1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
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. (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
**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 [[merge request|https://gitlab.freedesktop.org/help/user/project/merge_requests/getting_started.md]] 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|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 from the example, as it appears in the _commit object_:
[[!format txt """
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"|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 merge request
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.
[[!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.
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:
[[!format txt """
$> 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:
[[!format txt """
[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|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.
In other words, one must be able to directly see the contents of the patch and apply it via [[git-am|https://www.kernel.org/pub/software/scm/git/docs/git-am.html]] or [[git-am --scissors|https://www.kernel.org/pub/software/scm/git/docs/git-am.html]]
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.
# 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]]
|
