summaryrefslogtreecommitdiff
path: root/Development/Documentation/SubmittingPatches.mdwn
diff options
context:
space:
mode:
authorJoe Rayhawk <jrayhawk@freedesktop.org>2013-07-08 07:19:56 +0000
committerJoe Rayhawk <jrayhawk@freedesktop.org>2013-07-08 07:19:56 +0000
commitdd9f574b6b2ad4dcf44fea2e418e4eb58f3e5300 (patch)
treed130a86a4d1c990cc72ffbe9e4f9de7c78818313 /Development/Documentation/SubmittingPatches.mdwn
parent29f8a2abe160ae13d2e19971bd97aa3561e7b2c3 (diff)
moin2mdwn: convert page Development/Documentation/SubmittingPatches
Diffstat (limited to 'Development/Documentation/SubmittingPatches.mdwn')
-rw-r--r--Development/Documentation/SubmittingPatches.mdwn199
1 files changed, 199 insertions, 0 deletions
diff --git a/Development/Documentation/SubmittingPatches.mdwn b/Development/Documentation/SubmittingPatches.mdwn
new file mode 100644
index 00000000..c56c419e
--- /dev/null
+++ b/Development/Documentation/SubmittingPatches.mdwn
@@ -0,0 +1,199 @@
+
+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|http://cgit.freedesktop.org/xorg/xserver/commit/?id=9fe9b6e4ef669b192ee349e3290db5d2aeea273c]] from which this [[patch|http://lists.freedesktop.org/archives/xorg/2009-February/043171.html]] 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|http://www.x.org/wiki/XServer]].
+
+The patch submitter does the following:
+
+* Commit code changes to the local repository using the [[git-commit|http://www.kernel.org/pub/software/scm/git/docs/git-commit.html]] command
+* Create a patch using the [[git-format-patch|http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html]] command
+* E-mail the patch to the xorg-devel list using the [[git-send-email|http://www.kernel.org/pub/software/scm/git/docs/git-send-email.html]] command
+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|http://www.kernel.org/pub/software/scm/git/docs/git-am.html]] command
+* Push the patch to the git remote repository using the [[git-push|http://www.kernel.org/pub/software/scm/git/docs/git-push.html]] 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|http://lists.freedesktop.org/archives/xorg/2009-February/043171.html]], 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|CodingStyle]].
+
+Before creating a commit, ensure your git user name and e-mail is configured correctly using the [[git-config|http://www.kernel.org/pub/software/scm/git/docs/git-config.html]] 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.
+[[!format txt """
+$> 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|http://www.kernel.org/pub/software/scm/git/docs/git-add.html]] command. You then commit the changes using the [[git-commit|http://www.kernel.org/pub/software/scm/git/docs/git-commit.html]] command.
+[[!format txt """
+$> 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|http://www.kernel.org/pub/software/scm/git/docs/git-status.html]] command and the [[git-show|http://www.kernel.org/pub/software/scm/git/docs/git-show.html]] 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|https://bugs.freedesktop.org/]]. 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:
+[[!format txt """
+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_:
+[[!format txt """
+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"|http://who-t.blogspot.com/2009/12/on-commit-messages.html]]
+
+The message body also contains your sign-off tag, so in our example:
+[[!format txt """
+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.
+
+
+[[!format txt """
+$> 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:
+
+
+[[!format txt """
+[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:
+[[!format txt """
+[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:
+
+
+[[!format txt """
+$> 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|http://www.kernel.org/pub/software/scm/git/docs/git-send-email.html]] 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:
+[[!format txt """
+$> 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:
+[[!format txt """
+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|http://ozlabs.org/~jk/projects/patchwork/]] patch tracking system. The [[patchwork.freedesktop.org|http://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|http://lxr.linux.no/linux/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.
+ * **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|http://cgit.freedesktop.org/xorg/doc/xorg-docs/tree/MAINTAINERS]] 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|http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html]] 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|http://www.kernel.org/pub/software/scm/git/docs/git-am.html]] 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|http://who-t.blogspot.com/2009/06/git-patches-from-tarballs.html]] 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:
+[[!format txt """
+$> # 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
+
+* [[List of Xorg maintainers|http://cgit.freedesktop.org/xorg/doc/xorg-docs/tree/MAINTAINERS]]
+* [[Kernel patch submission process|http://kernelnewbies.org/UpstreamMerge/SubmittingPatches]]: details about patch format and contents equally apply to X.Org patches.
+* [[Git User's Manual|http://www.kernel.org/pub/software/scm/git/docs/user-manual.html]] \ No newline at end of file