Here are our rules and guidelines for contributions.
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.
First, please read our Code of Conduct.
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
-
[Defect reports][24]
-
[Feature requests][25]
-
[Metrics proposals][26]
-
[Refactoring suggestions][27]
We use Git to change, review, and version our source code.
Our default branch is master.
Never push changes directly to master. The master branch MUST be updated
with Pull Requests.
We use the branch-based GitHub flow to manage changes. That means
that anything merged into master SHOULD be immediately available as an
automated production release.
-
The
masterbranch is always stable and deployable. -
To work on something new, branch off
masterand give the new branch a descriptive name:777-feat-unicorn-husbandrywhere:-
777is the related Issue number (optional) -
featis the type of change you're making -
unicorn-husbandrydescribes the change (or gives the changes a meaningful label)
-
-
Regularly rebase that branch against
masterand 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
master, delete it from both your local and remote repository.
git-commit - Record changes to the repository [^1]
If possible, make atomic commits
-
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.
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
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 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 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 [^4] |
| 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 |
The scope should match the name of the package [^2][^3], module, or namespace (as perceived by the person reading the changelog generated from commit messages).
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
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.
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.
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.
To ensure consistency and quality throughout the source code, all source code MUST have:
-
No linting errors
-
A test for every possible cases introduced by your code change
-
100% test coverage
-
Documentation for new features
-
Updated documentation for modified features
Make sure your editor respects the EditorConfig
configuration file we put at the root of the repository.
ESLint
PrettierBefore pushing your code changes make sure there are no linting errors.
TIP!
--fixlint errors and warnings automaticallyMany linting errors can be automatically fixed from the Terminal by running:
npm run lint:js --fix
[][standardjs-url]
-
All JavaScript syntax should adhere to [JavaScript Standard Style
-
Run
npm run lint:jsto evaluate withESLint.
All data MUST be stored separately from source code.
We follow the Twelve-Factor App Config convention, and store configuration details in environment variables.
Our Developer Guidelines for Configuration explains how we do this.
Jest-
Include thoughtfully-worded, well-structured tests in a
__tests__directory with each module. -
Treat
describeas a noun or situation. -
Treat
itas a statement about state or how an operation changes state.
npm run test:create <path/to/file.js>This will generate a Jest spec stub for your JavaScript.
Visual Studio CodeThe best way to troubleshoot your tests is with a debugger.
Read Debugging tests in VS Code
[^1]:
Git - git-commit Documentation. (2019). Git-scm.com. Retrieved February 12, 2019, from https://git-scm.com/docs/git-commit
[^2]:
Package principles. (2014). En.wikipedia.org. Retrieved February 13, 2019, from https://en.wikipedia.org/wiki/Package_principles#Principles_of_package_cohesion
[^3]:
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
[^4]:
Fowler, M. (2019) Refactoring. Retrieved February 13, 2019, from https://refactoring.com/
[24]: https://github.com/commonality/archetypes-rules/issues/new?issue[assignee_id]=&issue[milestone_id=&issuable_template=Defect "Report faulty or unexpected behavior"
[25]: https://github.com/commonality/archetypes-rules/issues/new?issue[assignee_id]=&issue[milestone_id=&issuable_template=Feature "Request a new Feature"
[26]: https://github.com/commonality/archetypes-rules/issues/new?issue[assignee_id]=&issue[milestone_id=&issuable_template=Metrics "Propose Goals, Questions, and Metrics"
[27]: https://github.com/commonality/archetypes-rules/issues/new?issue[assignee_id]=&issue[milestone_id=&issuable_template=Refactoring "Suggest a new Refactoring"