Contributing Guidelines

Pull Request General Guidelines

  • Please check to make sure that there aren't existing pull requests attempting to address the issue mentioned.

  • Check for related issues on the issue tracker.

  • Non-trivial changes should be discussed on an issue first.

  • Develop in a topic branch, never on master: git checkout -b topic-branch.

  • Provide useful pull request description.

  • Make "atomic", well scoped pull requests. 1 PR per feature of bug fix.

  • Link the issue on the pull request description for cross references between code and issues.

We only support support squash merge of the pull requests as a best practice for ensure the master log is maintained clean and relevant, without requiring the pull request to be rebased. This strategy requires that all pull request made are "atomic", in other words they solve one thing only. One pull request per feature, bug fix or documentation update.

Commit Message Guidelines

We have very precise rules over how our git commit messages can be formatted by following the Conventional Commits Standard. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the project change log.

Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory and the scope of the header is optional.

Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

The footer should contain a closing reference to an issue if any.

Samples:

docs(changelog): update changelog to beta.5
fix(release): need to depend on latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users need the latest of these.

Revert

If the commit reverts a previous commit, it should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Type

Some examples:

  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)

  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)

  • docs: Documentation only changes

  • feat: A new feature

  • fix: A bug fix

  • perf: A code change that improves performance

  • refactor: A code change that neither fixes a bug nor adds a feature

  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)

  • test: Adding missing tests or correcting existing tests

  • content: Adding or removing content

  • devtools: Developer tooling related

Scope

The scope is the name of the component or service that it affects. Eg:

  • common

  • smart-contracts

  • webapp

  • storage

  • graphql

  • frontend

  • demux

  • docker

Subject

The subject contains a succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"

  • don't capitalize the first letter

  • no dot (.) at the end

Body

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.

Footer

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes.

Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.

Reporting bugs

Before submitting your issue please check that you've completed the following steps:

  • Made sure you're on the latest version.

  • Used the search feature to ensure that the bug hasn't been reported before.

Bug reports should contain the following information:

  • Summary: A brief description.

  • Steps to reproduce: How did you encounter the bug? Instructions to reproduce it.

  • Expected behavior: How did you expect it to behave?

  • Actual behavior: How did it actually behave?

  • References: Links to any related tickets or information sources.

  • If possible, attach visual documentation of the bug. Screenshot or animated gif.

Releases

We release the production software version using github tags following Semver, except the version roles have the semantic names, "Breaking.Feature.Fix" instead of "Major.Minor.Patch".

Breaking.Feature.Fix

We don't decide what the version will be. The API changes decide. Version numbers are for computers, not people. Release names are for people.

Breaking

Any breaking change, no matter how small increments the Breaking version number. Incrementing the Breaking version number has absolutely no relationship with issuing a release.

Feature

When any new feature is added. This could be as small as a new public property, or as large as a new module contract being exposed.

Fix

When a documented feature does not behave as documented, or when a security issue is discovered and fixed without altering documented behavior.

Changelog Generation

On each release we generate a changelog file to document changes using the standard git-changelog package. There's an npm task for it.

Advanced Git tools

There are also tools like Hub and git-extras that facilitate interacting with Github. You can leverage these tools to contribute to this repository.

Pre-commit Hooks

We use pre-commit hooks to ensure that both the code standards and commit message conventions are met.

PreviousPhilosophyNextIdea Validation

Last updated