Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
469 lines (301 loc) · 14.5 KB

CONTRIBUTING.md

File metadata and controls

469 lines (301 loc) · 14.5 KB
Raw

Contributing Agreement

Here are our rules and guidelines for contributions.

Contribution and collaboration We gratefully accept contributions like documentation, testing, defect-fixes, refactoring, and feature requests. If you're down, scroll down!

Table of Contents

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1. Code of Conduct

First, please read our Code of Conduct.

2. Support

Question Go to Stack Overflow for Questions and Problems

Do not open issues for general support questions on GitLab. You've got much better chances of getting your question answered on dedicated support platforms, the best being Stack Overflow.

We use GitLab issues for

3. Git

We use Git to change, review, and version our source code.

3.1. Default branch

Our default branch is main.

Never push changes directly to main. The main branch MUST be updated with Pull Requests.

3.2. Workflow Model

We use the branch-based GitHub flow to manage changes. That means that anything merged into main SHOULD be immediately available as an automated production release.

GitHub flow example

  • The main branch is always stable and deployable.

  • To work on something new, branch off main and give the new branch a descriptive name:

    777-feat-unicorn-husbandry where:

    • 777 is the related Issue number (optional)

    • feat is the type of change you're making

    • unicorn-husbandry describes the change (or gives the changes a meaningful label)

  • Regularly rebase that branch against main and push your work to a branch with the same name on the server.

  • When you need feedback, help or think you are ready, submit a pull request.

  • Once the branch has been merged (or rebased) into main, delete it from both your local and remote repository.

4. Commits

git commit symbol

Citation git-commit - Record changes to the repository 1

4.1. Atomic Commits

If possible, make atomic commits external link, which means:

  • Each commit should contain exactly one self-contained functional change

  • A functional change should be contained in exactly one commit

  • A commit should not create an inconsistent state (such as test errors, linting errors, partial fix, feature with documentation etc...)

A complex feature can be broken down into multiple commits as long as each one keep a consistent state and consist of a self-contained change.

4.2. Commit Message Format

Angular%20Commit%20Message%20Format

Light bulb TIP: How to Write Perfect Commit Messages Every Time

Try a CLI tool like Commitizen, which presents a step-by-step wizard to create perfect commit messages (till you get the hang of it).

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.

The scope of the header is optional.

The footer can contain an issue closing pattern external link.

4.3. 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.

4.4. Type

Type declares the kind of changes you're making.

Type values MUST be one of the following:

Type Description
build Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
chore Administrative and management tasks
Warning! DEPRECATED
ci Changes to the 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 Changes made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior 2
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

4.5. Scope

The scope should match the name of the package 34, module, or namespace (as perceived by the person reading the changelog generated from commit messages).

4.5. Subject

The subject contains succinct description of the change:

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

  • Don't capitalize first letter

  • No dot (.) at the end

  • Limit to 72 characters or fewer

4.6. 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. When only changing documentation, include [ci skip] in the commit body.

4.7. Footer

The footer should contain any information about Breaking Changes and is also the place to reference GitLab 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.

4.8. Examples

fix(pencil): stop graphite breaking when too much pressure applied
feat(pencil): add 'graphiteWidth' option

Fix #42
perf(pencil): remove graphiteWidth option

BREAKING CHANGE: The graphiteWidth option has been removed.

The default graphite width of 10mm is always used for performance reasons.

5. Source Code Style Guidelines

To ensure consistency and quality throughout the source code, all source code MUST have:

  1. No linting errors

  2. A test for every possible cases introduced by your code change

  3. 100% test coverage

  4. Valid commit message(s)

  5. Documentation for new features

  6. Updated documentation for modified features

Important Make sure your editor respects the EditorConfig external configuration file we put at the root of the repository.

5.1. Linting

ESLint logo ESLint Prettier logo Prettier

Before pushing your code changes make sure there are no linting errors.

Tip! TIP! --fix lint errors and warnings automatically

Many linting errors can be automatically fixed from the Terminal by running:

npm run lint:js --fix

5.2. JavaScript Standard Style

JS Standard Code Style

  1. All JavaScript syntax should adhere to JavaScript Standard Style external.

  2. Run npm run lint:js to evaluate with ESLint.

6. Configuration

dotenv-extended

All data MUST be stored separately from source code.

We follow the Twelve-Factor App Config convention, and store configuration details in environment variables.

info Our Developer Guidelines for Configuration explains how we do this.

7. Testing

Jest logo Jest

  1. Include thoughtfully-worded, well-structured tests in a __tests__ directory with each module.

  2. Treat describe as a noun or situation.

  3. Treat it as a statement about state or how an operation changes state.

Tip! Use npm run test:create <path/to/file.js>

This will generate a Jest spec stub for your JavaScript.

8. Troubleshooting

vscode logo Visual Studio Code

The best way to troubleshoot your tests is with a debugger.

tip Debugging Jest with VS Code

Read Debugging tests in VS Code link-external for step-by-step set-up and execution instructions.

9. References

Git - git-commit Documentation. (2019). Git-scm.com. Retrieved February 12, 2019, from https://git-scm.com/docs/git-commit

Package principles. (2014). En.wikipedia.org. Retrieved February 13, 2019, from https://en.wikipedia.org/wiki/Package_principles#Principles_of_package_cohesion

Brack, F. (2017). Why Do You Need To Know Package Cohesion Fundamentals?. Retrieved from https://medium.com/@fagnerbrack/why-do-you-need-to-know-package-cohesion-fundamentals-8a3510cba2c1

Fowler, M. (2019) Refactoring. Retrieved February 13, 2019, from https://refactoring.com/

Footnotes

  1. ↩
  2. ↩
  3. ↩
  4. ↩