Changes between Version 20 and Version 21 of TracDev/SubmittingPatches

Timestamp:

Sep 8, 2017, 1:44:04 AM (7 years ago)

Author:

Ryan J Ollos

Comment:

Put the most important information first.

TracDev/SubmittingPatches

@@ -4 +4 @@
 Have you made some changes you'd like to submit to Trac? Great! We love to see them. To make things go smoothly for everyone, here are some guidelines on submitting your changes.
 
-== What is a patch?
+== What is a good patch?
 
-A patch is a single file listing the changes you've made in a format that can be applied with the [http://savannah.gnu.org/projects/patch/ GNU patch] tool. It will look something like this:
-{{{
-Index: /branches/0.9-stable/trac/scripts/admin.py
-===================================================================
---- /branches/0.9-stable/trac/scripts/admin.py (revision 2822)
-+++ /branches/0.9-stable/trac/scripts/admin.py (revision 3521)
-@@ -12,9 +12,10 @@
- # history and logs, available at http://projects.edgewall.com/trac/.
- #
- 
-+from __future__ import generators
-+
- __copyright__ = 'Copyright (c) 2003-2006 Edgewall Software'
- 
--from __future__ import generators
- import cmd
- import getpass
- import os
-}}}
+Providing a patch is no guarantee that the change will actually make it into the repository.
+The patch has to be endorsed by a Trac developer, who will carry the burden to maintain that change over time. So the patch has to feature the following:
+ - clarity
+   - no spurious changes like whitespace change or other random reformattings
+   - no unrelated changes; if some refactoring really needs to be done prior to the actual change, better do that in a separate patch
+   - strict adherence to the CodingStyle
+ - maintainability
+   - comments for the parts that needs to be commented, no more, no less
+   - add UnitTests or FunctionalTests
+   - make sure existing tests still pass with your change applied
+ - code quality: the pertinence of the fix or the feature is the main criterion
 
-This format is called an "unified diff format". See below how to generate it.
+See for example #8935, #9718.
+
+That can be hard to get right the first time, so you'll certainly get asked to improve your patch. You should be willing to take feedback into account and maybe do a few iterations of the patch.
 
 == Getting started
@@ -70 +64 @@
 == Make the patch
 
+A patch is a single file listing the changes you've made in a format that can be applied with the [http://savannah.gnu.org/projects/patch/ GNU patch] tool. It will look something like this:
+{{{
+Index: /branches/0.9-stable/trac/scripts/admin.py
+===================================================================
+--- /branches/0.9-stable/trac/scripts/admin.py (revision 2822)
++++ /branches/0.9-stable/trac/scripts/admin.py (revision 3521)
+@@ -12,9 +12,10 @@
+ # history and logs, available at http://projects.edgewall.com/trac/.
+ #
+ 
++from __future__ import generators
++
+ __copyright__ = 'Copyright (c) 2003-2006 Edgewall Software'
+ 
+-from __future__ import generators
+ import cmd
+ import getpass
+ import os
+}}}
+
+This format is called an "unified diff format".
+
 Save your changes to the file "my_patch_file.diff":
 {{{#!sh
@@ -99 +115 @@
 After that, depending on lots of factors, your patch will be reviewed and eventually integrated. Most likely, you'll be asked to rework your patch a bit, according to the preferences of the Trac maintainers. 
 
-== What is a good patch?
-
-Now, having written a patch is no guarantee that the change will actually make it into the repository.
-The patch has to be endorsed by a Trac developer, who will carry the burden to maintain that change over time. So the patch has to feature the following:
- - clarity
-   - no spurious changes like whitespace change or other random reformattings
-   - no unrelated changes; if some refactoring really needs to be done prior to the actual change, better do that in a separate patch
-   - strict adherence to the CodingStyle
- - maintainability
-   - comments for the parts that needs to be commented, no more, no less
-   - add UnitTests or FunctionalTests
-   - make sure existing tests still pass with your change applied
- - code quality: the pertinence of the fix or the feature is the main criterion
-
-See for example #8935, #9718.
-
-That can be hard to get right the first time, so you'll certainly get asked to improve your patch. You should be willing to take feedback into account and maybe do a few iterations of the patch.
-
 ------
 See also: Mercurial:ContributingChanges#Patch_descriptions.