Overview

First of all, thank you for your interest in contributing to Abyss. All of your contributions are valuable to the project! There are several ways you can get involved in the Abyss community and become a contributor:

• Share Abyss: Share the link to Abyss with members of your product team, and we'd be happy to discuss how we can help support your application.
• Improve documentation: Help us improve the Abyss Docs by fixing incomplete or missing sections, examples, and explanations.
• Provide feedback: The team at Abyss are constantly working to make the project better, please let us know what features you would like to see with the Contact Us form.

Abyss code repo

Setting up project locally

For the essential system tools to get Abyss running on your local development environment, visit our workplace setup guide.

To set up, clone the Abyss repository to a directory of your choice:

git clone https://github.com/uhc-tech/abyss.git

Afterwards, install the dependencies for abyss on your machine:

# Go into the abyss directory
cd abyss

# Install abyss dependencies
pnpm i

Then you are ready to start abyss-docs on your machine:

pnpm run docs

Commit conventions

With several contributors working on Abyss, it's important to write your commit messages to be as descriptive as possible. Abyss follows the conventional commit format to keep commits organized and searchable.

<type>(<scope>): <description> [<story ID>]

Examples:

docs(web): Edit Button accessibility section [US123456789]
refactor(web): Extract loading overlay logic
feat(mobile): Add new Carousel feature [US987654321]
fix(docs): Fix docs deployment script [DE1234567]

Git branch names

Naming the branch you're working on helps repository maintainers understand the changes being made when the PR is opened. Using consistent branch name prefixes also allows build tools to automatically categorize the branches using labels. Branch names should be all lowercase (with the exception of US and DE) and include hyphens between words. All branches are divided into four groups:

• story/ - Changes associated with a User Story, use the unique 7-digit number from Rally followed by a task description.

• defect/ - Changes associated with a Defect, use the unique 7-digit number from Rally followed by a task description.

• refactor/ - Changes to the repo that aren't documented in Rally are considered refactors, so use the task portion to add detail to your branch name.

• release/ - Used specifically by build tools, this branch name is exclusive to release notes and documentation leading up to a new release.

Examples:

$ git checkout -b story/US2434515-developer-toolkit
$ git checkout -b defect/DE308703-button-accessibility
$ git checkout -b refactor/select-input-multi-docs
$ git checkout -b story/US1533842-use-loading-overlay

Branch Name Rules:

• Branch prefix must start with story/, defect/, refactor/, or release/
• Branch name may consist only of lowercase letters, numbers, and hyphens
  • The user story or defect ID (US### or DE###) must be included in the branch name and is an exception to this rule

Secure groups

Visit Secure to request permissions for the following group:

• abyss_contributors: For write access to Abyss GitHub repositories

Developer tools

Abyss is built using a list of trusted resources. Below are links to what makes up the framework of Abyss.

If you're ready to get started with Abyss on your own, check out the Abyss StarterKit (coming soon) to get started.

Design tools

Abyss has a dedicated team of designers creating a Design Kit on Figma. Below are some resources to help developers navigate these tools:

If you're a designer and want to dive deeper into the Abyss Design Kit, visit our Designer Getting Started (coming soon) page to learn more.