How to contribute to the source code

One of the greatest advantages of open source is the ability to view and modify the source code. This means diagnosing and fixing problems, or adding new features or documentation. In order to contribute these fixes/improvements to the project developers, you need to send them a patch file. The patch file (also called a patch for short) is a text file that consists of a list of differences between the modified code and the code in the developers’ repository. This file is created automatically using diff, a file comparison program that is present in every UNIX-like machine.

For the version control system we use Subversion, an application that automates the process of keeping an annotated history of the project, allowing reversion of code changes, and change tracking. A SourceForge’s server hosts all of the data files needed for version control, being the centralized resource of GNSS-SDR’s source code.

The repository is where all of the data is stored and where users go to access their data. Source code is tagged in time with the revision number. A revision is the contents of a repository at a single moment in time.  Any user can download a copy of the repository from a single revision (usually the current), which may be later modified. This local copy is called the working copy. Data is never edited in the repository directly, but in the user's working copy. To create a working copy, the user needs to perform a check-out. This takes a revision from the server and makes a local working copy with information used to relate the working copy to the server's repository.

Thus, in order to create a working copy, open a Terminal, go to your favorite directory (or better create one) and type:

$ svn co http://svn.code.sf.net/p/gnss-sdr/code/trunk gnss-sdr

Then, you can begin to modify the source code in your working copy. If, for some reason, you are interested in a certain revision which is not the current - say revision 665, the command is

$ svn co -r 665 http://svn.code.sf.net/p/gnss-sdr/code/trunk gnss-sdr

Before submitting a patch, please be sure that the list of differences is referred to the current version in the repository. Hence, update your working copy:

$ svn update

and then make your changes or resolve the conflicts. A conflict occurs when another developer have changed the same few lines of the same file than you since your last update. Whenever a conflict is reported (they are marked as ‘C’), you should open the file in question, and search for lines starting with the string <<<<<<<. The conflicting area is marked like this:

	<<<<<<< filename
	your changes
	=======
	code merged from repository
	>>>>>>> revision

Also, for every conflicted file Subversion places three additional files in your directory:

• filename.ext.mine This is your file as it existed in your working copy before you updated your working copy - that is, without conflict markers. This file has your latest changes in it and nothing else.
• filename.ext.rOLDREV This is the file that was the BASE revision before you updated your working copy. That is, it the file that you checked out before you made your latest edits.
• filename.ext.rNEWREV This is the file that your Subversion client just received from the server when you updated your working copy. This file corresponds to the HEAD revision of the repository.

At this point, you have three options for resolving the conflict:

1. Abandon your changes, and go with the current code of the repository.

This is the easiest solution. All you have to do is revert the changes you made, and update your working copy:

$ svn revert filename.ext
	Reverted 'filename.ext'

$ svn update filename.ext
	At revision NEWREV.

2. Keep your changes, and dump whatever it is in the repository.

$ cp filename.ext.mine filename.ext

3. Merge both versions to a new version

If you choose this option, you will have to manually edit filename.ext. Remove the markers and add whatever you need to add here.

Before creating the patch file, please be sure that after your modifications everything compiles and runs without problems, and clean up your work. Remove any junk lines or comments you may have left while fixing the code, and make sure your follow the recommended coding style for GNSS-SDR (indentation, white spaces, naming conventions and so on). This will make other developers’ life easier.

Then, run the diff subcommand of Subversion. The diff subcommand compares your local working copy to the repository and records the differences between them. This will generate the patch, so later the developers can add these changes to the developer's source code. To generate the patch file, go to the root directory of your repository and type:

$ svn diff > my_patch.txt

You can send patches to the developers mailing list or by using the ticket system at the SourceForge project site.

   Back to articles