Changes between Version 15 and Version 16 of SubmittingPatches


Ignore:
Timestamp:
Jul 11, 2016, 8:26:38 PM (8 years ago)
Author:
sanderd17
Comment:

Update to the new review process

Legend:

Unmodified
Added
Removed
Modified
  • SubmittingPatches

    v15 v16  
    1 We assume this process can be improved, so please send any suggestions and remarks you would have.
     1This document explains the process to submit code patches. This process isn't well suited for art changes, it's best to use the forums to submit new proposed art.
    22
    3 Currently the idea is:
     3== Creating the patch ==
     4First you should [[BuildInstructions|check out]] the game code from SVN or an up-to-date Git fork and make some changes.
    45
    5  * [http://trac.wildfiregames.com/wiki/TortoiseSVN_Guide Check out] the game from SVN. Git is also acceptable if using a fork of the official 0 A.D. git repo.
    6  * Make some changes.
    7  * Make sure you've updated to the latest version of the code (and merged in your own changes).
    8  * If this is your first contribution, please add yourself to the relevant file under [source:ps/trunk/binaries/data/mods/public/gui/credits/texts]. You are free to use your real name, your nickname or both.
    9  * Create a patch, with `svn diff` (or the equivalent "create patch" feature in TortoiseSVN).
    10  * Attach it to a Trac ticket (an existing ticket if there's a relevant one, else a new one), prefix the ticket '''Summary''' with "[PATCH]", set the ticket '''Milestone''' to the current release, and add "review patch" to the '''Keywords''' list. (The keywords make it show up on [query:status=new|assigned|reopened&keywords=~review this query].)
    11  * Try to keep the patches reasonable, i.e. don't mix a dozen bug fixes and new features together, producing a single massive patch. It's generally better to break these into multiple patches, each with its own ticket.
    12  * One of the core developers should then review it and maybe suggest some changes.
    13  * When it's considered okay, they should commit it to SVN.
    14  * If you don't hear anything within a reasonable time period (maybe a week or two), feel free to post a reminder on the [http://www.wildfiregames.com/forum/index.php?showforum=312 forum] or ping the developers on [http://webchat.quakenet.org/?channels=0ad-dev IRC]. Some patches take longer to review due to low priority, high complexity, or special knowledge required to review it. We appreciate your patience and all contributions.
    15  * For more "controversial" changes and gameplay features, it's a good idea to create a topic on the forum anyway, to get as much feedback as possible from the community.
    16  * Also, it's a good idea if you take some time to test patches yourself as well. Even just downloading/applying the patch and compiling it and testing if it does as it's supposed to is highly valuable. (Maybe the developer only has access to Linux, and you're on Windows or Mac, so even just testing to see if it compiles can be a good thing.) You don't have to know all the code to be able to test patches.
    17  * Once you get more familiar with the code you're encouraged to help review patches yourself. Not only will this help speed things up as bugs and ways to improve your code can be found before a team member has had time to look at the patch, it's also a chance for you to become even more familiar with the code and the coding conventions.
     6Make sure you're on the latest version of the code (and merged in your own changes) when making your patch. And try to follow the [[Coding_Conventions|coding conventions]].
    187
    19 You must agree that it is your own work (or else make it clear where it came from) and agree to licensing any code as [http://www.opensource.org/licenses/GPL-2.0 GPL 2+] (or in some cases [http://www.opensource.org/licenses/mit-license.php MIT], especially for code in `lib/` - check the existing copyright headers on the source files you edit) and data files as [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3.0].
     8If this is your first contribution, please add yourself to the relevant file under [source:ps/trunk/binaries/data/mods/public/gui/credits/texts]. You are free to use your real name, your nickname or both.
     9
     10Go to the "trunk" directory in the source tree, and create a patch, with `svn diff` (or the equivalent "create patch" feature in TortoiseSVN).
     11
     12Also try to keep your patches reasonable. Different bugs shouldn't be mixed in the same patch.
     13
     14When you modify or add methods to simulation components, you should add unit tests that test all added or modified changes.
     15
     16== The [report:21 RFC queue] ==
     17
     18Submitting a patch is done by attaching the patch file to a Trac ticket. This can be an existing relevant existing ticket or a new ticket. To get the ticket in the [report:21 RFC queue], you should make sure the ticket looks as follows:
     19
     20 * The ''Summary'' (title of the ticket) should start with `[PATCH]`.
     21 * The ''Milestone'' should be set to the release we're working on now.
     22 * The ''Keyword list'' should have the keywords `rfc patch`.
     23
     24At this stage, at least one other developer should try to give some comments on the patch (on all aspects of it). It is advisable that you also drop by on [https://kiwiirc.com/client/irc.quakenet.org#0ad-dev irc], to discuss matters further. If the topic involves controversial matter (things that influence balancing f.e.), it's also best to create a forum topic for it.
     25
     26Some patches can take longer to review due to high complexity or lower priority. But it's best to keep in touch with us and ask for reviews.
     27
     28Note that any developer can help in the RFC process. So if you have some time, you can also help with other patches in the queue: playtesting, checking code quality or even just seeing if it compiles on your system.
     29
     30When you're already familiar with the codebase, and have a trivial patch (that won't cause discussions on the code style or implementation of the feature), you can skip the RFC stage, and push your patch to the review queue directly.
     31
     32== The [report:15 review queue] ==
     33
     34Once a patch is agreed on during the RFC process, it can be pushed to the [report:15 review queue]. This is done by changing the `rfc` keyword to `review`.
     35
     36At this point, one of the core developers should review the final patch on the following points:
     37
     38 * Code style (check if the patch follows all [[Coding_Conventions|Coding Conventions]])
     39 * An in-game test (check if the patch implements the advertised changes)
     40 * Unit tests (check if the required tests are implemented and the tests still work)
     41
     42When the patch passes on all points, it gets committed. When the patch doesn't pass, it will be denied and send back to the RFC queue.
     43
     44== Legal disclaimer ==
     45
     46By sending in a patch, you agree that it is your own work (or else make it clear where it came from) and agree to licensing any code as [http://www.opensource.org/licenses/GPL-2.0 GPL 2+] (or in some cases [http://www.opensource.org/licenses/mit-license.php MIT], especially for code in `lib/` - check the existing copyright headers on the source files you edit) and data files as [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3.0].