Contribution guidelines

First off, thank you very much for your interest in contributing to the Star-Phor project.

All types of contributions are welcome and valued for star-phor, star-phor-input and for this wiki itself.

Bug reports

Before reporting a bug, please verify that you are using the last publish version.

If you have found a bug, you can report it using the star-phor mailing list. Please try to be as descriptive as possible when filing a report and provide all relevant details. Ideally, developers should be able to reproduce your issue in their machine.

Patches

If you have modified star-phor and you think that your changes could be useful to other users, you can submit a patch with your modifications. To generate a patch, you can use the git format-patch command. To submit it to the maintainers, simply send it to the star-phor mailing list.

Code style

The star-phor project does not enforce a formal code style, but follows some conventions. The most important aspect is consistency, and the codebase itself is the best reference. Note that developers tend to be more explicit in star-phor. We also use yoda conditions. If you are a vim user, we provide a custom .vimrc that automatically handles line breaks, comment formatting and other aspects of the code style. You can download this file here.

General guidelines

Use /* */ for comments, not //.
Try to explicitly initialize all variables when declaring them (= 0, = NULL, = STRUCT_NULL, ...).
Use a space after if, for, while, switch.
Do not use a space after the opening ( or before the closing ).
Use soft-tabs (spaces) for code indentation. Indentation is 2 spaces only.

C Files structure

Copyright header with LICENSE notice.
Local project headers.
External/system headers.
Forward declarations of opaque datatypes.
Section banners followed by function definitions.

Blocks

{ on same line preceded by a single space (except functions).
} on its own line unless continuing a statement (if else, do while, ...).

Functions

Return types in its own line
Function name in its own line
Each argument in its own line. ( in the same line of the first argument and ) in the same line of the last argument.
Opening { in its own line.

Variables

In pointer declarations, * is adjacent to the variable type, not the name: int* p, not int *p.
Variables are initialized at declaration.

Preconditions

Use ASSERT to document and check function preconditions at the top of the function body, after variable declarations and before any logic.

Error handling

Star-Phor uses the res_T type, provided by the rsys library, to handle errors. When calling functions that return an error status, check the return value:

res = some_function(arg, &out);
if (RES_OK != res) { goto error; }

The exit label handles cleanup and returns res. The error label performs any error-specific fixup (such as nulling output pointers and freeing the memory) and then falls through to exit.

Text length

Wrap lines to 80 chars.

Commits and Commit messages

Please try to respect the one-change-per-commit rule.

Provide a clear and descriptive commit message. Commit messages are expected to follow the form

subject [linebreak]
[linebreak]
commit message

Both the subject and the commit message should be wrapped to 72 characters.