X.Org uses patches to do code development. This page describes the required format of a patch as well as the workflow to create, send and apply it. We assume you have a git cloned repository and are familiar with making code changes and commits.

Take a look at this example commit from which this patch has been created. Open them in separate browser windows and refer to them while you read the rest of the page.

Workflow overview

Note: This workflow illustrates the lifecycle of a patch and does not constitute a development process. If you intend to develop patches for the X Server, consult their development process.

The patch submitter does the following:

The xorg-devel list reviewers do one of the following:

  • Signify their approval or disapproval (Acked-by or Nacked-by)
  • State an opinion about the appropriateness of the patch (Reviewed-by)
  • Test the patch (Tested-by)

The module maintainer does the following:

  • Obtain the patch from the bug report or from the xorg-devel list
  • Apply the patch to a local repository using the git-am command
  • Push the patch to the git remote repository using the git-push command

Making code changes

This is where it all starts. Think about the reviewers when you are organizing code changes. Focus on one issue and change one or more files to resolve the issue. In our example patch, the code change only deals with fixing the wrong behavior of the mouse buttons reported by the user.

Changes should follow the coding style guidelines.

Before creating a commit, ensure your git user name and e-mail is configured correctly using the git-config command. Use your real name as opposed to a nickname as you will be signing off your patches, indicating that you are able to release the patch under the licensing terms of the module.

$> git config --global --get user.name
$> git config --global --get user.email

Creating a commit

Once the code changes are implemented and tested on your local repository, they must be committed. A commit object is created which wraps your code changes with various git information. It is included in the patch you will create later. Nothing is sent to the remote git repository on the freedesktop.org server.

You tell git to add the files you changed using the git-add command. You then commit the changes using the git-commit command.

$> git add mipointer.c          # file changed to fix the bug
$> git commit -s                # -s adds the sign-off tag in the commit text

The git commit command raises the nano editor for you to enter the commit message that is describe in the next section. When you exit the editor, the commit object is created. Monitor the changes to the local repository using the git-status command and the git-show command.

Commit message format

Begin the commit message with a single short (less than 78 character) line summarizing the changes, followed by a blank line and then a more thorough description. Tools that turn commits into email, for example, use the first line on the Subject: line and the rest of the commit in the body.

When referencing a reported bug, use the bug number from FreeDesktop Bugzilla. If there is no corresponding bug, you should upstream the bug from your distribution to freedesktop.org.

An example of how to reference a reported bug in the commit message:

Fixes: https://bugs.freedesktop.org/show_bug.cgi?id=29049

Subject line

The subject line summarizes the code changes contained in the patch. For large components such as the X Server, prefix with the subsystem (e.g. dix, Xi, xfree86, kdrive, etc.). Look at the xserver's git log to give you guidance. The subject line should also include the bug number if available.

The subject line from the example, as it appears in the commit object:

mi: don't call UpdateSpriteForScreen if we have Xinerama enabled. #18668

Do not type the word [PATCH] in the subject line, it gets added later when the patch is created.

Message body

Explain in sufficient detail what the patch does and why this is necessary. This does not mean you need to describe the actual source changes (e.g. "changed x to be 10, then added x to y"). Use common sense and look at git logs for guidance. See also "on commit messages"

The message body also contains your sign-off tag, so in our example:

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

Other tags may be added after the patch review as hinted in the workflow overview.

Creating a patch

Once the commit object has been created with the proper subject line and message body, you can create a patch for it in order to either attach it to the bug report or e-mail it to the list.

$> git format-patch HEAD~1      # create a patch for the last commit

This will create a file named "0001-description-of-my-change.patch". Git uses the first line of the commit message (massaged for path-name safety) as the file name.

The subject line of the example patch:

[PATCH] mi: don't call UpdateSpriteForScreen if we have Xinerama enabled. #18668

The git format-patch command has prefixed the commit subject line with the word [PATCH] on your behalf. If you haven't signed-off in the commit message body, you can do so with the --signoff option.

If you are submitting a patch for applications, drivers or libraries to xorg-devel list, you should add the component name next to the PATCH word using the --subject-prefix option.

Examples:

[PATCH evdev] fix crash on VT switch #12345
[PATCH libXi] convert to ANSI

The reviewers need to know for which component this patch is for when reading the e-mail (there are over 200 of them). You can configure the git format-patch command to always do it for you:

$> git config format.subjectprefix "PATCH evdev"

Extra info

If you are sending the patch to the list, you may include additional information (benchmark results, a method how to reproduce it) after the -- in the git formatted patch. When the patch is applied, this information is omitted. If you are submitting a patch for a specific server version (not git master), then please note your version here. If this bug affected previous released versions of the X server it helps to say so too.

