diff options
| -rw-r--r-- | Development/Documentation/SubmittingPatches.mdwn | 119 |
1 files changed, 60 insertions, 59 deletions
diff --git a/Development/Documentation/SubmittingPatches.mdwn b/Development/Documentation/SubmittingPatches.mdwn index 3a808c55..b09babd2 100644 --- a/Development/Documentation/SubmittingPatches.mdwn +++ b/Development/Documentation/SubmittingPatches.mdwn @@ -1,7 +1,8 @@ -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. +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|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. +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. (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.) +[[!toc]] # Workflow overview @@ -10,10 +11,9 @@ Take a look at this [[example commit|http://cgit.freedesktop.org/xorg/xserver/co 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 +* Create a [[merge request|https://gitlab.freedesktop.org/help/gitlab-basics/add-merge-request.md]] in the freedesktop.org gitlab -The xorg-devel list reviewers do one of the following: +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) @@ -21,9 +21,7 @@ The xorg-devel list reviewers do one of the following: 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 +* Merges the merge request in gitlab, or closes the MR with an explanation. # Making code changes @@ -62,13 +60,12 @@ 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 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_: [[!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 @@ -81,8 +78,58 @@ 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 -# Creating a patch +X.Org is in the process of migrating development to [[gitlab|https://gitlab.freedesktop.org/xorg/]], and most subprojects use merge requests for development. Please refer to the [[gitlab user documentation|https://gitlab.freedesktop.org/help/gitlab-basics/README.md]] 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|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. Specifically, that you agree to the [[Developer's Certificate of Origin|http://developercertificate.org/]] + * **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|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, or force-push to your gitlab branch. + +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 +"""]] + +# 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. @@ -120,7 +167,7 @@ Examples: 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-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. 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. @@ -143,55 +190,9 @@ Patches sent to the mailing list are tracked by [[Patchwork|http://ozlabs.org/~j 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. Specifically, that you agree to the [[Developer's Certificate of Origin|http://developercertificate.org/]] - * **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]] +* [[Gitlab User's Manual|https://gitlab.freedesktop.org/help/gitlab-basics/README.md]] |