Skip to content

Minimal requirements

Jump to bottom Edit New page
Julian Gonggrijp edited this page Oct 31, 2013 · 2 revisions

These are requirements on contributions, not on the way in which you work on those contributions. For example, this page does not tell you how you should work with branches or issues. There are no real requirements on the way in which you work; only recommendations and guidelines.

In addition, the requirements outlined here only apply to the master branch of the-xkcd-community/the-red-spider-project (= the repository this wiki belongs to), also known as the integration branch. Work on any other branch need not meet these requirements (even on a master branch on a fork), in fact it need not meet any requirements at all (apart from what you decide or agree upon with your collaborators).

Work need not meet these requirements before it can be submitted in a pull request. However, you should keep the requirements in mind while working on a branch that you want to issue a pull request for. A pull request can only be granted if all requirements are met, because pulling the requested branch will bring your work into the integration branch.

Table of Contents

Attribution

All program source files should contain a copyright statement like the following at the top: 

Copyright YYYY authors_of_major_contributions
Licensed under the Red Spider Project License.
See the License.txt that shipped with your copy of this software for details.

Acknowledgements: X provided idea A, Y provided idea B.
Minor contributions were made by Z/by several authors;
please refer to the Authors.txt that shipped with your copy of this software.

The second part (with the acknowledgements) is optional.

authors_of_major_contributions includes you if you did anything creative, e.g. if you wrote the initial version or if you contributed to the program logic. Non-creative maintainance work (e.g. correcting typos, changing names (unless your replacements are very original)) could go with the minor contributions or you could put your name in the Authors.txt.

SVG files are similar to program source code, insofar that you can add copyright and license information in a similar way. This is also required. In general, this applies to all kinds of files that offer a convenient "spot" for copyright and license information.

Most other file types (ASCII art, Markdown, etcetera) don't offer a convenient spot for copyright information. If you create or edit any of those, always add your name to Authors.txt.

Documentation

If your contribution is a program, users must be able to figure out how to use it without reading your code. Possible ways to ensure this include:

  • to include a comment at the top of the source file with usage information;
  • to print usage information if your program is invoked without arguments;
  • to print usage information if your program is invoked with a -h or --help argument;
  • to put an explanation of your program under $RED_SPIDER_ROOT/doc;
  • to put an explanation of your program on the wiki (see State of the art);
  • to put an explanation of your program in the Readme (only if your program is of central importance to the project).
The preferred way is to print a short usage message if your program is invoked with -h, and to put a longer explanation in $RED_SPIDER_ROOT/doc which is also shown when your program is invoked with --help.

Libraries should be documented as well, but obviously not all options listed above are available in that case.

In general, document everything that people need to know in order to use your stuff. For example, if you add an SVG file and people need a non-websafe font in order to render it correctly, document that. If your program isn't automatically installed by setup.py, tell users how to do it. And so on.

Portability

Programs should work on recent versions of Windows with cmd.exe and on Mac OS X and Linux with bash.

Exceptions:

  • if you already started working on a less-portable program before reading about this requirement;
  • if you couldn't find a way to realise your idea in a portable way.
In these cases your program should still be ported to the other platforms, but it can be postponed until after the pull request.

Usability

Obviously, if something is to be pulled into the integration branch it should offer something new. It need not be much, but what is added should be reasonably well-behaved:

  • it has been verified to work as expected under expected conditions;
  • it doesn't crash out of the blue;
  • it can be terminated normally.
Ideally, your program should be installed by setup.py. At present this is still a bit hard if your program needs to be compiled (see issue #33), so in that case it can be postponed until after the pull request. However, note that you should still document how to install your program.

Non-requirements

  • A contribution should be usable but it doesn't need to be useful.
  • A contribution doesn't need to be big; it's fine to do a pull request for something very small.
  • A contribution doesn't need to be high quality (though quality-improving work is always very welcome).
  • A program doesn't need to be feature-complete in order to have it pulled.
Add a custom footer
Add a custom sidebar
Clone this wiki locally