| 1 |
commit: e567fc6f7d05d509bdac865606271f0bc2e132d6 |
| 2 |
Author: Michał Górny <mgorny <AT> gentoo <DOT> org> |
| 3 |
AuthorDate: Sat Oct 14 18:14:40 2017 +0000 |
| 4 |
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org> |
| 5 |
CommitDate: Wed Jan 3 04:31:48 2018 +0000 |
| 6 |
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=e567fc6f |
| 7 |
|
| 8 |
Move the commit policy & commit message to git |
| 9 |
|
| 10 |
ebuild-maintenance/git/text.xml | 158 ++++++++++++++++++++++++++ |
| 11 |
ebuild-maintenance/maintenance-tasks/text.xml | 151 ------------------------ |
| 12 |
2 files changed, 158 insertions(+), 151 deletions(-) |
| 13 |
|
| 14 |
diff --git a/ebuild-maintenance/git/text.xml b/ebuild-maintenance/git/text.xml |
| 15 |
index 2070217..59f1833 100644 |
| 16 |
--- a/ebuild-maintenance/git/text.xml |
| 17 |
+++ b/ebuild-maintenance/git/text.xml |
| 18 |
@@ -107,6 +107,164 @@ the historical commits after the initial git commit. |
| 19 |
</body> |
| 20 |
</section> |
| 21 |
|
| 22 |
+<section> |
| 23 |
+<title>Committing to gentoo.git</title> |
| 24 |
+<body> |
| 25 |
+ |
| 26 |
+<subsection> |
| 27 |
+<title>Git Commit Policy</title> |
| 28 |
+<body> |
| 29 |
+ |
| 30 |
+<ul> |
| 31 |
+<li>Always run <c>repoman scan</c> before you commit.</li> |
| 32 |
+<li>Please run <c>repoman full</c> before you commit.</li> |
| 33 |
+<li>Always test that <path>package.mask</path> is okay by doing |
| 34 |
+<c>emerge --pretend mypkg</c> before you commit and check |
| 35 |
+that it doesn't contain any conflicts.</li> |
| 36 |
+<li>Always commit the updated <path>package.mask</path> before |
| 37 |
+the updated package.</li> |
| 38 |
+<li>Always do atomic commits; if you commit a package with a new license, |
| 39 |
+or that is masked, then first commit the revised <path>package.mask</path> and/or license, |
| 40 |
+then commit the ebuild, patches |
| 41 |
+and <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> all in <b>one</b> go |
| 42 |
+.</li> |
| 43 |
+<note> Although the set of changes in a single git commit is atomic, and |
| 44 |
+combining <path>package.mask</path>/license changes with ebuild changes in a |
| 45 |
+single commit wouldn't break atomicity, it is not currently possible to do so |
| 46 |
+using <c>repoman commit</c>.</note> |
| 47 |
+<!-- See: https://bugs.gentoo.org/show_bug.cgi?id=390651 --> |
| 48 |
+</ul> |
| 49 |
+ |
| 50 |
+</body> |
| 51 |
+</subsection> |
| 52 |
+ |
| 53 |
+<subsection> |
| 54 |
+<title>Git Commit Message Format</title> |
| 55 |
+<body> |
| 56 |
+ |
| 57 |
+<p> |
| 58 |
+It is important to format the commit messages properly so that they |
| 59 |
+communicate the changes to the reader in a clear and concise |
| 60 |
+way. Additionally, consistency in message format allows for easier |
| 61 |
+parsing by external tools. The first line of the commit message should |
| 62 |
+contain a brief summary of the changes, followed by an empty new |
| 63 |
+line. From the third line onward should be a detailed, multiline |
| 64 |
+explanation of the changes introduced by the commit. At the very end, |
| 65 |
+auxiliary information such as the bugs related to the commit, |
| 66 |
+contributors, and reviewers should be listed using RFC822/git style |
| 67 |
+tags. The length of the lines in the message should be 70-75 |
| 68 |
+characters at maximum. |
| 69 |
+</p> |
| 70 |
+ |
| 71 |
+<p> |
| 72 |
+The summary line should start with referencing what is affected by the |
| 73 |
+change followed by a colon ':' character. Use the rules in the |
| 74 |
+following list to determine the proper format based on what has |
| 75 |
+changed, substituting the package, category and eclass names |
| 76 |
+appropriately: |
| 77 |
+ |
| 78 |
+<ul> |
| 79 |
+<li><c>${CATEGORY}/${PN}:</c>Single Package (Note that <c>repoman commit</c> |
| 80 |
+automatically inserts this for you)</li> |
| 81 |
+<li><c>${CATEGORY}:</c> Package Category</li> |
| 82 |
+<li><c>profiles:</c> Profile Directory</li> |
| 83 |
+<li><c>${ECLASS}.eclass:</c> Eclass Directotry</li> |
| 84 |
+<li><c>licenses:</c> Licenses Directory</li> |
| 85 |
+<li><c>metadata:</c> Metadata Directory</li> |
| 86 |
+</ul> |
| 87 |
+ |
| 88 |
+For packages where <c>${CATEGORY}/${PN}:</c> is long, the line length |
| 89 |
+limit can be exceeded, if absolutely necessary, to ensure a more |
| 90 |
+useful summary line. If a commit affects multiple directories, prepend |
| 91 |
+the message with which reflects the intention of the change best. If |
| 92 |
+there are any bugs on Gentoo Bugzilla associated with the commit, id |
| 93 |
+of the bug can be appended to the summary line using the format |
| 94 |
+<c>#BUG-ID</c>. If you are modifying keywords, clearly state what |
| 95 |
+keywords are added/removed. |
| 96 |
+ |
| 97 |
+<warning> |
| 98 |
+By default, lines starting with <c>#</c> are considered to be comments |
| 99 |
+by git and not included in the commit message. Make sure that a new |
| 100 |
+line does not start with <c>#BUG-ID</c>. Optionally, git can be |
| 101 |
+configured to use a different character for comments by changing the |
| 102 |
+<c>commentchar</c> option. |
| 103 |
+</warning> |
| 104 |
+</p> |
| 105 |
+ |
| 106 |
+<p> |
| 107 |
+For non-trivial commits, the message should contain a detailed |
| 108 |
+explanation of what the commit intends to change, why it is required, |
| 109 |
+and how it is accomplished, along with any other supplementary |
| 110 |
+information. |
| 111 |
+</p> |
| 112 |
+ |
| 113 |
+<p> |
| 114 |
+Finally the commit message should list auxiliary information such as |
| 115 |
+people who are involved in authoring, suggesting, reviewing and |
| 116 |
+testing the changes, and revelant bugs. Use RFC822/git style tags as |
| 117 |
+explained in the |
| 118 |
+<uri link="https://kernel.org/doc/html/latest/process/submitting-patches.html"> |
| 119 |
+Linux Kernel patch guideline</uri>. Additionally, the following tags |
| 120 |
+are optionally used in Gentoo: |
| 121 |
+ |
| 122 |
+<ul> |
| 123 |
+<li><c>Bug:</c> Use this to reference bugs <e>without</e> closing them. |
| 124 |
+The value is a URL to the bug. If multiple bugs need to be referenced, |
| 125 |
+each one should be listed in a separate <c>Bug</c> tag. If a bug |
| 126 |
+on Gentoo Bugzilla, or an issue or a pull request on GitHub |
| 127 |
+is referenced, a reference to the commit will be added |
| 128 |
+automatically.</li> |
| 129 |
+<li><c>Closes:</c> Use this to reference bugs and close them |
| 130 |
+automatically. Alike <c>Bug:</c>, the value is a single URL to the bug, |
| 131 |
+and multiple tags can be used to close multiple bugs. If a bug on Gentoo |
| 132 |
+Bugzilla, or an issue or a pull request on a GitHub repository |
| 133 |
+mirrored by Gentoo is referenced, it will be closed (as fixed) |
| 134 |
+automatically with reference to the commit.</li> |
| 135 |
+<li><c>Package-Manager:</c> This is automatically inserted by |
| 136 |
+<c>repoman commit</c> and it specifies the version of |
| 137 |
+<pkg>sys-apps/portage</pkg> on the system.</li> |
| 138 |
+<li><c>RepoMan-Options:</c> This is automatically inserted by |
| 139 |
+<c>repoman commit</c> and records the options passed to repoman (such |
| 140 |
+as --force) for the commit.</li> |
| 141 |
+</ul> |
| 142 |
+</p> |
| 143 |
+ |
| 144 |
+<p> |
| 145 |
+Additionally, some developers prefer referencing bugs on the summary |
| 146 |
+line using the <c>#nnnnnn</c> form. Developers are free to use either |
| 147 |
+form, or both simultaneously to combine their advantages. |
| 148 |
+</p> |
| 149 |
+ |
| 150 |
+<p> |
| 151 |
+When committing <uri link="::ebuild-writing/user-submitted">user |
| 152 |
+contributions</uri>, make sure to credit them in your commit message |
| 153 |
+with the user's full name and email address. Be aware and respectful |
| 154 |
+of their privacy: some users prefer to be only known by a |
| 155 |
+nickname. Take advantage of the tags such as <c>Suggested-By</c> or |
| 156 |
+<c>Reported-By:</c>when entering such information to the commit |
| 157 |
+message. |
| 158 |
+</p> |
| 159 |
+ |
| 160 |
+<p> |
| 161 |
+An example commit message is shown below: |
| 162 |
+</p> |
| 163 |
+ |
| 164 |
+<pre caption="Example commit message"> |
| 165 |
+app-misc/foo: version bump to 0.5 |
| 166 |
+ |
| 167 |
+This also adds a new USE flag 'bar' which controls the |
| 168 |
+new bar functionality introduced with this version. |
| 169 |
+ |
| 170 |
+Bug: https://bugs.gentoo.org/00000 |
| 171 |
+Closes: https://bugs.gentoo.org/00001 |
| 172 |
+</pre> |
| 173 |
+ |
| 174 |
+</body> |
| 175 |
+</subsection> |
| 176 |
+ |
| 177 |
+</body> |
| 178 |
+</section> |
| 179 |
+ |
| 180 |
</body> |
| 181 |
</chapter> |
| 182 |
</guide> |
| 183 |
|
| 184 |
diff --git a/ebuild-maintenance/maintenance-tasks/text.xml b/ebuild-maintenance/maintenance-tasks/text.xml |
| 185 |
index ba401ca..003d14e 100644 |
| 186 |
--- a/ebuild-maintenance/maintenance-tasks/text.xml |
| 187 |
+++ b/ebuild-maintenance/maintenance-tasks/text.xml |
| 188 |
@@ -96,157 +96,6 @@ work on those architectures. |
| 189 |
</subsection> |
| 190 |
|
| 191 |
<subsection> |
| 192 |
-<title>Git Commit Message Format</title> |
| 193 |
-<body> |
| 194 |
- |
| 195 |
-<p> |
| 196 |
-It is important to format the commit messages properly so that they |
| 197 |
-communicate the changes to the reader in a clear and concise |
| 198 |
-way. Additionally, consistency in message format allows for easier |
| 199 |
-parsing by external tools. The first line of the commit message should |
| 200 |
-contain a brief summary of the changes, followed by an empty new |
| 201 |
-line. From the third line onward should be a detailed, multiline |
| 202 |
-explanation of the changes introduced by the commit. At the very end, |
| 203 |
-auxiliary information such as the bugs related to the commit, |
| 204 |
-contributors, and reviewers should be listed using RFC822/git style |
| 205 |
-tags. The length of the lines in the message should be 70-75 |
| 206 |
-characters at maximum. |
| 207 |
-</p> |
| 208 |
- |
| 209 |
-<p> |
| 210 |
-The summary line should start with referencing what is affected by the |
| 211 |
-change followed by a colon ':' character. Use the rules in the |
| 212 |
-following list to determine the proper format based on what has |
| 213 |
-changed, substituting the package, category and eclass names |
| 214 |
-appropriately: |
| 215 |
- |
| 216 |
-<ul> |
| 217 |
-<li><c>${CATEGORY}/${PN}:</c>Single Package (Note that <c>repoman commit</c> |
| 218 |
-automatically inserts this for you)</li> |
| 219 |
-<li><c>${CATEGORY}:</c> Package Category</li> |
| 220 |
-<li><c>profiles:</c> Profile Directory</li> |
| 221 |
-<li><c>${ECLASS}.eclass:</c> Eclass Directotry</li> |
| 222 |
-<li><c>licenses:</c> Licenses Directory</li> |
| 223 |
-<li><c>metadata:</c> Metadata Directory</li> |
| 224 |
-</ul> |
| 225 |
- |
| 226 |
-For packages where <c>${CATEGORY}/${PN}:</c> is long, the line length |
| 227 |
-limit can be exceeded, if absolutely necessary, to ensure a more |
| 228 |
-useful summary line. If a commit affects multiple directories, prepend |
| 229 |
-the message with which reflects the intention of the change best. If |
| 230 |
-there are any bugs on Gentoo Bugzilla associated with the commit, id |
| 231 |
-of the bug can be appended to the summary line using the format |
| 232 |
-<c>#BUG-ID</c>. If you are modifying keywords, clearly state what |
| 233 |
-keywords are added/removed. |
| 234 |
- |
| 235 |
-<warning> |
| 236 |
-By default, lines starting with <c>#</c> are considered to be comments |
| 237 |
-by git and not included in the commit message. Make sure that a new |
| 238 |
-line does not start with <c>#BUG-ID</c>. Optionally, git can be |
| 239 |
-configured to use a different character for comments by changing the |
| 240 |
-<c>commentchar</c> option. |
| 241 |
-</warning> |
| 242 |
-</p> |
| 243 |
- |
| 244 |
-<p> |
| 245 |
-For non-trivial commits, the message should contain a detailed |
| 246 |
-explanation of what the commit intends to change, why it is required, |
| 247 |
-and how it is accomplished, along with any other supplementary |
| 248 |
-information. |
| 249 |
-</p> |
| 250 |
- |
| 251 |
-<p> |
| 252 |
-Finally the commit message should list auxiliary information such as |
| 253 |
-people who are involved in authoring, suggesting, reviewing and |
| 254 |
-testing the changes, and revelant bugs. Use RFC822/git style tags as |
| 255 |
-explained in the |
| 256 |
-<uri link="https://kernel.org/doc/html/latest/process/submitting-patches.html"> |
| 257 |
-Linux Kernel patch guideline</uri>. Additionally, the following tags |
| 258 |
-are optionally used in Gentoo: |
| 259 |
- |
| 260 |
-<ul> |
| 261 |
-<li><c>Bug:</c> Use this to reference bugs <e>without</e> closing them. |
| 262 |
-The value is a URL to the bug. If multiple bugs need to be referenced, |
| 263 |
-each one should be listed in a separate <c>Bug</c> tag. If a bug |
| 264 |
-on Gentoo Bugzilla, or an issue or a pull request on GitHub |
| 265 |
-is referenced, a reference to the commit will be added |
| 266 |
-automatically.</li> |
| 267 |
-<li><c>Closes:</c> Use this to reference bugs and close them |
| 268 |
-automatically. Alike <c>Bug:</c>, the value is a single URL to the bug, |
| 269 |
-and multiple tags can be used to close multiple bugs. If a bug on Gentoo |
| 270 |
-Bugzilla, or an issue or a pull request on a GitHub repository |
| 271 |
-mirrored by Gentoo is referenced, it will be closed (as fixed) |
| 272 |
-automatically with reference to the commit.</li> |
| 273 |
-<li><c>Package-Manager:</c> This is automatically inserted by |
| 274 |
-<c>repoman commit</c> and it specifies the version of |
| 275 |
-<pkg>sys-apps/portage</pkg> on the system.</li> |
| 276 |
-<li><c>RepoMan-Options:</c> This is automatically inserted by |
| 277 |
-<c>repoman commit</c> and records the options passed to repoman (such |
| 278 |
-as --force) for the commit.</li> |
| 279 |
-</ul> |
| 280 |
-</p> |
| 281 |
- |
| 282 |
-<p> |
| 283 |
-Additionally, some developers prefer referencing bugs on the summary |
| 284 |
-line using the <c>#nnnnnn</c> form. Developers are free to use either |
| 285 |
-form, or both simultaneously to combine their advantages. |
| 286 |
-</p> |
| 287 |
- |
| 288 |
-<p> |
| 289 |
-When committing <uri link="::ebuild-writing/user-submitted">user |
| 290 |
-contributions</uri>, make sure to credit them in your commit message |
| 291 |
-with the user's full name and email address. Be aware and respectful |
| 292 |
-of their privacy: some users prefer to be only known by a |
| 293 |
-nickname. Take advantage of the tags such as <c>Suggested-By</c> or |
| 294 |
-<c>Reported-By:</c>when entering such information to the commit |
| 295 |
-message. |
| 296 |
-</p> |
| 297 |
- |
| 298 |
-<p> |
| 299 |
-An example commit message is shown below: |
| 300 |
-</p> |
| 301 |
- |
| 302 |
-<pre caption="Example commit message"> |
| 303 |
-app-misc/foo: version bump to 0.5 |
| 304 |
- |
| 305 |
-This also adds a new USE flag 'bar' which controls the |
| 306 |
-new bar functionality introduced with this version. |
| 307 |
- |
| 308 |
-Bug: https://bugs.gentoo.org/00000 |
| 309 |
-Closes: https://bugs.gentoo.org/00001 |
| 310 |
-</pre> |
| 311 |
- |
| 312 |
-</body> |
| 313 |
-</subsection> |
| 314 |
- |
| 315 |
-<subsection> |
| 316 |
-<title>Git Commit Policy</title> |
| 317 |
-<body> |
| 318 |
- |
| 319 |
-<ul> |
| 320 |
-<li>Always run <c>repoman scan</c> before you commit.</li> |
| 321 |
-<li>Please run <c>repoman full</c> before you commit.</li> |
| 322 |
-<li>Always test that <path>package.mask</path> is okay by doing |
| 323 |
-<c>emerge --pretend mypkg</c> before you commit and check |
| 324 |
-that it doesn't contain any conflicts.</li> |
| 325 |
-<li>Always commit the updated <path>package.mask</path> before |
| 326 |
-the updated package.</li> |
| 327 |
-<li>Always do atomic commits; if you commit a package with a new license, |
| 328 |
-or that is masked, then first commit the revised <path>package.mask</path> and/or license, |
| 329 |
-then commit the ebuild, patches |
| 330 |
-and <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> all in <b>one</b> go |
| 331 |
-.</li> |
| 332 |
-<note> Although the set of changes in a single git commit is atomic, and |
| 333 |
-combining <path>package.mask</path>/license changes with ebuild changes in a |
| 334 |
-single commit wouldn't break atomicity, it is not currently possible to do so |
| 335 |
-using <c>repoman commit</c>.</note> |
| 336 |
-<!-- See: https://bugs.gentoo.org/show_bug.cgi?id=390651 --> |
| 337 |
-</ul> |
| 338 |
- |
| 339 |
-</body> |
| 340 |
-</subsection> |
| 341 |
- |
| 342 |
-<subsection> |
| 343 |
<title>The files Directory</title> |
| 344 |
<body> |
Archives