Handling Third Party Contributions

(Ref Id: 1348684771)

The most common way to tell the world that your project is a DIY is to publish it to a public code repository. This works for your core team -- for people that you know -- but what about third party developers? They do not have write access to your code repository. Third party developers can typically only download a read-only version. How can they submit a bug fix or an enhancement to the original development team? They either need to submit a patch or, in Git parlance, submit a pull request.

Simple Method: Tar

Before considering either of these methods let's consider the simplest way to submit a patch: send the entire updated files with an explanation of what was changed, perhaps stored in a zipped archive. In this case the original development team will need to take all of your files, add them to a sandboxed copy of the release, and then run a diff comparison against a clean copy of the core release to see what you have changed.

If you are using Windows you can still follow along with this tutorial but you should install UnxUtils first. Note, the tar.exe in the UnxUtils toolkit is a mess. The archiving instructions listed later will not work with it. You'll need to find a working Tar port for Windows. Let's assume we have two folders -- one called src/ with the original, unmodified source from the release and another folder, srcalt/ with our modified source.

diff -rq src/ srcalt/ > tar.list
cat tar.list

At this point we have a file called tar.list that contains lines that look like this:

Files src//folder1/foo.cpp and srcalt//folder1/foo.cpp differ
Only in srcalt//folder2: foo2.cpp
Files src//folder2/foo.cpp and srcalt//folder2/foo.cpp differ

These lines tell you which files are different in the two releases. It also tells you if you added files. Edit the file using your favorite editor to remove everything except the file names in the locally modified folders (the ones in srcalt/ above). You only want the files on the right in the tar.list file:

srcalt//folder1/foo.cpp
srcalt//folder2/foo2.cpp
srcalt//folder2/foo.cpp

Now run your Tar utility to create an archive with just these files:

tar -zcvf soandsosystem-v3.0-patch.tgz -T tar.list
tar -vf ./so
andsosystem-v3.0-patch.tgz --list

Now you have an archive with your new files. You can create a problem ticket (or use an e-mail if that is okay) to communicate your files with the core development team and attach this archive. I would mention that you have included whole files in your patch archive and not a diff as it was easier for you to do.

Diff/Patch Method

The first method is fine if the core developers receive one or perhaps two patches of this variety, but the entire process can become unwieldy when receiving numerous patches. Some projects will not accept patches submitted in this fashion.

Since we are only considering two version control systems to solve this problem for the sake of brevity, CVS and Git, this method should be used for organizations using a version control system that is more like the former. According to one online resource, CVS "doesn't offer any tools to help with accepting contributions (via patches) from people without commit access." So for CVS and similar systems we will use two common Linux tools, diff and patch.

Before doing anything, verify that you have diff and patch on your system (Windows users: you have to open a command prompt to do this). Try:

diff -v
patch -v

You should see the version information for both utilities. If you don't see version information you will need to install one or both of them prior to continuing. FYI, you can get a copy of patch for Linux from GNU.org if for some reason yours is not working.

There are various methods for submitting patches when it comes to multiple files. Some projects publish the method they would like you to use. If their method differs from this one, use their method. Here is how you create a simple patch for a series of files in separate folders:

diff -rupN src/ srcalt/ > src.patch

The patch file is human-readable so you can take a look (just do not modify anything). It will contain the changes not only to those files that were modified but it will contain the entire contents of any brand new files you added.

The main project can then run the following to add your patch to the main code repository:

patch -p1 < src.patch

If the core maintainers receive too many patches (or yours does not make the cut for some other reason) yours might get skipped. In this case the patch file will no longer be valid for the latest release. This is why it is important to incorporate the name and version of the product being patched in your patch file name. So instead of src.patch above you would make the name so_and_so_system-v3.0.patch. If your patch is not accepted then obtain the latest version of the source, check to ensure that your patch is still needed, and try again.

Switch to Git

The final method is to use pull requests on projects where the core development team is using Git, particularly projects that are using Github.

There is actually a fairly good help page on Github purely on collaboration using pull requests so there is not need to repeat it all here. The point is that a pull request is part and parcel of the way Git handles collaboration. Third party developers can fork the entire project, modify it, and then submit a request for the core team to adopt those changes.

Not every project uses Git, so you still have to learn the old way of submitting patches specified earlier.

Go Back

Citation: Handling Third Party Contributions. (2012). Retrieved Sun Oct 22 02:24:40 2017, from http://www.limsexpert.com/cgi-bin/bixchange/bixchange.cgi?pom=limsexpert3;iid=readMore;go=1348684771