Closely related to: Software development / Practices and philosophy
Software project management (Category )
[I have a couple]
Aliases: Source code collaboration, Accepting contributions to open-source projects, Soliciting contributions to open-source projects, Free and open-source software / Soliciting help, Fixing other people's code. See also: Patches
Join the Community The first step in community participation is to find a way to stay on top of the latest happenings. To do this most effectively, you will want to subscribe to the main developer discussion list (<firstname.lastname@example.org>) and commit mail list (<email@example.com>). By following these lists even loosely, you will have access to important design discussions, be able to see actual changes to Subversion source code as they occur, and be able to witness peer reviews of those changes and proposed changes. These email based discussion lists are the primary communication media for Subversion development. See the Mailing Lists section of the website for other Subversion-related lists you might be interested in. But how do you know what needs to be done? It is quite common for a programmer to have the greatest intentions of helping out with the development, yet be unable to find a good starting point. After all, not many folks come to the community having already decided on a particular itch they would like to scratch. But by watching the developer discussion lists, you might see mentions of existing bugs or feature requests fly by that particularly interest you. Also, a great place to look for outstanding, unclaimed tasks is the Issue Tracking database on the Subversion website. There you will find the current list of known bugs and feature requests. If you want to start with something small, look for issues marked as “bite-sized”. Get the Source Code To edit the code, you need to have the code. This means you need to check out a working copy from the public Subversion source repository. Become Familiar with Community Policies Now that you have a working copy containing the latest Subversion source code, you will most certainly want to take a cruise through the HACKING file in that working copy's top-level directory. The HACKING file contains general instructions for contributing to Subversion, including how to properly format your source code for consistency with the rest of the codebase, how to describe your proposed changes with an effective change log message, how to test your changes, and so on. Commit privileges on the Subversion source repository are earned—a government by meritocracy.  The HACKING file is an invaluable resource when it comes to making sure that your proposed changes earn the praises they deserve without being rejected on technicalities. Make and Test Your Changes With the code and community policy understanding in hand, you are ready to make your changes. It is best to try to make smaller but related sets of changes, even tackling larger tasks in stages, instead of making huge, sweeping modifications. Your proposed changes will be easier to understand (and therefore easier to review) if you disturb the fewest lines of code possible to accomplish your task properly. After making each set of proposed changes, your Subversion tree should be in a state in which the software compiles with no warnings. Subversion has a fairly thorough  regression test suite, and your proposed changes are expected to not cause any of those tests to fail. By running make check (in Unix) from the top of the source tree, you can sanity-check your changes. The fastest way to get your code contributions rejected (other than failing to supply a good log message) is to submit changes that cause failure in the test suite. In the best-case scenario, you will have actually added appropriate tests to that test suite which verify that your proposed changes work as expected. In fact, sometimes the best contribution a person can make is solely the addition of new tests. You can write regression tests for functionality that currently works in Subversion as a way to protect against future changes that might trigger failure in those areas. Also, you can write new tests that demonstrate known failures. For this purpose, the Subversion test suite allows you to specify that a given test is expected to fail (called an XFAIL), and so long as Subversion fails in the way that was expected, a test result of XFAIL itself is considered a success. Ultimately, the better the test suite, the less time wasted on diagnosing potentially obscure regression bugs. Donate Your Changes After making your modifications to the source code, compose a clear and concise log message to describe those changes and the reasons for them. Then, send an email to the developers list containing your log message and the output of svn diff (from the top of your Subversion working copy). If the community members consider your changes acceptable, someone who has commit privileges (permission to make new revisions in the Subversion source repository) will add your changes to the public source code tree. Recall that permission to directly commit changes to the repository is granted on merit—if you demonstrate comprehension of Subversion, programming competency, and a “team spirit”, you will likely be awarded that permission.
Now is a fantastic time to follow Ruby’s development, with Ruby 2.0 development underway. With the increased attention Ruby has received in the past few years, there’s a growing need for good talent to help enhance Ruby and document its parts. So, where do you start? The topics related to Ruby development covered here are:
- Using Subversion to Track Ruby Development
- Improving Ruby, Patch by Patch
- and, Rules for Core Developers
Improving Ruby, Patch by Patch
Rubyforge maintains a bug tracker for submitting patches and bug reports to Matz and the gang. These reports also get submitted to the Ruby-Core mailing list for discussion, so you can be sure your request won’t go unnoticed. You can also send you patches straight to the mailing list. Either way, you are encouraged to take part in the discussion that ensues.
To summarize, the steps for building a patch are:
1. If you are fixing a bug in Ruby 1.8, check out a copy of Ruby 1.8 from Subversion using the ruby_1_8 branch.If you wish to add a feature to Ruby, check out the trunk of Ruby’s source. Even if you wish to add a feature to Ruby 1.8, it has to be proven in the trunk first.$ svn co http://svn.ruby-lang.org/repos/ruby/trunk ruby
2. Add your improvements to the code.
3. Create a patch.$ svn diff > ruby-changes.patch
4. Email your patch to the Ruby-Core mailing list with a CHANGELOG entry describing the patch.
5. If there are no issues raised about the patch, committers will be given the approval to apply it.
Please note: patches should be submitted as a unified diff. For more on how patches are merged, see the diffutils reference.
Discussion of Ruby’s development converges on the Ruby-Core mailing list. So, if you are curious about whether your patch is worthwhile or you want to spark a discussion about Ruby’s future, don’t hesitate to come aboard. Be warned that off-topic discussions are not tolerated on this list, the noise level should be very low, topics should be pointed, well-conceived and well-written. Since we’re addressing Ruby’s creator, let’s have some reverence.
Keep in mind that Ruby’s core developers live in Japan and, while many speak very good English, there is a significant timezone difference. They also have an entire body of Japanese development lists happening alongside the English counterparts. Be patient, if your claim isn’t resolved, be persistent—give it another shot a few days later.
http://blog.hasmanythrough.com/2007/5/24/laying-tracks-slides has_many :through: Laying Tracks slides [have not watched]
http://dev.rubyonrails.org/ Rails Trac
Checking out the source
The Subversion repository resides at http://svn.rubyonrails.org/rails
Check out the current development trunk (Edge Rails) with:
If you'd rather work with Rails' stable branch:
Creating a patch
Tickets are fine, but patches are great. If you want to modify Rails or fix a bug you've run across, there's no faster way to make it happen than to do it yourself. Rails thrives on the generous work of contributors from around the world. Please become one of them.
- Get Rails ready for patching
- Check out the latest source: svn co http://svn.rubyonrails.org/rails/trunk
- Ensure that the existing unit tests pass.
- Make a test-driven change
- Add or change unit tests to prove that your change works.
- Make the change to the source.
- Verify that all tests pass by running rake. Run tests for a specific database using, for example, rake test_oracle. See rake --tasks for more.
- Share your well-tested change
- Sanity check the changes you've made: svn status
- Create a patch: svn diff > my_descriptively_named_patch.diff
- Login to Trac or register a new user.
- Create a new ticket with [PATCH] as the first word in the summary. Attach your patch file.
- Keep an eye on the ticket and address concerns that arise. Make your change hard not to commit.
- Bask in the glory of being a Rails contributor!
- Two spaces, no tabs
- Don't use and and or for boolean tests, instead always use && and ||
- MyClass.my_method(my_arg) -- not my_method( my_arg ) or my_method my_arg
- Follow the conventions you see used in the source already
Create New Ticket
Before submitting a ticket, make sure that the fault, request, or patch has not already been reported. Use the search to look for keywords or investigate the lists. Then make sure that you're as specific as possible. Give sample code whenever possible and be sure to explain both why and how you need or have done something. We're looking for rationale. This is broken because I wanted to do X, or, this patch adds Y to make this piece of code pretty.
For both bugs and new features, it's strongly recommended that you supply test cases. The chances that a patch will receive attention increases exponentially when test cases are present.
1. Get annoyed by a defect or missing feature
Open source software isn’t written by an army of coders, with a back up army of testers, documenters, and “Dummies Guide” book authors. Rather, its code that fixed the author’s problem; and they were nice enough to flesh it out generically so you could use it. Or they were seeking fame and glory.
So you find problems. The project owner and all its users will be super grateful if you fix it for them.
2. Finding the source
The modern Ruby community uses subversion/svn for their source repositories. So now is your excuse to install it and start to learn how to use it.
The tricky part is “where is the repository?”
If the project has a RubyForge project go to (if its URL is http://XYZ.rubyforge.org, then its project page is http://rubyforge.org/projects/XYZ) then try the “SCM” tab on the project page. If the project isn’t hosting on RubyForge SVN, hopefully they have disabled this menu tab. If not, you’ll get version 0 when you do the checkout to tell you the project’s not hosted here.
Alternately, the project’s homepage/Readme file should tell you where the repository is.
Finally, email the project owner. And tell them to get their act together and publicise their SVN repos.
3. Check out the source
Hopefully you’re told the complete URL to the trunk of the project. For anonymous access to the newgem RubyForge project the URL is svn://rubyforge.org/var/svn/newgem/trunk
A project SVN repository might contain multiple projects, and may or may not use the common trunk/branches/tags root folders. So you may need to navigate around the repository and til you find the trunk of the project’s code.
So for a generic RubyForge project, the root URL for anonymous access is svn://rubyforge.org/var/svn/XYZ.$ svn list svn://rubyforge.org/var/svn/newgem branches/ tags/ trunk/ $ svn list svn://rubyforge.org/var/svn/newgem/trunk History.txt …
If there is a trunk root folder, then do the following:rm -rf XYZ svn co svn://rubyforge.org/var/svn/XYZ/trunk XYZ cd XYZ
And now you’ve checked out the trunk or “edge” of the project. The latest and greatest.
4. Snoop around
Load up the project into your editor and poke around.
If it has test cases (!) try running them. You may need to create some databases and/or modify the Rakefile/connection details to work with your database. Hopefully the project comes with rake tasks to create/drop the databases. rake -T should find them.
If its a RubyGem, try installing the gem locally (on top of the existing defective gem that you’re about to fix). Again, run rake -T and hopefully there is a task install_gem or similar to build and install the gem from source. If not, send hate mail to the author. And then fix the Rakefile to use the Hoe gem. And then send a patch to the author with the fixed Rakefile.rake install_gem
5. Make changes
Finally, you get to change their code.
If the project has a suite of test cases, please make an effort to add “failing test cases”. That is, add test cases that demonstrate the defect by failing (unless the project includes your fix).
Run the tests to ensure they are working. 6. Refresh the code from the repository (svn up)
The original repository may have changed since you did the checkout, so update your version.svn up
If there are any conflicts, go fix them and delete any helper files created by SVN.
7. Create the patch
First, you need to tell subversion about any folders/files you’ve added (svn add) or deleted (svn remove).
Then, from the root folder of the trunk:svn diff > i_fixed_a_bug.patch
Give the patch file a useful, readable name. Like readme_updated_for_rdoc_syntax.patch.
Each project may have a different preferred way to submit patches.
8a. Submit patch to trac
If the project uses trac then:
- Register an account (normally a link at the top right of the page) if available. Some trac installations require an account (e.g. Rails) and others allow anonymous tickets.
- Click “New Ticket”
- Fill in details (note, there is nowhere initially to add your patch). Prefix the subject with [PATCH]
- Save the ticket (check the box “Attach files”)
- Attach the patch file and save
8b. Submit patch to Google Groups
Projects hosted on rubyforge SVN cannot use trac. I personally use Google Groups for my projects – the project communities are all small enough such that its manageable.
- Join the Group (using Google Account)
- Add a picture to your Google Groups account; I cannot communicate how relatively unnecessary this step truly is
- Go to Files section (link on right hand side)
- Attach your patch file to the group
- Get the URL for the uploaded file
- Post a note/write an email to the group describing your patch, and include the URL for the patch file
8c. Submit patch to RubyForge Tracker
RubyForge offers a bug/patch/feature request tracker for each Project. It is enabled by default for new projects:
- Log in or Create new Rubyforge account
- Go to project page and click “Tracker“ from sub-menu
- Click “Submit New”
- Fill in details (each RubyForge Project can contain many sub-projects/gems - pick from Category drop-down)
- Check the box “Check to Upload & Attach File”
- Browse and select your patch file; put file name in File Description field as you’ve already made it human readable, because you’re a champion.
- Save the ticket
8d. Submit patch to LaunchPad Tracker
“I have to say I quite like Launchpad, now that I’ve got used to it. If you’re an Ubuntu guy like me then it is perfect.” - from Neil Wilson
- Log in to/Register for your Launchpad account
- From The Launchpad bug tracker click the Report a bug button.
- Enter the name of the project, or select it from the list.
- The project in question will almost certainly provide its own bug reporting link that takes you directly to the Report a New bug page.
- Enter a one line summary and click Continue
- Fill in the comment box and click Submit Bug Report
- Then click the link “Add a comment/attachment”, and Browse for the patch file. Check “This attachment is a patch” and add a Description if required.
- Click Save Changes
8z. Email the project owner
See title: Email the project owner. Prefix the subject with [PATCH].
Why 8z? I figured readers might want to share other ways they coordinate within a project, like Google Code, etc. I haven’t used it. So, (c) - (y) are placeholders :)
Corollary: Tell users how to fix problems
If you administer some OSS projects, you are doing yourself a disservice not telling your users how to quickly, easily submit patches.
Either copy and paste the relevant sections above, and/or link them to this “8 steps” page.
Make it really clear on your project website that patches are welcome and will be rewarded with free t-shirts and other complimentary items of stationary, and watch those patches roll in.
If you find a bug in readline, you should report it. But first, you should make sure that it really is a bug, and that it appears in the latest version of the readline library that you have. Once you have determined that a bug actually exists, mail a bug report to firstname.lastname@example.org. If you have a fix, you are welcome to mail that as well! Suggestions and ‘philosophical’ bug reports may be mailed to email@example.com or posted to the Usenet newsgroup gnu.bash.bug.
Building Your Own
The source is GPL’d, so feel free to chip in, add on, take off, or… you know, whatever. You’ll need Microsoft Visual Studio .NET 2003, though, or SharpDevelop and a willingness to maintain your own project files and build configs. Please send me the changes if you add anything useful, and I’ll give you credit.
Why not? Because there's a good chance it has been fixed in more recent releases.
I was excited to see that Ubuntu's crash detector/reporter actually enforces this policy: when xbindkeys-config crashed on me, it gave me the option to "Report bug", which I clicked. But then it told me I couldn't report a bug because I had old versions of certain libraries (like libc, etc.).
This is a good thing. Not because submitting bug reports is a bad thing in itself. But because developers should be fixing bugs in current releases (and providing an easy upgrade path), not maintaining old releases.
[With PayPal Donate button] Anything on this website is provided absolutely free. If you feel like supporting me by paying me a beer or two, by all means do so by using the PayPal donate button. Also, good ideas and bug reports are always welcome.
What should be done with every release?
What should be included in every release?
One approach to doing a change log (that I'd never seen before) is to literally list (as diffs) every single change that has been made to the source code. This appears to be what the author of tar2rubyscript did on this page: http://www.erikveen.dds.nl/tar2rubyscript/diverse/history.txt.html
It's a nice colorized list of unified diffs, with dates ranging from 2003 all the way to 2006.
Raw and verbose, but kind of neat!