3

Let us say I have an open source project on github. Now I wish to include tools required to develop the project so others can easily contribute. It is hard for me to tell when these tools should be included in the project for others to use and when they are a personal preference and part of my private development environment.

For example, I understand that a vim config file should not be part of the project as it is part of my editor of choice. I also understand that a Gemfile should be part of the repository as it is required to run the project. I have a problem where these two cross.

What about a Guardfile[1]? This file would automatically compiles/refreshes certain parts of the project if a specific command is called from the command line. Some few developers may have an IDE or substitute which already does this, however most would be happy to have a project-specific and tailored Guardfile.

Would adding such a file be alright or does it cross the line of the developers environment?

[1] https://github.com/guard/guard

2 Answers 2

3

It's part of your private environment. Most people want; some random tool like guard is not something I know or care about, nor want to use if for some reason it managed to be installed. I build projects by typing make, not automatically in the background.

However, I disagree that privately useful files should never be part of the repo. Many projects ship a vim file under tools/ or something. For purity, though, you may wish to put them in a separate repository, perhaps a submodule.

2

TL;DR

Canonical build or test files should always be included in the repository. Files that are expected to be customized by each developer should be included in a minimalist way within the repository, often in the form of example files.

Reasons to Include a Baseline Guardfile Verbatim

Files which are required to build or test your code base should be included in the repository. A Guardfile that contains customizations necessary to run your test suite properly, such as RSpec-related arguments, might therefore make sense as an integral part of the repository. However, the Guardfile should not contain personal preferences such as screen clearing or other per-developer customizations.

On many projects, a standard Guardfile may be a perfectly reasonable thing to commit, provided that all of the team members expect to use the same configuration. This will ensure that things "just work" after cloning, but at the cost of enforcing a vanilla configuration across all developer workstations.

Reasons to Include a Sample Guardfile for Customization

On projects where the customization of the Guardfile isn't needed, it makes sense to commit the Guardfile directly. However, on teams or projects where the Guardfile in use may vary between developers, it's often better to commit an example such as Guardfile.example that developers can then copy to Guardfile before editing it, ensuring that individual customizations aren't committed upstream.

Note that this approach also requires that the filename for customizations be added to the project's .gitignore file, or the equivalent for your SCM of choice. You will generally want changes to Guardfile.example to be committed for future users, but will not want each developer's customized Guardfile to be committed if they do something common like git add . when committing new work.

The downside of the example-file approach is that it requires a manual step by each developer to properly configure the tool-chain before first use. This adds to the cognitive load of bootstrapping the project, and can easily be forgotten or overlooked when cloning a project. Even if the step is documented in your readme, or your project includes some kind of setup script that includes a line like cp Guardfile{.example,}, having to rename or configure tool-specific configuration files like Guardfile or .rspec before being able to run your test suite properly the first time may violate the principle of least surprise for new team members.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.