Skip to content

Latest commit

 

History

History
105 lines (68 loc) · 6.37 KB

CONTRIBUTING.md

File metadata and controls

105 lines (68 loc) · 6.37 KB
Raw

Contributing to Carbon

We love contributions, so thanks for choosing to get involved with the Carbon project.

Contents

Setting up dev environment

To help you get setup for working on Carbon, we have a dev environment setup guide with more information.

Codebase Overview

More details can be found in our Codebase Overview guide.

Testing

More details about how we test can be found in our Testing Guide.

Bugs

Where to find known issues

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.

Reporting an issue

Please provide as much as possible to help us replicate and understand the problem. The best way to do this is to provide a simplified example using Codesandbox. We have two templates available using JavaScript and TypeScript to help you do this.

Proposing a large change

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.

Raising a Pull Request

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 master and a pull request raised to merge into back into master.
  • 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 master branch.

Semantic Versioning

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.

Git commit messages

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

Denoting a breaking change

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 validated on commit

Messages are automatically validated against the conventional-commit guidelines when a commit is made. We use commitlint and husky to do this.

Contributor License Agreement (CLA)

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:

Have a question?

  • Internal Sage contributors are invited to post in our #carbon Slack channel.
  • External contributors are invited to use our GitHub Issues page.