Do you want to contribute something to the rails_apps_composer gem? Here’s how you can help.
We realize it is important to respond to your issues and contributions as quickly as possible because it shows we care about your efforts and keeps the project alive and growing.
The current maintainer for the project, Daniel Kehoe, works fulltime on the RailsApps project, which includes updating the rails_apps_composer gem as well as maintaining example applications and writing tutorials.
He will try to respond as soon as possible, whether you send an email, make a pull request that corrects an error, or contribute a new feature.
In general, he updates the rails_apps_composer gem approximately monthly. His priority is fixing bugs that impact large numbers of users, as well as adding features that directly support creation of the RailsApps example applications.
We love to receive pull requests for new recipes and significant new features. However, it is not always possible to evaluate and include significant new contributions right away, as much as we might like to. So we ask for your patience as we work through any backlog.
Be sure to carefully read the section in the Guide to the Rails Apps Composer Gem titled Hacking the Gem.
The rails_apps_composer gem is complex and unwieldy but it is documented thoroughly.
The primary purpose of the rails_apps_composer gem is to automate the maintenance of the RailsApps example applications. Each of the RailsApps example applications are generated by the script we call the Rails Composer tool. The Rails Composer tool is actually a Rails application template generated by the rails_apps_composer gem.
The rails_apps_composer gem creates the Rails Composer application template from a predefined set of recipes, notably the railsapps.rb recipe but also others. Choosing “core” creates the Rails Composer application template, as seen here:
$ rails_apps_composer template ~/mypath/railsapps/rails-composer/composer.rb -r core
Each time we release a new version of the rails_apps_composer gem, we generate and release a new version of the Rails Composer tool. Often, at the same time, we generate new versions of each of the RailsApps
example applications using the new Rails Composer application template. Then we run tests on each of example applications.
It’s important to realize that the RSpec tests built into the rails_apps_composer gem are NOT adequate to ensure that all the example applications run without problems. The only way to know for sure that changes to the rails_apps_composer gem have not broken any example applications is to regenerate each example application and run its test suite. We do not have an automated test suite to test them all.
That is one reason why there is often a delay between the time you submit a new feature and the time it is released as part of the rails_apps_composer gem.
Many developers use the rails_apps_composer gem to create their own application templates. This includes consultants and enterprise developers who maintain their own preferred starter applications. In general, if new features are significant and useful to the community, we will include them in the gem, even if they are not used by the RailsApps example applications.
Many more developers use the “generic” Rails Composer tool to generate starter applications. The Rails Composer tool will create any of the RailsApps example applications. It also has a “build your own application” option.
The “build your own application” option is largely experimental. There are some combinations of options that may not work together. We like to debug the problems and include fixes in the rails_apps_composer recipes when we encounter these integration issues.
Reporting an issue on Github is one of the simplest ways to contribute. Reporting issues (and fixing!) helps everyone.
When you generate an application, the application’s README.textile file will contain a diagnostics report. Please include the diagnostics report when you create an issue on GitHub.
GitHub helps you make improvements to the project by allowing forking, branches, and pull requests.
Forking means you make your own version of the repository so you can make changes.
Branching means you separate your fix or a feature from the main trunk of the code so we can examine and test your fix or a feature in isolation before adding it to the trunk.
Pull request means you tell us that you have a fix or a feature to add.
See a helpful article on how to fork, branch, and make a pull request.
Fork the rails_apps_composer repository, get your copy into your local environment development, and configure so you can track changes to the original repository.
Click the “Fork” button you see in the rails_apps_composer repository. Then:
$ git clone [email protected]:username/rails_apps_composer.git $ cd rails_apps_composer $ git remote add upstream [email protected]:RailsApps/rails_apps_composer.git
Branching allows you to build new features or try out fixes without mixing your code with the main trunk of the project.
If your fix is very tiny, like correction of a typo, you don’t need to create a branch.
For fixes or features of any complexity, you must create a branch so we can examine and review your code before we add it to the main trunk.
GitHub explains how to create a branch from your web browser but it is easier to do it from the command line after cloning the project to your local machine.
Here’s how to create a branch from the command line:
$ git checkout -b myfeature
The command creates a new branch named “myfeature” and switches to it, analogous to copying all your files to a new directory and moving to work in the new directory (though that is not really what happens with Git).
As soon as you’ve created your new branch, push it to your GitHub fork:
$ git push -u origin myfeature
The branch is now on GitHub as well as on your local machine.
You can see a list of all your branches:
$ git branch
Make your changes, then commit your changes to git:
$ git add -A $ git commit -m "work in progress"
You can make multiple commits as you continue your work.
When you’ve completed your work, be sure to push the changes in the branch up to GitHub:
$ git push origin myfeature
Now your fork on GitHub has a branch with your changes and you can make a pull request.
Make a GitHub pull request to tell use about your new feature or fixes.
On GitHub, visit your forked version of the repository and select the branch you’ve created.
Above the list of files and the information about the most recent commit, you’ll find a gray bar that includes the “Pull Request” link. Click “Pull Request” and GitHub will show you a review of all the differences between your version and the original.
Click the message “Click to create a pull request for this comparison.”
Enter a message describing your work and click the button “Send pull request.”
The maintainer of the project will immediately receive an email message that you’ve made a pull request.
It could be a few hours or a few days before you hear from the maintainer. We promise we’ll reply as soon as we can.
No matter what you’ve contributed, small fix or large feature, you have our grateful appreciation for your interest and help.
If you continue to work in your branch after making a pull request, the changes will be reflected in the pull request until it is accepted.
If you created a working branch, you can delete it after the pull request is accepted:
$ git branch -D myfeature
If you can write a test suite for the changes you’ve made, it would be very much appreciated.
That said, if you are not experienced at writing tests, your contributions are still welcome.
Enter rake spec to run the existing test suite.
The existing test suite is primarily a “sanity check” to make sure recipes conform to general requirements.
The test suite does not test if the recipes actually generate working Rails applications.
At this time, it’s necessary to individually test any applications generated by the rails_apps_composer gem. Sad to say, that means regression testing of the rails_apps_composer gem has to performed manually.
It is your responsibility to help update the documentation if you have contributed new features or changed the behavior of existing functionality.
At a minimum, you must indicate where the documentation should be changed, both in the README and in the
Guide to the Rails Apps Composer Gem.
We’ll help with the documentation but you must help by giving us something to start with.
Please follow the coding conventions used throughout the project (indentation, comments, etc.).
If you need guidance, check the ruby-style-guide.
We try to mention all contributors in the CHANGELOG file (and we apologize if we’ve overlooked anyone).
If you need an additional acknowledgment, for example if you’d like to be cited for recognition by consulting clients, prospective employers, or your school, drop the maintainer an email.