What is a software patch?

by Ross Gardler on 7 January 2008 , last updated 8 November 2013

Introduction

A patch is a record of changes made to a set of resources. Typically a patch will add a new feature, fix a bug, or add documentation to the project. A popular means of creating a patch is by using diff, a tool that is commonly available on Linux and Unix systems.

Patches are often the preferred way to submit contributions to open development projects such as open source software, particularly when a project is using a centralised version control system (VCS) and the contributor does not have commit rights. Projects using a distributed version control system (DVCS) may prefer contributions to be submitted as pull requests.

When using patches, the contributor creates a patch and submits it to the project. The project maintainer can then inspect the changes and apply them to the main code base if they so choose. Various tools are available to help with patches. These tools make it very easy to create and manage patches for project outputs such as source code and documentation. Patches and patch management tools are the key to building an active community of contributors to an open development project.

This document provides a simple overview of a software patch. It does not deal with the mechanics of creating and processing patches, which are better handled by the documentation of the patch management tool chosen. In the further reading section, we list a few tools to help you get started with creating patches.

Creating a patch

When a contributor makes a change to the outputs of a project they do so by editing files available in a version control system. A version control system tracks changes to documents and source code over time. Using one makes creating a patch simple because you can always refer to the version of the source code the changes are based upon. However, there are a few steps that should be taken to maximise the chances of the patch being accepted by the maintainers of a project.

It is important that the contributor ensures that the patch complies with any documentation and coding standards adopted by the project. It is also critical to thoroughly test changes against any test suites the project provides. Finally, each contribution should be clearly documented with, at a minimum, details on:

what it is intended to do
how it is implemented
how it is used

Once the contributor is satisfied that the patch is worthy of consideration by the project maintainers, a patch must be created.

How the contributor creates the patch depends on which development environment they are using and on which version control system the project is using. Most Integrated Development Environments (IDEs) include a feature to generate a patch. There are also many tools you can install, providing command line or GUI interfaces to patch generation tools.

After running the chosen tool, one or more files will be produced. Collectively, these files describe the changes made in the contribution. Often multiple files will be placed into a single archive file for ease of management. This archive is called a patch. It is this patch that a contributor submits to the project.

The actual submission process varies from project to project, but in all cases there will be a requirement to address the assignment of copyright or rights to use the IP contained within the patch. This is discussed further in Contributor Licence Agreements.

Applying a patch

Once a patch has been submitted by a contributor, it is then the responsibility of the project maintainers to evaluate and, where appropriate, apply the patch. Different projects have different approaches to reviewing and applying patches. However, they all have some common steps:

quickly evaluate the value of the patch
prepare prompt and accurate feedback to the contributor (requesting a resubmission where appropriate)
experimentally apply the patch
run any test suites against changed code
report any problems to the contributor and request a resubmission
commit the patch to the version control system

Skilled developers can read patch files and understand their implications without actually applying them to the code base. This makes it easy to provide rapid feedback to the contributor. Should the project maintainer feel that the patch looks like a solid contribution, they will apply it to their local development copy and test it. Since a good contribution will already have undergone extensive testing, this should be a simple matter for the maintainer. However, mistakes can be made and so further testing should always be carried out.

Once a patch is ready to be applied to the version control tree, the maintainer will ‘commit’ it. That is, they will make it available in the public version control system. This action will usually result in an automated notification to the developer community via a ‘commit’ email list. At this point, the wider community is given the opportunity to review the contribution; if the change is in response to a bug report or a feature request, the associated ticket in the issue tracker should be updated.

Is it really that simple?

For things to work as smoothly as described above, it is important that contributors create patches against a recent version of the project outputs (usually software code), preferably the most recent version, from the ‘head’ of the version control system. This is because, as time passes, code will evolve. If the code in question has changed since the contributor downloaded their copy, applying the patch may not be as simple as described above, since there may be conflicting changes.

Since users often want to work with a stable version of the code in a production environment, it is possible that the initial changes were not made against the latest development version of software. This creates a dilemma for the contributor: do they contribute a patch against an old version of the code, or do they invest the time in creating a patch against the latest development version?

In order to maximise the chances of a patch being accepted, the contributor should submit the patch against the latest development version. Therefore the contributor should have a development copy of the project deployed and ready to test against. All contributions should first be applied to this development version, and any further changes necessary to ensure it works as expected should be made.

Having a development environment deployed like this has the added benefit of allowing the organisation to test current development versions in a non-critical environment. This, in turn, helps with the decision to upgrade or not when a new release is available.

Failure of contributors to create patches against the latest development version of a project will increase the amount of time a maintainer needs to invest in reviewing and applying the patch. Consequently, the chances of its being accepted are significantly reduced. Rejection will not prevent the contributor’s organisation from using the patch, but it will mean that an upgrade to future releases is made more complicated, since their local modifications will have to be reapplied to new releases. Consequently, putting the effort in at an early stage will reduce the effort to upgrade and thus make it more likely that an upgrade will go smoothly.

Even though it is advisable for contributors to work against the latest development resources, projects should still be willing to consider patches against older versions. A patch against an old version is better than no patch at all. Whether such a patch is applied or not depends on the community and on the perceived value of the patch. An important feature addition or a bug fix is likely to be applied, whereas a niche feature may be ignored as there may be no active developers with a need for that feature.

Release early, release often

To minimise the chances of users submitting patches against an outdated release, open development projects should release early and release often. In teh early stages of a project, the more frequent the project releases are, and the easier the upgrade path, the more likely users are to move to a new version. Consequently, they are more likely to provide patches against a more recent code base. Looking after users in this way ensures that the project enables users to become valuable contributors with minimal effort.

The more contributors a project has, the more likely it is to survive. For open source projects, building and maintaining an active community are vital for sustainability.

Why should I contribute a patch?

Some people wonder why they should put the effort into providing a patch. They may consider it additional work over and above the development effort of making the modifications in the first place. However, there is purely selfish benefit in creating and submitting a quality patch: it makes it easier to maintain your use of the project outputs.

At some point in the future an organisation is likely to want to use the latest and greatest release of the project outputs. If that organisation’s staff has failed to work with the community in order to have their local modifications accepted, they will need to reapply all changes, or lose them. That is, the organisation will be paying its staff to make each change twice.

It is easy to ignore this fact. After all, each change seems insignificant and easy to reapply. However, each change is cumulative, and since the project has been progressing independently of your changes, it is quite possible that the application of your modifications will no longer be a simple activity.

Submitting a patch to a project does not guarantee that it will be included, but it certainly increases the chances, especially if staff are encouraged to work with project maintainers to ensure the patch is compatible with the objectives of the project. It is rare for projects to refuse patches outright; any refusal is usually accompanied by recommendations for ways to make it acceptable to the community.

Ultimately, the act of providing patches to projects ensures that an organisation has a cheaper upgrade path and it makes it easier to create releases. At the same time, they help to ensure that the software they depend on remains in active development. Mark Johnson showed in his presentation at TransferSummit/UK 2010 how rewarding it can be to provide patches and become active in an open development project. As such, it is a great way of helping build community around your project.

OSS Watch provides unbiased advice and guidance on the use, development, and licensing of free software, open source software, and open source hardware.