CONTRIBUTING.md

Contributing

• Contributing
  • Issues and PRs
  • Submitting a Change
    • Commit Message Convention
    • Common Commit Types
    • Breaking Changes
      • What is a breaking change
      • How to approach breaking changes
      • Marking changes as breaking
      • Removing deprecated functionality
    • Reverting Commits
    • Highlight your code snippets in your messages
  • Release Process
    • 1) Feature Branches (regular changes)
    • 2) Pre-Releases (Beta / Release Candidate branches for complex changes)
    • 3) Experimental Releases

---

Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.

Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project you agree to abide by its terms.

Issues and PRs

If you have suggestions for how this project could be improved, or want to report a bug, open an issue! We'd love all and any contributions. If you have questions, too, we'd love to hear them.

Submitting a Change

• Clone the repo
• npm install
• git checkout -b my-branch-name. Short, accurate and lowercase branch names are recommended.
• Do your changes and make sure:
  • Your commit(s) are following Conventional Commit Conventions ✅
    • NOTE: We use semantic releases. This means, all commits are processed to determine next version as well as producing release notes when a PR is merged in main. PR is approved by at least by one of the Codeowners ✅
• Merge your changes.

Commit Message Convention

Before committing think about the message you will be sending to consumers. Be short and straight to the point. We currently use Conventional Commits.

Common Commit Types

• feat → Addition or removal of features. Eg: feat: add table on landing page, feat: remove table from landing page. Will increase the minor version.
• fix → Bug fixing, followed by the bug. Eg: fix: illustration overflows in mobile view. Will increase the patch version.
• refactor → Code refactors. E.g. refactor: change to use shared merge refs hook in Menu. Will increase the patch version.
• chore → Will not trigger a release. Code that package won't output. E.g. chore: add revert documentation to contributing docs.
• BREAKING CHANGE: or BREAKING CHANGES: footer → Will increase the major version. Breaking changes are only allowed for the feat and fix commit types.

Breaking Changes

What is a breaking change

A breaking change is any change in library that could break existing consumer's code. Or, in other words, these are changes that might require consumer to update their code before they can use the latest version.

Having breaking changes forces consumers to either stick with older version of the library or make changes when they might not have time for it.

Examples of breaking changes include changing prop type or name, removing exported type or function, bumping major peer dependency version, etc.

How to approach breaking changes

In case you're removing or renaming something, see if you can instead mark that piece of code as deprecated (using @deprecated tag). This will inform consumers of library that the particular piece of code should not be used. When applicable, provide an alternative.

Marking changes as breaking

If changes are breaking, they must contain BREAKING CHANGE or BREAKING CHANGES in the footer of the commit message. Breaking changes are only allowed for the feat and fix commit types.

git commit -m 'feat: remove "foo" export

BREAKING CHANGE: "foo" export no longer available, use "bar".'

Removing deprecated functionality

If we followed suggestion from the previous section, we're likely to end up with a bunch of deprecated functionality that we don't want to maintain forever. Every once in a while we'll do a breaking change release where the only changes will be removal of deprecated features. This should mean that, if consumers migrated deprecated features in timely manner, the breaking change should actually be painless.

Reverting Commits

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>. followed by a reason for the revert, where the hash is the SHA of the commit being reverted:

revert: feat: add type to foo var

This reverts commit a7721472aad3bab9deff29e184df9a05b274e2dc. Reason to revert.

Keep in mind that the standard commit message from git revert is slightly different, so make sure to use the --edit option when running git revert to adjust the commit message.

You can follow any of the regular prerelease and release processes documented below with revert commits.

Highlight your code snippets in your messages

Wrap your message in double quotes and escape the back ticks.

git commit -m "feat: add \`boolean\` prop \`open\` to \`<dialog>\`"

---

Release Process

1) Feature Branches (regular changes)

The most common process is to branch off from main, add your code and merge it to main with Rebase and merge option. Conventional Commits and Semantic Releases will take care of the rest. See image below for visual clarity:

2) Pre-Releases (Beta / Release Candidate branches for complex changes)

(See image below for visual clarity)

• Branch off from main to your feature-branch.
• Commit the code you need and do your local tests.
• Open a PR and wait for approval.
• Checkout beta branch and cherry-pick your changes from feature-branch:
• If you previously checked out beta, always ensure it is always up-to-date with main before cherry-pick'ing. By doing it, you release a beta version based on the current main branch + your cherry-picked changes.
• NOTE: Everytime a push in beta occurs a new version gets deployed in NPM. Changelog, Package.json and Lock files also change. Update your local beta branch after the release has finished.
• Use the beta package to test your application.
• NOTE: ⛔ Never merge beta in main.
• After tests are complete you either:
• Merge your feature-branch in main.
• cherry-pick your feature-branch commits into an rc branch to hold / group those for a release in the upcoming weeks.

3) Experimental Releases

(See image below for visual clarity)

Similar to pre-releases (2), they're not required to either be tested through beta or rc branches. They are one off simpler and less complex experimental features.

• Branch off from main to your feature-branch.
• Commit the code you need and do your local tests.
• Open a PR and wait for approval.
• Branch off from feature-branch to a branch prepended with exp-*. eg. exp-feature-branch.
• When pushing your changes a new experimental release is promoted. eg. 1.3.0-exp-feature-branch.1.
• NOTE: ⛔ Never merge exp-* branches in main.
• After tests are complete delete the exp-* branch in origin.