Plain text format

Always attach patches as plain text files - if emailed then either attached or in-line. Never attach a zip file, tarball or any other archive with patches. Posting a link to a pastebin is permissible on IRC, don't post links on mailing lists, just attach the patch directly to the email.

Apply common sense: make it as easy as possible for others to look at the patch. The more steps required to look at your patch and write a review, the more likely it will be ignored.

E-Mailing a patch

E-mail the patch you have just created to the xorg-devel list for review and approval. Let's use the git-send-email command for that. Of course, you can use other e-mail clients to attach your patch. If you decide to use a mailer, make sure your mailer isn't altering the spaces or lines of the patch, or the patch won't work.

Configure the send-email client using the same git config command we have used so far. The example patch can be e-mailed using this command:

$> git send-email --to xorg-devel@lists.x.org 0001-mi-don-t-call-UpdateSpriteForScreen-if-we-have-Xine.patch

You can use the --dry-run option and/or send it to yourself to try it out first.

Configuring send-email:

git config --global sendemail.confirm always
git config --global sendemail.smtpserver <your mail server>
git config --global sendemail.supresscc self
git config --global sendemail.from "First Last <myself@example.com>"

Patches sent to the mailing list are tracked by Patchwork patch tracking system. The patchwork.freedesktop.org is now available for general use.

If you are already subscribed to xorg-devel using the address the patch comes from, and it's smaller than the list's size limit, it should be delivered immediately - otherwise it goes into a moderation queue which is usually manually processed at least once a day. If you send many patches from an address that you don't want all xorg-devel mail to come to, you can subscribe to the list and then go to the list options page in mailman to turn off mail delivery.

Signing off and reviewing

X.Org developers may use a number of tags to acknowledge patches, both in a commit message and when reviewing patches. Here's a short summary for each tag, please refer to the Linux kernel's Documentation/SubmittingPatches file for details. The summaries below are copied from that file.

  • Signed-off-by: certifies that you wrote it or otherwise have the right to pass it on as a open-source patch. Specifically, that you agree to the Developer's Certificate of Origin
  • Acked-by: If a person was not directly involved in the preparation or handling of a patch but wishes to signify and record their approval of it then they can arrange to have an Acked-by: line. Acked-by: does not necessarily indicate acknowledgement of the entire patch.
  • Tested-by: A Tested-by: tag indicates that the patch has been successfully tested (in some environment) by the person named. This tag informs maintainers that some testing has been performed, provides a means to locate testers for future patches, and ensures credit for the testers.
  • Reviewed-by: A Reviewed-by tag is a statement of opinion that the patch is an appropriate modification without any remaining serious technical issues. Any interested reviewer (who has done the work) can offer a Reviewed-by tag for a patch.

Whenever you review a patch on the mailing list or in a bugzilla, feel free to provide the appropriate tag as a reply email (or a comment on bugzilla).

Getting no response

We don't have an abundance of developers and sometimes bugs or patches get dropped. If this happens to your patch, ping the list/bug again after a sufficient period (a few days at the very least). CC the maintainer of the matching subsystem.

Changing a patch

Likely, a developer will tell you to make some changes to the code or the commit message. Although you have committed your changes locally, you can still edit them.

git commit --amend lets you edit the last commit. By default, this only edits the commit message (e.g. git commit --amend -s adds the signed-off-by if you've forgotten it). Any code changes you want to incorporate into the commit, use git add filename before amending the commit. Then re-send/attach the new patch.

If your patch is not the last commit in your local tree, consider using the git-rebase command in interactive mode.

Applying a patch

Although not the subject of this wiki page, it helps making better patches when you understand those on the other side of the fence. You may also want to test your own patch, round trip, by sending it to yourself.

Download the patch from your favorite e-mail client as plain text file in the appropriate git local repository. Use the git-am command to apply this patch.

Using git

Always use git to generate a patch. Why? All X.Org developers work with git and a git-formatted patch is easiest to apply and preserves ownership (which is in your interest). If you are working from a tarball or a distribution package, read generating git patches from tarballs to find out how to set up a temporary git repository.

This summarizes the commands needed to create and e-mail a patch such as the example used:

$>                              # Edit files to make code changes
$> git add file.c               # Add changed files to be committed
$> git commit -s                # Sign-off and commit changes, write commit message
$> git format-patch HEAD~1      # create a patch for the last commit
$> git send-email --to xorg-devel@lists.x.org 0001-*.patch

Further reading