In our Git/GitHub Workflow Activity we saw pull requests as one mechanism by which contributions from the community can be integrated into a project. The diff and patch tools provide another mechanism that many H/FOSS projects use to accept community contributions. For example, Freeciv has a patch process for accepting contributions.

This activity will give you some experience with diff and patch using a the modifications that you made to Freeciv in the Getting Around in a FOSS Project Activity.

Prerequisites

Before starting work through the tutorial below. The Hello World example will introduce you to the use of the unix diff and patch tools:

• HowTo Apply a Patch File To My Linux / UNIX Source Code by Vivek Gite.

Assignment

In this assignment you will practice creating and applying patches. In particular you will create a single file patch for the changes you made to the text.c file in Freeciv and then apply that patch to a clean copy of the project. You will then create a patch that captures all of the changes you made to the full source tree and apply that patch to a clean copy of the project.

Getting Started

Run make clean in the freeciv-2.1.9 directory.

Make two additional copies of the clean unmodified freeciv-2.1.9 directory.

cp -r freeciv-2.1.9 freeciv-2.1.9-one
cp -r freeciv-2.1.9 freeciv-2.1.9-two

You'll use these clean copies to test applying the patches that you create.

Making a Single-File Patch

If the changes you make are isolated to a single file it is often easiest to make a patch file for just that single file.

1. Create a patch file for the changes that you made to the text.c file.
   Tips:
   • diff -u orig-file mod-file > patch-file
   • Create the patch from within the directory containing the modified text.c file.
   • Use a relative path to the unmodified text.c file.
   • Redirect the patch output to a file in the parent of the freeciv-2.1.9-mod directory.

2. Look at the contents of the patch file and confirm that they agree with the changes that you made to text.c.

Applying a Single-File Patch

Before submitting a patch you should always test that everything goes ok when it is applied. We'll use the freeciv-2.1.9-one directory test the application of the patch you created.

1. Change to the freeciv-2.1.9-one/client directory.

2. Look at text.c and verify that it is the original unmodified version.
   Tips:
   • cat text.c | grep "infra"

3. Apply the patch to text.c
   Tips:
   • patch < patch-file
   • Use a relative path to the patch-file you created above.

4. Look at text.c and verify that the patch has been applied (i.e. that it now contains your changes).

5. Run make and ensure that the project is built (e.g. check the date stamp on the executables (ls -l). In practice you would now run any automated tests and also try the program to ensure that the changes you made are functioning properly. After that, you would submit the patch to the project.

6. Can you think of any advantages of using a single-file patch rather than just sending your modified file to the project manager?

Making a Project Patch

If you have made changes across a number of files in a number of directories within the project, creating one patch file that captures all of your changes is more convenient than creating many single-file patches.

1. Change to the parent of the freeciv-2.1.9-mod directory.

2. Create a patch for all of the changes that you made in freeciv-2.1.9-mod
   Tips:
   • diff -u -r -Xdiff-ignore-file orig-dir mod-dir > patch-file
   • Full project patches should generally be made from the parent directory of the modified source. This keeps the relative paths short and, as we'll see later, makes it relatively easy for the project managers to apply the patch.
   • The freeciv-2.1.9-mod dir contains a diff_ignore file that specifies files (e.g. .o files, executables, etc) that the project managers do not want included in patches.

3. Look at the contents of the patch file and confirm that they agree with the changes that you made. Notice that the paths to all of the changed files begin with freeciv-2.1.9-mod. Of course the project managers will not have this path in their projects. We'll see how they deal with that soon.

Applying a Project Patch

Like with the single-file patch, it is always a good idea to apply your patch to a clean copy of the project to be sure everything works. Note that this is also similar to what a project manager would do when they receive your patch.

1. Change to the freeciv-2.1.9-two directory.

2. Check a few of the files in the sub-directories of freeciv-2.1.9-two to verify that they are the originals and do not contain your changes.

3. Apply the patch.
   Tips:
   • patch -p # < patch-file
   • Use a relative path to the patch-file you created above.
   • Replace # with the number of prefix directories in the paths of the patch file that should be ignored. One in this case. This is how we tell patch to ignore the freeciv-2.1.9-mod directory and just use what follows (e.g. client, common, etc.). So in this case use -p 1.

4. Check a few of the files in the sub-directories of freeciv-2.1.9-two to verify that they now contain your changes.

5. Run make in the freeciv-2.1.9-two directory and ensure that the project is built.

Patches in a VCS

Many VCSs provide a mechanism for performing diffs and creating patch files between branches or repositories. For example, git provides git diff and git apply for creating and applying patch files. Svn provides the svn diff command that produces files that are compatible with the standard unix patch command. Those tools are beyond the scope of this activity, but keep them in mind if the H/FOSS project you work on accepts contributions in the form of patches.

Acknowledgements: This assignment builds from and adapts ideas and content from the following activities created by others:

• https://quaid.fedorapeople.org/TOS/Practical_Open_Source_Software_Exploration/html/ch-Fixing_the_Code.html