User Tools

Site Tools


playground:repository_guidelines

Guidelines for the official Nightingale Repositories

This is a draft. Thus, it is currently not binding and may get edited by anyone at will. Once it is final, direct edits without discussion will be discouraged.

As the official Nightingale repositories are the central repositories we're working with, we must define some standards to ensure interoperability.

However, don't fear these rules. As long as you don't have push privileges, you cannot mess anything up. If you should miss something listed here, that's no big deal. We'll try our best to improve your request and then merge it in.

Most of these rules are not set in stone. If you're aware of the rules, you may disobey them when appropiate. Exceptions from this rule are explicitly marked with the keyword must.

Codestyle

In general, we are following Mozilla Coding Style. However, we tend to be a bit more strict on line lengths; try to keep it at 80 characters whereever easily possible, this especially applies to comments.

Note that currently some parts currently use 2-Space indentation due to historical reasons. Please stick to the file's indentation schema in such cases, and do not blindly enforce 4 spaces.

Commit rules

Try to commit self-contained entities whereever possible. If you're working in multiple sessions and commit for yourself “at random”, consider squashing them into self-contained entities after you're done. That way code changes can get tracked down easier.

When commiting, please use an appropiate commit message. Try to express the self-contained entity the commit is about in the first line, and use later lines to be more verbose, if required. If you fix a tracked issue, mention the issue by its number.

Merge rules: How to get your code in there

Open an Issue first!

Please open an issue before starting to work on something (if it does not yet exist), and get yourself assigned to it. You can then be sure that nobody else is doing the same work and that your issue is actually in the right repository (for example, most feature requests do not belong in the core repository, but should get implemented as add-on).

Pull Requests

Everyone may request his/her commits to get merged in. To do so, simply fill a pull request at github. It would be great if your commits already suite the code- and commit style in this document, but not a requirement.

Discussing Pull Requests

After a pull request has been issued, it is open for public dicussion. Anyone may comment and suggest improvements, and new commits may get attached to the same pull request.

Pull requests for new, major core features must stay in this phase for at least a week, to allow other community members to comment on the consistency with other parts of the core. All other pull requests may get merged immediately.

While discussing, trusted community members are encouraged to comment whether they want the request to get merged or not. This will later simplify the final decision.

Merging Pull Requests

Trusted community members have the privilege to merge pull requests in. Such a member will do so if all of the following conditions are met:

  • The Pull Request is a bugfix, trivial feature or older than a week
  • He/She knows the code affected by the pull request and read through the whole diff
  • He/She checked the codestyle and commit style to be useable (does not need to be perfect)
  • He/She tested the pull request actually works as advertised, and/or other trusted community members agreed on merging it in without testing
  • He/She tested the pull request does not break building or basic features (a short test is sufficient)
  • At least one other trusted community member reviewed the changes and gave an OK to merge (can be via IRC or as a comment)

Trusted community members must not merge if the above conditions are not met. They are encouraged not to merge pull requests if they are unsure, even if they have push privileges. Merging without another community member commenting positively should get avoided in all non-trivial cases.

Pushing directly

Trusted community members may push their commits directly to the official repositories. If a community member decices to do so, it must be aware of the responsibility that comes with pushing directly and assert that building and basic features are working after each push. Trusted community members are encouraged to use separate branches or pull requests whenever they are unsure.

playground/repository_guidelines.txt · Last modified: 2014/03/06 05:48 by freaktechnik