This wiki has been moved to https://github.com/SuperTux/wiki into the mediawiki branch.

Difference between revisions of "Contributing"

From SuperTux
Jump to: navigation, search
(Merge CreatingPatches into Contributing)
(Make page less negative to avoid scaring people away)
Line 3: Line 3:
 
== Why ==
 
== Why ==
 
*Show your changes to the world, and contribute them to the project!
 
*Show your changes to the world, and contribute them to the project!
*You must have some patches accepted before we'll give you write access to our repository or let you join the team.
+
*You get write access to our repository and join the team if you contribute enough.
  
 
== Licenses ==
 
== Licenses ==
  
 
We can't use contributions that aren't redistributable under the same license as SuperTux itself.
 
We can't use contributions that aren't redistributable under the same license as SuperTux itself.
Usually, GPL will infect small code changes automatically. For everything else (like levels, images, sounds, and new programs), make sure that you can release it under GPLv2 (yes, ''all'' contributions need to be released under GPL) and also CC-by-sa for data files such as images, sounds, music, and levels. (Scripts count as parts of levels)
+
Usually, GPL will infect small code changes automatically. For everything else (like levels, images, sounds, and new programs), make sure that you can release it under GPLv2 (yes, ''all'' contributions need to be released under GPL) and also CC-BY-SA for data files such as images, sounds, music, and levels. (Scripts count as parts of levels)
  
 
== Generic instructions ==
 
== Generic instructions ==
 
These instructions apply to every function you may want to adopt.
 
These instructions apply to every function you may want to adopt.
 
#Join the SuperTux [[Contact#Mailing List|mailing list]] to stay up to date with recent developments.
 
#Join the SuperTux [[Contact#Mailing List|mailing list]] to stay up to date with recent developments.
#Check out the latest SuperTux [[Download/Subversion|development version]] and compile it by following the instructions in the [http://svn.berlios.de/viewcvs/supertux/trunk/supertux/INSTALL?view=markup INSTALL file].
+
#Check out the latest SuperTux [[Download/Subversion|development version]] and compile it by following the instructions in the [http://svn.berlios.de/viewcvs/supertux/trunk/supertux/INSTALL?view=markup INSTALL file] if you want to develop code or levels.
#Modify or add something that is either listed in the [[TODO]] or seems useful to you.
+
#Modify or add something that is either listed in the [[Milestone 2 Design Document/Tasks|task list]] or seems useful to you.
 
#Give us your work:
 
#Give us your work:
 
#*The preferred way is to open a new report on our [{{MediaWiki:bugtracker-url}} bug tracker] and attach the files to it. (You can upload and attach files to bug reports using the “Upload File” button when filing or perusing them).
 
#*The preferred way is to open a new report on our [{{MediaWiki:bugtracker-url}} bug tracker] and attach the files to it. (You can upload and attach files to bug reports using the “Upload File” button when filing or perusing them).
 
#*Alternatively, upload the files to some website or ftp server and send us the link on the mailing list.
 
#*Alternatively, upload the files to some website or ftp server and send us the link on the mailing list.
#*Using attachements on the mailing list is NOT good as the files tend to get big which will annoy people subscribed to the mailing list!
+
#*Do NOT use attachments on the mailing list; the files tend to get big, annoying people, and the mailing list often eats them
  
 
== Data Files ==
 
== Data Files ==
 
Contributions which mostly add new files (typically when creating new graphics, sound, music, levels) can simply be put into an archive (preferably .tar.gz or .zip).
 
Contributions which mostly add new files (typically when creating new graphics, sound, music, levels) can simply be put into an archive (preferably .tar.gz or .zip).
  
The developers will review your work and, if they share your opinion about its usefulness, check it into the repository.
+
The developers will review your work and, if everything seems in order, check it into the repository.
  
 
=== Translators ===
 
=== Translators ===
Line 32: Line 32:
  
 
Please use the PNG format for small graphics and the JPEG format for large ones.
 
