Adding code to ink

There are many reasons why someone outside the ink team might want to add code to the repository: fixing bugs, adding new features or components, or simply contributing to documentation.

For all of those reasons (and others), we have some helpful tips on how to get the best experience when adding code to the ink repository.

All contributors to ink, including the ink team, go through the same review process: they create a branch, make changes and create a PR against master to be reviewed by the rest of the team.

Before adding any code, share your idea on the ink channel and let us know how we can help you with it!

Read this to learn how to ask questions in the channel.

As an alternative, you can also send us a message in the #design-technology channel or reference @design-technologists in any channel if you have questions!

Clone ink into your machine using

$ git clone git@github.com:carta/ink.git

Run cd ink to enter the ink folder and run yarn install to install all ink dependencies.

If you intend to add something to the ink documentation, you'll need to run the commands for the Docs environment below.

Depending on what you're doing on ink, you'll have contact with different environments.

We have three different development environments:

This is our main development environment, where you can test new components or new implementations to existing components. It's a hermetic self-cleaning environment that is not tracked by git.

This environment uses components from the Expose/ folder.

To run the sandbox, in the root folder, run:

$ yarn start

If this is the first time you're running this command it will create a sandbox folder inside ink with a Sandbox.tsx file where you can import your component and make changes to it without the fear of it ending up on the ink repo.

If you're making changes to existing components or adding new tests you can also use the Expose. This is the environment we use for our tests, so if you want to run Backstop or Cypress testing locally, you'll need to be running the Expose.

To run the expose, in the root folder, run:

$ yarn start:expose

ink's documentation runs on a separate folder inside the ink main folder.

The ink documentation uses Gatsby, so you'll need to make sure Gatsby is installed on your machine before you can run them locally. To run the docs, run the following commands in the root folder:

Create your branch off of master. Master is our main branch and it's the most up to date branch on ink.

Most of the times this branch has newer code than the last release. To better understand how ink releases work, go to ink releases.

To name your branch you have two options:

DTR-XXXX/simple-explanation-of-the-task

ta/simple-explanation-of-the-pr

To learn more about the code styles in ink and how to organize your folders, please read the Code Style.

In ink we prefer smaller and frequent commits. Separation of concerns when commiting helps maintain some cohesion if we ever need to revert/cherry-pick the commit in the future.

To learn more about how we build tests in ink, please read Testing.

When adding any code to ink, everyone, including the ink team, needs to open a PR to be reviewed by the team before merging.

Before opening a PR, consider opening it in Draft and reviewing it yourself before making it open to general review. Often times some big PRs can benefit from having someone review it along the development.

Pre-reviewing it yourself can also help you to find errors early and gives you an opportunity to add comments to help others better understand your PR.

To open a PR in ink there are some practices that need to be followed:

PRs names should follow the structure:

[ComponentsName] Concise description of what was made in the PR

If the content of your PR is not a component-specific change, try to use what closest describes what you did on the PR. Some examples can be: Docs, Typescript, Release, Testing or any other non-component specific subject on ink. If your PR makes changes to multiple components that can not be described with a single tag like Table, Forms or a non-component specific subject, separate the concerns into multiple PRs.

We separate our PRs using the first name in brackets ([]) in the PR name and transform this name into a category with the PR description nested under it. PRs that work on the same component will be put under the same name. Good, meaningful descriptions are expected since these will eventually become part of the release changelog.

One of the tests CI runs on your PR is to see if it has the correct labels. The ones needed are the cc labels and release labels if your change/addition affects versioning.

Find the one (or more) label that most closely describe what you're doing on your PR.

The available labels are:

cc-product-development: Build new or iterate on an internal or external offering of functionality.

cc-bug: Fixing any product in any development branch & code behaviour is different than originally expected

cc-documentation: Adding documentation to a repository.

cc-hotfix: Like a bug, but highest priority - this is deeply impacting customers.

cc-tech debt: Paying out technical debt. Examples: refactoring features for better extensibility.

cc-config changes: Configuration change on an existing feature or resource. Examples: granting new permissions

We use semantic versioning to define how each change affects the versioning.

Whenever we have what could be considered a minor or major change we need to add the proper labels to the PR so when the CI create the release, it can properly update the version.

For minor changes, the PR needs to have the Needs Minor Release label. These minor changes consist of changes that are big changes that are still compatible with older versions of ink.

For major changes, the PR needs to have the Needs Major Release label. This label indicates the PR have some changes that could potentially break other repos in a bad or big way (not retroactively compatible). Some examples could be: deleting full components, deleting important props, updating typescript/packages versions, etc;

If you have any difficulties understanding what version your PR needs, ask the ink team.

If you're introducing breaking changes please follow up with the ink team so you can help with any codemods, migration guides or deprecation warnings needed.

In ink we also use the PRs as documentation of changes being made, that's why the PR description should be as complete as possible, explaining the problem, decisions made and why and if applicable a step-by-step of what was done in the PR.

If your PR name is not enough to explain the contents of the PR or there are breaking changes, consider adding a better explanation into the Changelog notes section of the description. These notes are also added to the changelog.

All PRs in ink will pass through a series of required tests when opened:

When you have your PR open you can post it on the ink channel or send it to specific people on the ink team to review.

Your code needs to have at least two approving reviews, and you'll always need at least one approve from a member of the Design Technology team in Carta. Ideally, both approves should come from people in the ink team.

If your PR is more engineering-focused, ask at least one ink engineer to review it. On the other hand, if your PR is more css/visually focused make sure to ask for an ink DT to review it.

To better understand how to get reviews from the ink team you can read this document

In ink we have automated visual regression that uses BackstopJS.

If your branch is not passing the Backstop test you'll need to update it. Passing backstop tests is mandatory to merging in ink.

To approve backstop tests follow these steps:

$ yarn backstop approve <failing_backstop_url>

If you want to learn how to run Backstop tests locally or how to write tests for Backstop, you can read our visual regression testing session.