-

contribution policies and guidelines

We have some strict rules, and some helpful guidelines to have the Pike repository working smoothly and maintaining some degree of order in the Pike development process. Rules are not negotiable, guidelines are there to help you and the rest of us, but breaking them isn't an offense that would terminate write access rights. The primary rule is employing common sense, though; we prefer to stay clear of lengthy documents of law on all obvious dos and don'ts.

Strict rules for git write access

To get write access to the Pike git repository, we require:

	Pike copyrights - we consider all contributions to Pike donations and claim copyright for the entire Pike repository. This also means that IDA will have full power to take legal actions against anyone who would actually manage to break the license.
	Common sense - show that you are worthy of the trust we show you by granting access to the server and repository, and when in doubt, try to get in touch with us. We would like to maintain good relations to the Pike community, and especially so to those contributing time and energy.
	A working mail address that we can use to get in touch with you when needed, for instance to inform you of technical matters about the server or to point out something about a recent commit.

Working code

It might sound obvious, but from our own experience we know how difficult it is to keep the code on the tip of the git compilable. Therefore we request that you test that your code compiles at least on your own machine. With the aid of our automatic compilation servers you should also be able to verify that your additions or changes compile and run on all the architectures available to us.

Documentation

We require that all new user accessible (from pike programs) symbols (functions, constants, classes etc) are documented with pike AutoDocs. No one knows your code better than you. In addition to this we have over the years discovered three things that need to be documented, no matter how clean code you wrote or how good variable names you chose. The three are complex algorithms, complex program flows and complex data structures, which should be documented with applicable code comments.

Assimilating code

If you cut and paste code from external sources (libraries and similar) into Pike, you must first make sure that you do not violate its license by borrowing (donating, as per the rules above) it for inclusion in Pike. GPL code, for instance, can not be added to Pike, unless you also happen to own it or have a copy under a license that allows you to do so.

The second thing you need to do is to mark the affected areas in the code with a begin and end comment, like this (replacing "libjpeg/6b" with the name and version, where applicable, of your source):

/* Start of code borrowed from libjpeg/6b */ [...] /* End of code borrowed from libjpeg/6b */

The same goes for code inspired by other code to the degree where the code can be said to be based on the original, in the copyright sense of the word. The reasoning behind this rule is to simplify merging the code with a later release of the upstream, or reverting the code altogether, in case we would have to, at a later date.

Naming conventions

In order to make Pike as homogenous and easy to learn, use, read, write and maintain, employing common naming conventions helps. A lot. Please stick to common Pike conventions in interface design; module and class names in Pike are CamelCase (capital letters marking new words or abbreviations such as HTTP, no underscores), function and variable names are lower_case (words separated by underscores) and #defines and constants are ALL_CAPS. Try using descriptive names for user visible components. For local variables, sticking to short names often helps up code readability, though.

Filenames

There are several don'ts regarding file names, since we try to be as cross platform as possible. Don't use any non-ASCII characters, control characters or whitespace in filenames. Never put two files with the same name but in different cases in the same directory. Keep filename lengths at most 31 characters long.

Empty files

Empty files, i e files with a file size of exactly zero bytes, behave strange in some situations (SMB, NFS and Windows, for instance). The solution is of course to not create empty files. Put a newline in them, for instance, and the problem will never arise.

File endings

All text files should end in a newline character. This is needed for some text file detection heuristics on some systems for proper operation. A lot of trailing empty lines is however just as annoying as trailing spaces, so please do not litter the place.