Difference between revisions of "PatchSubmissionGuidelines"

From The Battle for Wesnoth Wiki
(→‎See also)
m (→‎Obtaining help)
 
(11 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
Copied from http://www.wesnoth.org/forum/viewtopic.php?f=10&t=9979
+
'''Submitting a patch for a large and mature project like Wesnoth can be an even more daunting task than writing the code it delivers.'''
  
−
* '''All patches should be submitted at patches.wesnoth.org'''
+
This page provides some '''advice and requirements for prospective code contributors''' seeking the best chance of acceptance for their patches.
−
You can post them in the [http://www.wesnoth.org/forum/viewtopic.php?f=10&t=9979 Coder's Corner] subforum too for discussion, but we need to track what is their status and p.w.o helps a lot
 
  
−
* '''Patches should be generated using "svn diff"'''
+
== Technical requirements ==
−
SVN provides a cool command to generate diff. We usually run "svn diff >mypatch.patch" to create patches, and it's all nice and ready.
 
  
−
It even records precisely the commit against which it was generated, it makes things really easy for us...
+
{{NewDevsGoHereSidebox}}
  
−
* '''Don't forget to add an entry to the Changelog'''
+
<ul>
−
* '''If you add a file, don't forget to update src/Makefile.am, src/SConscript,  src/CMakeLists.txt, and projectfiles/VC9/wesnoth.vcproj '''
 
  
−
* '''Add yourself in about.cfg'''
+
<li>
−
Including your name and/or nickname(s) makes it easier for us to recognize your contributions.
+
<h3>All patches should be submitted as GitHub pull requests</h3>
−
New contributors (i.e., those without commit access) should add themselves to the ''Miscellaneous Contributors'' section of the about file (data/core/about.cfg). Please keep the alphabetical order while doing it!
+
<p>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 that. '''See the <cite>[[WesnothRepository]]</cite> page for help with Git and GitHub.'''</p>
 +
</li>
  
−
* '''When changing WML, please add a pointer in the wiki to where it should be updated when commited'''
+
<li>
 +
<h3>Your commits should follow our existing commit contents and message conventions</h3>
 +
<p>This is explained in greater detail in the '''[[DeveloperGuide#Commits|<cite>DeveloperGuide</cite> section]]''' about commits and commit formatting.</p>
 +
</li>
  
−
* '''Be patient, sometimes we are not very responsive'''
+
<li>
−
* '''Don't be suprised if we discuss the patch a lot'''
+
<h3>Add entries to the changelogs summarizing your changes, if necessary</h3>
−
Thus, you should leave us a way to contact you, either a forum nick, an email adress, or submit with a registered gna 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.
+
<p>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. See the relevant '''[[DeveloperGuide#Changelogs_and_release_notes|<cite>DeveloperGuide</cite> section]]''' as well.</p>
 +
</li>
  
−
* '''The patch should generate no warnings'''
+
<li>
−
Wesnoth has a large number of compiler warnings enabled, and all of them are useful. If your code spits warnings, please have a look, and ask yourself why you are doing whatever causes the warning.
+
<h3>When adding new C++ source code files, make sure to update the most commonly used project files</h3>
 +
<p>The development team primarily uses '''CMake''' and '''SCons'''. The relevant files are '''<code>src/CMakeLists.txt</code>''' and '''<code>src/SConscript</code>'''. You might 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.</p>
 +
<p>Please consider updating the '''other build environments''' under '''<code>projectfiles/</code>''', e.g. Visual C++, as well.</p>
 +
</li>
  
−
* '''Sometimes patches are rejected, don't be suprised if it happens'''
+
<li>
 +
<h3>C++ source code patches must not generate new warnings</h3>
 +
<p>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.</p>
 +
</li>
 +
 
 +
<li>
 +
<h3>Add yourself to the game credits</h3>
 +
<p>'''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.</p>
 +
</li>
 +
 
 +
<li>
 +
<h3>When changing or adding WML features, provide directions for updating the wiki along with your submission in the tracker</h3>
 +
<p>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.</p>
 +
</li>
 +
 
 +
</ul>
 +
 
 +
== After submission ==
 +
 
 +
<ul>
 +
 
 +
<li>
 +
<h3>Be patient, sometimes we are not very responsive</h3>
 +
<p>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. '''If you feel that it takes much too long for us to respond, contact us in #wesnoth-dev on irc.libera.chat.'''</p>
 +
</li>
 +
 
 +
<li>
 +
<h3>Don't be surprised if we discuss the patch a lot</h3>
 +
<p>Thus, you should '''leave us a way to contact you''', by noting your forums username or email address. We recommend that you join the '''<code>#wesnoth-dev</code>''' channel on '''<code>irc.libera.chat</code>''' regularly so we can contact you in real time if needed.</p>
 +
</li>
 +
 
 +
<li>
 +
<h3>Sometimes patches are rejected, please don't be surprised or offended if this happens</h3>
 +
<p>If your patch introduces '''new errors or bugs''', if the feature you implemented '''isn't considered an improvement''', or if '''we couldn't contact you''' with our questions and recommendations, the pull request will be denied. <strong>This can usually be averted</strong> if you discuss your idea on #wesnoth-dev, where the developers will point out these issues. If your pull request is denied, <strong>don't let that discourage you</strong>, though!</p>
 +
</li>
 +
 
 +
</ul>
 +
 
 +
== Obtaining help ==
 +
 
 +
<ul>
 +
 
 +
<li>
 +
<h3>If you encounter any issues or need additional guidance when preparing your patch...</h3>
 +
<p>...the easiest way is to ask the developers on the aforementioned IRC channel, '''<code>#wesnoth-dev</code>'''. You can join <code>#wesnoth-dev</code> in your Web browser via this link: {{FeaturedURL|https://web.libera.chat/#wesnoth-dev}}</p>
 +
</li>
 +
 
 +
<li>
 +
<h3>If you know who is responsible for the code that your patch changes...</h3>
 +
<p>...please prefix their IRC nick in front of your question -- else your message could be overlooked.</p>
 +
</li>
 +
 
 +
</ul>
  
 
== See also ==
 
== See also ==
 +
 +
* [[WesnothRepository]]
 +
* [[DeveloperGuide]]
 
* [[HackingWesnoth]]
 
* [[HackingWesnoth]]
 
* [[CodingStandards]]
 
* [[CodingStandards]]
−
* [[GoodCommitCommentingPractice]]
 
 
* [[EasyCoding]]
 
* [[EasyCoding]]
 
* [[DeveloperResources]]
 
* [[DeveloperResources]]
  
 
[[Category:Development]]
 
[[Category:Development]]

Latest revision as of 12:26, 27 September 2023

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

Are you a newcomer to Git or GitHub, or to the Battle for Wesnoth project?
If so, please see WesnothRepository.

  • 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 that. See the WesnothRepository page for help with Git and GitHub.

  • Your commits should follow our existing commit contents and message conventions

    This is explained in greater detail in the DeveloperGuide section about commits and commit formatting.

  • 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. See the relevant DeveloperGuide section as well.

  • When adding new C++ source code files, make sure to update the most commonly used project files

    The development team primarily uses CMake and SCons. The relevant files are src/CMakeLists.txt and src/SConscript. You might 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.

    Please consider updating the other build environments under projectfiles/, e.g. Visual C++, as well.

  • 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. If you feel that it takes much too long for us to respond, contact us in #wesnoth-dev on irc.libera.chat.

  • Don't be surprised if we discuss the patch a lot

    Thus, you should leave us a way to contact you, by noting your forums username or email address. We recommend that you join the #wesnoth-dev channel on irc.libera.chat regularly so we can contact you in real time if needed.

  • Sometimes patches are rejected, please don't be surprised or offended if this happens

    If your patch introduces new errors or bugs, if the feature you implemented isn't considered an improvement, or if we couldn't contact you with our questions and recommendations, the pull request will be denied. This can usually be averted if you discuss your idea on #wesnoth-dev, where the developers will point out these issues. If your pull request is denied, don't let that discourage you, though!

Obtaining help

  • If you encounter any issues or need additional guidance when preparing your patch...

    ...the easiest way is to ask the developers on the aforementioned IRC channel, #wesnoth-dev. You can join #wesnoth-dev in your Web browser via this link:

  • If you know who is responsible for the code that your patch changes...

    ...please prefix their IRC nick in front of your question -- else your message could be overlooked.

See also

Retrieved from "https://wiki.wesnoth.org/index.php?title=PatchSubmissionGuidelines&oldid=71641"
This page was last edited on 27 September 2023, at 12:26.