Difference between revisions of "User:Shadowm/PatchSubmissionGuidelines"

From The Battle for Wesnoth Wiki
(Split in sections, added an intro blurb, minor rewording)
(Technical requirements)
Line 5: Line 5:
 
== Technical requirements ==
 
== Technical requirements ==
  
* '''All patches must be submitted to [http://patches.wesnoth.org patches.wesnoth.org]'''<br>You may post them in the [http://forums.wesnoth.org/viewtopic.php?f=10 Coder's Corner] forum for discussion too, but we need to track their status, and patches.wesnoth.org is better suited for this.
+
* '''All patches should be submitted as GitHub pull requests'''<br>You may post them in the [http://forums.wesnoth.org/viewtopic.php?f=10 Coder's Corner] forum for discussion too, but we need to track their status, and GitHub is better suited for this. See [http://wiki.wesnoth.org/WesnothRepository this] page for help on using git and GitHub.  
  
 
* '''Add entries to the changelogs summarizing your changes if necessary'''<br>The <code>changelog</code> file contains a list of outstanding changes that is published with every release. If you are fixing a bug or adding a feature that is particularly visible or important for players, you should also add an entry to the <code>players_changelog</code> file.
 
* '''Add entries to the changelogs summarizing your changes if necessary'''<br>The <code>changelog</code> file contains a list of outstanding changes that is published with every release. If you are fixing a bug or adding a feature that is particularly visible or important for players, you should also add an entry to the <code>players_changelog</code> file.
Line 14: Line 14:
  
 
* '''Add yourself to the game credits'''<br>Including your name and/or username(s) makes it easier for the development team and the community at large to recognize your contributions. New contributors (i.e. those without commit access) should add themselves to the ''Miscellaneous Contributors'' section of the credits file (<code>data/core/about.cfg</code>), making sure to follow alphabetical order with respect to the first character that will be displayed.
 
* '''Add yourself to the game credits'''<br>Including your name and/or username(s) makes it easier for the development team and the community at large to recognize your contributions. New contributors (i.e. those without commit access) should add themselves to the ''Miscellaneous Contributors'' section of the credits file (<code>data/core/about.cfg</code>), making sure to follow alphabetical order with respect to the first character that will be displayed.
 
* '''Patches should be generated using "svn diff"'''<br>SVN provides a handy command to generate a unified diff from your local changes. Running <code>svn diff > mypatch.patch</code> is enough to create a proper patch file for submitting. It even records precisely the commit against which it was generated, which makes things easier for us.
 
  
 
* '''When changing or adding WML features, provide directions for updating the wiki along with your submission in the tracker'''<br>This allows us to provide content creators with up-to-date information about WML features, even if you cannot be around in time for the commit or the next release.
 
* '''When changing or adding WML features, provide directions for updating the wiki along with your submission in the tracker'''<br>This allows us to provide content creators with up-to-date information about WML features, even if you cannot be around in time for the commit or the next release.

Revision as of 19:45, 3 February 2014

This is an updated version of the PatchSubmissionGuidelines I'm preparing here. This document is not authoritative until it replaces the current PatchSubmissionGuidelines at their current location.

-- shadowmaster

Submitting a patch for a large and mature project like Wesnoth can be an even more daunting task than writing the code it delivers. This page provides some advice and requirements for prospective code contributors seeking the best chance of acceptance for their patches.

Technical requirements

  • All patches should be submitted as GitHub pull requests
    You may post them in the Coder's Corner forum for discussion too, but we need to track their status, and GitHub is better suited for this. See this page for help on using git and GitHub.
  • Add entries to the changelogs summarizing your changes if necessary
    The changelog file contains a list of outstanding changes that is published with every release. If you are fixing a bug or adding a feature that is particularly visible or important for players, you should also add an entry to the players_changelog file.
  • When adding new C++ source code files, make sure to update the most commonly used project files
    The development team primarily uses CMake, SCons, and Visual C++ 2008. The relevant files are src/CMakeLists.txt, src/SConscript, and projectfiles/VC9/wesnoth.vcproj. You may take a look at how existing source code files are handled in each build script to get an idea of the best way to add your own.
  • C++ source code patches must not generate new warnings
    Wesnoth has a large number of compiler warnings enabled, and all of them are useful. If your code causes new warnings during build, you will be required to fix them.
  • Add yourself to the game credits
    Including your name and/or username(s) makes it easier for the development team and the community at large to recognize your contributions. New contributors (i.e. those without commit access) should add themselves to the Miscellaneous Contributors section of the credits file (data/core/about.cfg), making sure to follow alphabetical order with respect to the first character that will be displayed.
  • When changing or adding WML features, provide directions for updating the wiki along with your submission in the tracker
    This allows us to provide content creators with up-to-date information about WML features, even if you cannot be around in time for the commit or the next release.

After submission

  • Be patient, sometimes we are not very responsive
    The Wesnoth developers live on different locations across the globe and have other matters to attend to, most of the time. It may happen that your patch is assigned to a developer who is currently unable to dedicate much time to reviewing it.
    (FIXME: alternatively, it may happen that the patch is never assigned to anyone. What to do about this?)
  • Don't be suprised if we discuss the patch a lot
    Thus, you should leave us a way to contact you, either a forum nick, an email adress, or submit with a registered Gna.org account. We recommend that you join the #wesnoth-dev channel on irc.freenode.net regularly so we can contact you in real time if needed.
  • Sometimes patches are rejected, don't be suprised if this happens
    (FIXME: common rejection reasons, some words of encouragement.)

Obtaining help

If you encounter any issues or need additional guidance when preparing your patch, you may ask the developers on #wesnoth-dev on irc.freenode.net (FIXME: include the forums and devs ML here?). (FIXME: could really use a link with a guide to using IRC and asking questions in #wesnoth-dev here, e.g. explaining the timezones issue, idlers, etc.)

See also