Please use the PNG format for small graphics and the JPEG format for large ones.
It would be helpful to keep and send the source files as well (the GIMP's .xcf is preferred) so that the team can reuse the image more easily.
+
It would be helpful to keep and send the source files as well (the GIMP's .xcf is preferred) so that the team can reuse the image.
  
 
Hints:
 
Hints:
Line 40: Line 40:
 
=== Level designers ===
 
=== Level designers ===
  
Your level should comply with the [[Milestone 2 Design Document/Styleguide|level guidelines]] set by the SuperTux team. See the [[Editor FAQ]] for some help on using the Supertux-sharp editor.
+
Your level should try to follow with the [[Milestone 2 Design Document/Styleguide|level guidelines]] set by the SuperTux team. See the [[Editor FAQ]] for some help on using the Supertux-sharp editor.
If your levels don't comply, or you don't want them as part of the main world, try [[CreatingMods|packaging them as an addon]]. (Note that addons can be under licenses other than GPLv2 and CC-by-SA)
+
If your levels break the rules or you don't want them as part of the main world, try [[CreatingMods|packaging them as an addon]]. (Note that addons can be under licenses other than GPLv2 and CC-by-SA, though they should allow non-commercial distribution if you want them be in the addon manager)
  
 
== Programmers/Code ==
 
== Programmers/Code ==
  
Changes to the code typically affect only parts of bigger files, so it's hard to spot the differences to the original file. Therefore we only accept code contributions in the form of a patch. (Patches also happen to be smaller than full files) This guide will walk you through the process of creating a patch.
+
Changes to the code typically affect only parts of bigger files, so it's hard to spot the differences to the original file. Therefore, we ''strongly'' recommend sending code contributions in the form of a patch. (Patches also happen to be smaller than full files) This guide will walk you through the process of creating a patch.
  
 
We assume that you have a current checkout of the SuperTux repository (see [[Download/Subversion]]) with your changes applied. Then you should first use
 
We assume that you have a current checkout of the SuperTux repository (see [[Download/Subversion]]) with your changes applied. Then you should first use
 +
<code>
 +
svn update
 +
</code>
 +
to merge in other developer's changes.
 
<code>
 
<code>
 
  svn status
 
  svn status
 
</code>
 
</code>
to print you a list of files with a prefix letter. M means you changed the file, C means there is a conflict between your changes and changes from someone else who committed to the repository, and ? means the file is ignored by the version control.
+
will print a list of files with a prefix letter. M means you changed the file, C means there is a conflict between your changes and changes from someone else, ! means the file is missing, and ? means the file is ignored by the version control.
  
You should fix conflicts by editing the conflicted file and using '''svn resolved <filename>''', add files to version control with '''svn add <filenames>''', and remove existing versioned files with '''svn remove'''. (Note that files are never really deleted; you may always check out a former revision when the file still existed.) Finally you can create a patch using Subversion:
+
You should fix conflicts by editing the conflicted file and then using '''svn resolved <filename>''', add files to version control with '''svn add <filenames>''', and remove existing versioned files with '''svn remove'''. (Note that files are never really deleted; you may always check out a former revision when the file still existed.) Finally you can create a patch using Subversion:
 
<code>
 
<code>
 
  svn diff *files* > mypatch.patch
 
  svn diff *files* > mypatch.patch
 
</code>
 
</code>
This will create a file mypatch.patch that contains all changes in the listed files. (You should open the file in a text editor and verify that it contains all your changes and only changes you want to submit). Omit the files argument completely to include all files that have been changed,
+
This will create a file mypatch.patch that contains all changes in the listed files. (You should open the file in a text editor and verify that it contains all your changes but only changes you want to submit). Omit the files argument completely to include all files that have been changed.
  
 
Now you can send off ''mypatch.patch'' using the generic instructions. If you want to apply a patch generated using ''svn diff'', use the following command:
 
Now you can send off ''mypatch.patch'' using the generic instructions. If you want to apply a patch generated using ''svn diff'', use the following command:
 
<code>
 
<code>
  patch -p0 < fix-year.patch
+
  patch -p0 < apatch.patch
 
</code>
 
</code>
  
 
[[Category:Development]]
 
[[Category:Development]]
 
[[Category:Meta]]
 
[[Category:Meta]]

Revision as of 16:18, 7 November 2009

If you would like to contribute to SuperTux, you should follow a series of instructions to make the process as hassle-free as possible for you and the developers.

Why

  • Show your changes to the world, and contribute them to the project!
  • You get write access to our repository and join the team if you contribute enough.

Licenses

We can't use contributions that aren't redistributable under the same license as SuperTux itself. Usually, GPL will infect small code changes automatically. For everything else (like levels, images, sounds, and new programs), make sure that you can release it under GPLv2 (yes, all contributions need to be released under GPL) and also CC-BY-SA for data files such as images, sounds, music, and levels. (Scripts count as parts of levels)

Generic instructions

These instructions apply to every function you may want to adopt.

  1. Join the SuperTux mailing list to stay up to date with recent developments.
  2. Check out the latest SuperTux development version and compile it by following the instructions in the INSTALL file if you want to develop code or levels.
  3. Modify or add something that is either listed in the task list or seems useful to you.
  4. Give us your work:
    • The preferred way is to open a new report on our bug tracker and attach the files to it. (You can upload and attach files to bug reports using the “Upload File” button when filing or perusing them).
    • Alternatively, upload the files to some website or ftp server and send us the link on the mailing list.
    • Do NOT use attachments on the mailing list; the files tend to get big, annoying people, and the mailing list often eats them

Data Files

Contributions which mostly add new files (typically when creating new graphics, sound, music, levels) can simply be put into an archive (preferably .tar.gz or .zip).

The developers will review your work and, if everything seems in order, check it into the repository.

Translators

Please see Translation for instructions.

Artists

Please use the PNG format for small graphics and the JPEG format for large ones. It would be helpful to keep and send the source files as well (the GIMP's .xcf is preferred) so that the team can reuse the image.

Hints:

Level designers

Your level should try to follow with the level guidelines set by the SuperTux team. See the Editor FAQ for some help on using the Supertux-sharp editor. If your levels break the rules or you don't want them as part of the main world, try packaging them as an addon. (Note that addons can be under licenses other than GPLv2 and CC-by-SA, though they should allow non-commercial distribution if you want them be in the addon manager)

Programmers/Code

Changes to the code typically affect only parts of bigger files, so it's hard to spot the differences to the original file. Therefore, we strongly recommend sending code contributions in the form of a patch. (Patches also happen to be smaller than full files) This guide will walk you through the process of creating a patch.

We assume that you have a current checkout of the SuperTux repository (see Download/Subversion) with your changes applied. Then you should first use

svn update

to merge in other developer's changes.

svn status

will print a list of files with a prefix letter. M means you changed the file, C means there is a conflict between your changes and changes from someone else, ! means the file is missing, and ? means the file is ignored by the version control.

You should fix conflicts by editing the conflicted file and then using svn resolved <filename>, add files to version control with svn add <filenames>, and remove existing versioned files with svn remove. (Note that files are never really deleted; you may always check out a former revision when the file still existed.) Finally you can create a patch using Subversion:

svn diff *files* > mypatch.patch

This will create a file mypatch.patch that contains all changes in the listed files. (You should open the file in a text editor and verify that it contains all your changes but only changes you want to submit). Omit the files argument completely to include all files that have been changed.

Now you can send off mypatch.patch using the generic instructions. If you want to apply a patch generated using svn diff, use the following command:

patch -p0 < apatch.patch