OpenShift Contributor Guidelines

November 10, 2015 · View on GitHub

Summary

Communication

Google+
IRC
Mailing list
Twitter
Trello

Using git and github

Squash commits
Enhancements and updates
Bug fixes

Various expectations

Fail gracefully
Secrets in quickstarts
Handling sensitive data from gears
Provide machine-readable script outputs
Hardcoding assumptions from the Online project

Summary

For any project with more than a handful of contributors, it is helpful to agree on some guidelines for participation. This document walks through various expectations that have developed for the OpenShift project. Some may be reactions to mistakes that we are still working to correct, so we request patience with past transgressions. With awareness that any open source project guidelines must sometimes bend to allow specific circumstances, we hope these will be useful guidelines for making this project successful. That also means guidelines should be limited in order to avoid becoming TL;DR.

Communication

You do not work in a vacuum. OpenShift developers are happy to help and guide you.

Using git and github

Squash commits

DO:

Use git rebase -i to combine multiple interim commits into single coherent commits with helpful commit logs before submitting a pull request. This keeps our commit logs readable.

AVOID:

Pull requests with lots of small commits for tweaks and interim saves. This is just noise in the log.
Squashing commits from unrelated changes into one large commit - this obscures the purpose and makes rollback of individual changes harder.

Enhancements and updates

DO:

git commit without -m for multiline messages.
Format commit messages like this:

script/class/component: short description of the work done

Link to Trello card, PEP, mailing list, or other planning documentation
Detailed explanation

This makes later searches of the commit log much easier.

AVOID:

Non-descriptive one-line commit messages like this:

Changed foo to bar

(where, why?)

broker card 123

(You have the card open; at least cut and paste the description and link.)

Bug fixes

DO:

git commit without -m for multiline messages.
Format commit messages like this:

script/class/component: short description of the fix, symptom, or bug

Bug <number>
Bugzilla link <https://bugzilla.redhat.com/show_bug.cgi?id=number>
Detailed explanation

Some benefits from this:

Adding the short description helps readers search the commit log.
Seeing "bug number" (but not "BZ" or "Bugzilla"), our GitHub detector will automatically add a comment on the bug once your commit merges to master (which lets QE know that your code is in). This can be anywhere in the message.
Including the BZ link (which you probably have handy) makes it that much easier to get to it later (when you probably do not).

AVOID:

Non-descriptive commit messages like this:

Bug <number>

Tiny fix

Various expectations

Fail gracefully

DO:

Expect and check for failure conditions and raise or wrap as appropriate.
Set a timeout (preferably configurable) on any operation that could block forever.
If possible, provide error messages that help the user understand the context of the error and what to do about it.

Secrets in quickstarts

DO:

Salt or otherwise scramble secrets embedded in quickstarts such that they are unique per application, not universally shared. An obvious example needing protection would be Rails secret_token.rb. See how to handle this example.

Handling sensitive data from gears

Some environment variables and data from gears might be considered sensitive. Private keys, passwords, and tokens certainly are. Use your judgment about everything else.

AVOID:

Your cartridge storing any sensitive data in MongoDB. DB contents are too likely to be displayed indiscreetly.
Logging messages outside the gear (e.g. in mcollective.log) that contain sensitive data. These messages should be scrubbed of sensitive data.

Provide machine-readable script outputs

DO:

With any script, provide at least an option for machine-readable output (well-defined e.g. YAML, JSON, XML, a DSL, etc.). The default may be intended for human consumption but options should enable other scripts based on your script.

Hardcoding assumptions from the Online project

AVOID:

Coding constants in origin-server for specific gear profiles, cartridges, external integration points, or anything else we might reasonably expect an OpenShift administrator to want to customize.

DO:

Use configuration files, cartridge manifests, and plugins to enable specific behavior.