We love contributions, so thanks for choosing to get involved with the Carbon project.
- Setting up dev environment
- Codebase Overview
- Testing
- Semantic Versioning
- Git commit messages
- Contributor License Agreement (CLA)
- Have a question?
To help you get setup for working on Carbon, we have a dev environment setup guide with more information.
More details can be found in our Codebase Overview guide.
More details about how we test can be found in our Testing Guide.
We use GitHub Issues to keep track of incoming bugs and enhancement requests. Before you raise a new issue, please have a look to see if your problem does not already exist.
Please provide as much as possible to help us replicate and understand the problem. The best way to do this is to provide a sandbox that reproduces the issue. We have a starter template to help you do this:
Most bug fixes and enhancements are trivial and can be implemented and raised as a pull request as normal. For larger, complex changes however, we ask if an Request for Comments (RFC) is raised first.
We accept two standard workflows for raised pull requests:
- Feature branch workflow - for internal Sage contributors with access rights to the repository. Features should be developed in a branch off
masterand a pull request raised to merge into back intomaster. - Forking workflow - for third-party contributors outside Sage. You should fork the repository and make your changes there, then raise a pull request to merge back into the Carbon
masterbranch.
Carbon uses semantic versioning - we release major versions for breaking changes, minor versions for new features or non-essential changes, and patch versions for critical bugfixes.
We automate our release process by standardising our git commit messages using the conventional-commits format, and the semantic-release package - which uses commit messages to determine the next version number, generate release notes, and publish a new version.
Following the conventional-commits format, all commit messages should be structured as below.
<type>([optional scope]): <description>
<BLANK LINE>
[optional body]
<BLANK LINE>
[optional footer]
Carbon accepts the following commit types, shown with the corresponding release that is generated using semantic-release:
| Type | Description | Release Type |
|---|---|---|
feat: |
Introduce a new feature | minor |
fix: |
A bug fix | patch |
docs: |
Documentation only changes | ❌ |
style: |
Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) | ❌ |
refactor: |
A code change that neither fixes a bug nor adds a feature | ❌ |
perf: |
A code change that improves performance | patch |
test: |
Adding missing tests or correcting existing tests | ❌ |
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) | ❌ |
chore: |
Other changes that don't modify src or test files | ❌ |
revert: |
Reverts a previous commit | patch |
Any of the types in the previous table can trigger a major release by including BREAKING CHANGE: in the commit footer, or appending a ! after the type/scope.
Messages are automatically validated against the conventional-commit guidelines when a commit is made. We use commitlint and husky to do this.
huskymanages the git commit hooks defined inpackage.json- we have a hook that runs the commit message via
commitlint - we use the
@commitlint/config-conventionalconfig huskyaborts the commit if the commit message is in the wrong format
For contributors external to Sage, we require a CLA to be signed before we can accept your pull request. Please find links to the relevent documents below:
- Internal Sage contributors are invited to post in our #carbon Slack channel.
- External contributors are invited to use our GitHub Issues page.