We use a Kanban-style board to prioritize the work. For example the EOS rate project board.
We have added a additional column to the default automated board in order to maintain a prioritized
To Do column.
When a new issues is create you need to explicitly use the project option on the GitHub issue to include it in the board; Once you do that it gets automatically added to the New Issues column.
Periodically we move the new Issues to the
To Do column and manually and give it the appropriate priority.
When you start working on a task you must manually move it to
In Progress column.
We use GitHub flow https://guides.github.com/introduction/flow/ to request code changes.
We develop on
release using tags with semver versioning.
New and reopened
pull request are automatically added to the board in the
In Progress column.
When the pull request is closed is moved to the
Done column automatically. If the pull request closes and issues it is properly stated with the GitHub keywords closes in the pull request it gets automatically moved to the
Done column too.
Branch Naming Convention
Name every branch for your pull requests using the following simple convention:
- Always use lowercase.
- Choose the type.
- Meaningful and short descriptions.
- Use hyphens as separators.
- Use the imperative, present tense: "change" not "changed" nor "changes".
- Use the
issuenumber to reference it in the branch.
^--^ ^---------^ ^-^
| | |
| | +-> Issue number
| +-> Short description of the task
+-> Type: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test, content, or devtools
Pull Request General Guidelines
- Please check to make sure that there aren't existing
pull requestattempting to address the
- Check for related
- Non-trivial changes should be discussed on an issue first.
- Develop in a topic branch, never on master:
git checkout -b type/task-issue.
- Provide useful
- Make well scoped
atomicpull requests. 1 PR per feature of bug fix.
- Link the
pull requestdescription 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, following GitHub conventions and standards. 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.
We follow the commit message conventions as shown below:
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:
header is mandatory and the
scope of the header is optional.
feat: add a new method
| +-> abstract in present tense.
+-------> Type: build, ci, docs, feat, fix, perf, refactor, style, test, content, or devtools.
The commit message cannot be longer than 100 characters. This allows the message to be easy to read on GitHub as well as various
The footer should contain a closing reference to an issue if any.
The commit message must be like the following 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.
Even more samples
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.
- build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
- chore: What a user would not see (changes to the build process, configuration, etc).
- ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs).
- docs: Documentation only changes.
- feat: A new feature for the user.
- fix: A bug fix for the user.
- perf: A code change that improves performance.
- refactor: A code change that neither fixes a bug nor adds a feature (renaming a variable).
- revert: Reverts a previous commit.
- 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.
The scope is the name of the component or service that it affects. Eg:
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
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.
The footer should contain any information about Breaking Changes and is also the place to
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.
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.
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".
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.
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.
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.
When a documented feature does not behave as documented, or when a security issue is discovered and fixed without altering documented behavior.
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
We use the standardjs code style.
Continuous Integration and Delivery
This is a work in progress, we are going to probably want to use Netifly and TravisCI.
We use pre-commit hooks to ensure that both the code standards and commit message conventions are met.