Gem behavior differs depending on whether it is run with 'rake erd' or 'bundle exec erd'

[cherimarie]

This is confusing!

example: Configuration settings must be prepended with '--' for 'bundle exec erd', but not with 'rake erd' bundle exec erd --attributes=false --orientation=vertical Valid! rake erd attributes=false orientation=vertical Valid!

bundle exec erd attributes=false orientation=vertical Invalid :( rake erd --attributes=false --orientation=vertical Invalid :(

example: Orientation option does nothing when included in 'bundle exec erd', but does alter results when included in 'rake erd'.

Possible solutions:

• update documentation to clearly explain expected behavior with the different commands
• update gem so that behavior is the same no matter how it's run

Updating documentation is relatively straightforward, so seems a good place to start.

Are these differences in behavior intentional? Is eliminating them desirable?

[kerrizor]

I believe the difference here is that bundle exec erd executes using the erd compiled binary file (the result of running rake build if you want to test this locally) while rake erd runs the Rake task found in lib/rails_erd/tasks.rake#generate which handles options differently (accepting environment variables, for example..)

This /is/ a little weird. We use the gem choice to handle the command-line arguments; could it be used to handle the -- prepended options for the Rake task?

[kerrizor]

Alternatively this might just need some better documentation.

[patrickdent]

In today's investigation, we've found that only the 'bundle exec' command (defined in cli.rb) uses the choicegem. The 'rake' command (defined in tasks.rake) does not. The fact that these commands each have their own file defining behavior explains why there are differences!

Each file handles options completely differently. Getting them to both take the same options seems prohibitively difficult; we suggest removing the bundle exec method of running rails_erd and reserve it as a rake task. This will have the added benefit of making the project easier to maintain, and will keep functionality more consistent.

We suggest removing bundle exec because:

1. the previously mentioned bug with the orientation=vertical option
2. the rake task is much easier to read an understand for future developers
3. with the rake task you can set options in your ENV variables to automatically produce the desired erd without passing in command line options
4. the rake file checks the options passed against the options defined within the project , this doesn't require maintaining the choice gem's options config

Is there any additional functionality with bundle exec erd that we didn't see, or any other reason to maintain these two processes side-by-side?

[kerrizor]

After looking at the implementation, I think we do need to narrow the "surface area" here.

I'm reluctant to remove the binary ($ bundle exec erd or simply $ erd) because

• preferences and config files for repeatable/comparable ERD generation was strongly desired by many users
• setting preferences via environment variables is cumbersome
• having a binary removes the need to actually install the thing into your project

I'm reluctant to remove the rake task because

• it is somewhat easier to automate for post-CI builds or as part of rake db:migrate
• it feels a bit more accessible and expected to add rake tasks, and sets a pattern for hooking into existing tools

I believe we could refactor the rake task(s) to align with the command line tool in terms of what is executed, either by simply running the same command and interpreting environment variables into choice options, or by actually attempting a system call (somewhat inadvisable, but we can experiment.) This would let us keep both methods in place for the differing use cases. Thoughts?

[darylf]

I almost opened an issue regarding the difference in the documentation between the README suggesting bundle exec erd, and the documentation suggesting rake erd

It sounds like the documentation should clarify which way is the preferred way, but I'm not sure if the 2.0 documentation has been unified already.