Skip to main content

Overview

Contributing to Gesso​

Before adding functionality to Gesso it's important to gauge with the team whether that change is generic enough to be worthwhile adding it to Gesso, or is it a more specific usecase to your project. If your work is not approved by Gesso team it may not get merged in.

Gesso team prefers git rebase over git merge in order to help keep a cleaner/linear git history.

General workflow​

  • Create a branch GESSO-XXX-description
  • Make the necessary changes
  • Run the tests for the modified packages pnpm test --filter="@acromedia/packagename
  • Run pnpm lint:fix and pnpm build to ensure there is not issues with the code.
  • Create a merge request, ensure the pipeline succeeds, then move the ticket into "UX Review" (if required) or "Technical Review" (if no visual changes were made)

Conflicts​

When resolving conflicts with your development branch against the main branch, it's important to only rebase with main. To make the rebase easier for you, squash your commits into 1 single commit and then rebase over that single commit. IE: if you have 12 commits in your branch run git reset HEAD~12 git add . && git commit -m "Some meaningful message" Then run git rebase main

Backwards Compatibility​

Gesso maintains compatibility through 1 entire major version, meaning if you deprecate something in v4 it must stay in place through the entire lifetime of v5, when we release v6 deprecations and any functionality to maintain backwards compatibility will be removed.

When deprecating something you must flag it using the @deprecated annotation The message should let users know what the replacement is, and also what version the deprecation was added.

/*
 * @deprecated Use X instead.
 *
 * Remove V6
 */

In the above example we are current on v4 so the removal comment is for v6. This helps developers at each major release find and remove any deprecations that are to be removed in the next major release.

When deprecating something you will often need to add some logic in order to handle backwards compatibility with the old way AND the new way. Any functionality that is used for backwards compatibility should also have a comment explaining it's use for backwards compatibility and what version it should be removed.

// Handles backwards compatibility for X
// Remove V6
const myCompatibilityHandler = () => {
  // Do some things to handle both cases.
}

Committing your changes​

Prior to pushing your merge request for review you need to create a changeset.

Before following the steps below ensure you run this from the root of the project.

warning

You should NEVER tag a major release. This is handled by Gesso team only.

  • pnpm changeset: this will ask you some questions about your changes.
    • Select minor if you are adding a new feature.
    • Select patch if you are fixing a bug, or making minor changes to something.
    • Enter a meaningul message that clearly explains what your change entail. But keep it short... These messages will appear on the changelog.
  • git add .changeset
  • Commit your code and push.