Edgewall Software

Changes between Version 15 and Version 16 of TracDev/SubmittingPatches


Ignore:
Timestamp:
Feb 14, 2015, 11:16:26 AM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified

  • TracDev/SubmittingPatches

    v15 v16  
    1 = Submitting Patches =
     1= Submitting Patches
    22
    3 Have you made some changes you'd like to submit to Trac?  Great!  We'd love to see them.  However some people who are unfamiliar with the process of submitting changes make it overly complicated for themselves and the developers reviewing the changes.  So, in order to make things go smoothly for everyone, here are some guidelines on submitting your changes.
     3Have you made some changes you'd like to submit to Trac? Great! We'd love to see them. In order to make things go smoothly for everyone, here are some guidelines on submitting your changes.
    44
    5 == What is a patch? ==
     5== What is a patch?
    66
    7 A patch is a single file listing the changes you've made in a format that can be applied with the [http://www.gnu.org/software/patch/ GNU patch] tool. It will look something like this:
     7A 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:
    88{{{
    99Index: /branches/0.9-stable/trac/scripts/admin.py
    … …  
    2727This format is called an "unified diff format". See below how to generate it.
    2828
    29 == Getting started ==
     29== Getting started
    3030
    31 First you'll need to get a copy of the Trac source to make and test your changes.  Use [http://subversion.apache.org/ Subversion] to get the source so that you can easily generate your patch.
     31First you'll need to get a copy of the Trac source to make and test your changes. Use [http://subversion.apache.org/ Subversion] to get the source so that you can easily generate your patch.
    3232
    3333Bug fixes for a current release may be added on the "stable" branch:
    … …  
    4545Then see [DevelopmentEnvironmentSetup how to setup a development environment].
    4646
    47 == Make some changes ==
     47== Make some changes
    4848
    4949Go ahead and make your changes to the Trac code.
    5050
    51 It is a good idea to be familiar with the CodingStyle of the Trac project, so that we won't ask you to rework your changes later on.
     51It is a good idea to apply the CodingStyle of the Trac project to your changes, so that we won't ask you to rework your changes later on.
    5252
    5353Test the changes using [TracTroubleshooting#ModifyingtheCode tracd].
    … …  
    5555Ideally, you should write some tests (UnitTests or FunctionalTests) demonstrating the problem you're trying to address - the tests should ''fail'' before the fix and ''pass'' with your changes. Also, by running the tests, you will see if you didn't break anything else with your changes.
    5656
    57 A sentence like ''added some more tests - all tests pass'' in your commit message is guaranteed to earn you good points from the maintainers ;-)
     57A sentence like ''added some more tests - all tests pass'' in your commit message is guaranteed to earn you points from the maintainers!
    5858
    59 == Adding files ==
     59== Adding files
    6060
    61 Did you create any new files?  If you only modified existing Trac files you can skip this. However, if you added any new files be sure to tell Subversion you're adding them:
     61Did you create any new files? If you only modified existing Trac files you can skip this. However, if you added any new files be sure to tell Subversion you're adding them:
    6262
    6363{{{
    … …  
    6767The same applies if you use Mercurial, and in Git you'll also have to "add" modified files to the index.
    6868
    69 == Make the patch ==
     69== Make the patch
    7070
    7171Simply run:
    … …  
    7474}}}
    7575
    76 This will save your changes to the file "my_patch_file.diff".  Pick an appropriate filename for the changes you've made.
     76This will save your changes to the file "my_patch_file.diff". Pick an appropriate filename for the changes you've made.
    7777
    78 Note that `svn diff` will generate a diff in the unified format. If for some reason you use the `diff` tool to produce the patch, then please use `diff -u` otherwise the diff won't be an unified diff.
     78Note that `svn diff` will generate a diff in the unified format. If you are using the `diff` tool to produce the patch, then please use `diff -u`, otherwise the diff won't be an unified diff.
    7979
    80 With Mercurial or Git, make a commit with a detailed log message (the one you'd like to see later on in Trac itself!) and then export it.
     80With Mercurial or Git, make a commit with a detailed log message, the one you'd like to see later on in Trac itself! Then export it.
    8181
    82 With mercurial, assuming your patch corresponds to the latest commit:
     82With Mercurial, assuming your patch corresponds to the latest commit:
    8383{{{
    8484hg export tip > my_patch_file.diff
    8585}}}
    8686
    87 With git, assuming your patch corresponds to the head:
     87With Git, assuming your patch corresponds to the head:
    8888{{{
    8989git show  > my_patch_file.diff
    9090}}}
    9191
    92 == Submit the patch ==
     92== Submit the patch
    9393
    94 If there is an existing ticket related to the changes you've made attach your patch file to that ticket.  Otherwise please create a new ticket and attach your patch file. Be sure to provide a comment briefly explaining your changes.
     94If there is an existing ticket related to the changes you've made, attach your patch file to that ticket. Otherwise please create a new ticket and attach your patch file. Be sure to provide a comment briefly explaining your changes.
    9595
    96 You may add the text "[PATCH]" at the beginning of the ticket's "Summary" field as a hint to developers that a possible patch has been provided.
     96You may add the text "[PATCH]" at the beginning of the ticket's "Summary" field as a hint to developers that a patch has been provided.
    9797
    9898After that, depending on lots of factors, your patch will be reviewed and eventually integrated. Most probably, you'll be asked to rework your patch a bit, according to the preferences of the Trac maintainers.
    9999
    100 If you wonder why your patch didn't get applied as fast as you'd liked to, see for example the case of #8883. Executive summary: while you never have any guarantee that a patch will be integrated, you can influence this outcome by making the developers ''want'' to integrate your patch. For this, read on to the next section.
    101 
    102 == What is a good patch? ==
     100== What is a good patch?
    103101
    104102Now, having written a patch is no guarantee that the change will actually make it into the repository.
    105 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 be convincing on different accounts:
     103The 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:
    106104 - clarity
    107105   - no spurious changes like whitespace change or other random reformattings
    … …  
    116114See for example #8935, #9718.
    117115
    118 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, if needed.
     116That 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.
    119117
    120 Also useful reading: Mercurial:ContributingChanges#Patch_descriptions.
     118------
     119See also: Mercurial:ContributingChanges#Patch_descriptions.
    121120