xorg/ Development/ Documentation/ SubmittingPatches

X.Org uses patches to do code development. This page describes the required format of a patch as well as the workflow to create and submit 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. (Note that the example here is from the old mailing-list-based workflow, but the commentary here about review tags and commit message formatting still applies.)

  1. Workflow overview
  2. Making code changes
  3. Creating a commit
  4. Creating a merge request
  5. Signing off and reviewing
  6. Getting no response
  7. Changing a patch
  8. Applying a patch
  9. Using git
  10. Appendix: Creating a patch
  11. Further reading

Workflow overview

The patch submitter does the following:

  • Commit code changes to the local repository using the git-commit command
  • Create a merge request in the freedesktop.org gitlab

The 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:

  • Merges the merge request in gitlab, or closes the MR with an explanation.

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 from the example, as it appears in the commit object: 

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

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 merge request

X.Org is in the process of migrating development to gitlab, and most subprojects use merge requests for development. Please refer to the gitlab user documentation for an introduction to gitlab's contribution workflow. However, if a project does not have Merge Requests enabled, or if you prefer an email workflow, see "Creating a Patch" at the bottom of this page.

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 merge request, feel free to provide the appropriate tag as a reply email or comment.

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, or force-push to your gitlab branch.

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

Appendix: Creating a patch

If you're not using gitlab for this patch, read on.

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.

The reviewers need to know for which component this patch is for when reading the e-mail or filtering in patchwork, as there are over 200 of them. You can configure the git format-patch and git send-email commands to always do it for you:

$> git config format.subjectprefix "PATCH evdev"

Or you can add the component name next to the PATCH word using the --subject-prefix option to git format-patch and git send-email.

Examples:

[PATCH evdev] fix crash on VT switch #12345
[PATCH libXi] convert to ANSI
[PATCH xserver] randr: add support for holographic projector outputs

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.

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. You can use other e-mail clients to send your patch, but you must ensure the patch is inline and the mailer isn't altering the spaces or lines of the patch.

In other words, one must be able to directly see the contents of the patch and apply it via git-am or git-am --scissors

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.

Further reading