Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
240 lines (149 loc) · 11.3 KB

CONTRIBUTING.md

File metadata and controls

240 lines (149 loc) · 11.3 KB

Contributing to LaunchPad UI

First off, thanks for taking the time to read our contribution docs!

The following is a set of guidelines for contributing to LaunchPad and its packages, which are hosted in the LaunchDarkly Organization on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Table Of Contents

How Can I Contribute?

The LaunchPad maintainers monitor the issue tracker in the repository. Bug reports and feature requests should be filed in this issue tracker. The maintainers will respond to all newly filed issues within two business days.

Reporting Bugs

When reporting a bug, help maintainers and the community understand your report 📝, reproduce the behavior 💻 💻, and find related reports 🔎.

  • Determine which package the issue should be reported in.
  • Perform a cursory search in our bug issues to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one.
  • File a bug issue and describe in detail how to reproduce the issue. Screenshots or video are always a big help!

Suggesting Enhancements

We're always open to enhancement suggestions! When assessing an enhancement, we must consider how it will affect other teams, how it will function with other UI/UX patterns in LaunchPad, and more.

  • Perform a cursory search in our enhancement issues to see if the feature has already been suggested. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one.
  • File a feature request and describe in detail what you're suggesting.

Contributing Code

If you'd like to help by writing code and filing a pull request for a feature enhancement or bugfix, we welcome all contributions, but here are a few things to note:

  • For new features: reach out to someone on the team to discuss the design system contribution process.
  • For feature enhancements: if it's a small tweak, feel free to submit a PR for the team to review.
  • For bugfixes: we welcome all bugfix PR submissions.

To learn how to contribute code in LaunchPad, follow the guide below.

Code Contribution Guide

If you're contributing code to LaunchPad, follow this guide to make sure that once you publish your pull request, the team has everything we need to review your code.

Step 1: Create a feature branch off main

We follow a branch naming convention inspired by Conventional Commits, which looks like so:

{your name}/{tag}/{description of change}

So if I'm publishing a fix to some CSS issues, it might look like this:

tealydan/fix/update-alert-max-width

Step 2: Write and test your code

See our common tasks section below for advice on how to accomplish common tasks.

For testing, you can visit the tests section to learn which test commands we have available. We have a minimum coverage score you must fulfill for unit tests, so make sure to write a few tests to cover base cases and any heavily-used interactions.

You should also consider adding axe accessibility tests. See other packages for examples.

Step 3: Generate a changelog for your code

We use a tool called changesets to manage versioning and changelogs within LaunchPad. Every package change should include a changelog with a description of the changes. When new changelog files are detected in LaunchPad's .changeset folder, a Github action will publish or update a pull request that, when merged, will publish those changes along with the changelog to new NPM module versions for the modified packages.

To generate a changelog:

  • Run npx changeset
  • You'll see a list of packages changesets has determined have changed
    • Select the packages you've updated.
  • changesets will now ask what type of version change should occur:
    • A brand new package should receive a "minor" bump, which should set it at 0.1.0.
    • For other version bumps, refer to the semantic versioning docs.
  • changesets will create a new .md file in the .changeset directory. Find it, and update the description to be more human readable.

Here's an example of an acceptable file in the .changeset folder:

---
'@launchpad-ui/components': patch
'@launchpad-ui/tokens': patch
---

Add `Toast` to display brief, temporary notifications of actions, errors, or other events

Step 4: Commit your code

We follow the Conventional Commits approach to commit messages, branch naming, and pull request titles. Not only does this make it easier for us developers to grok, search, and organize code changes, it also lets us do some fun automation.

  • Use the present tense ("Add feature" not "Added feature")
  • Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit the first line to 72 characters or less
  • Start the commit message with a conventional commit tag, such as:
    • fix
    • feat
    • build
    • chore
  • Add a scope where relevant.

Here's an example of an acceptable commit message:

feat(components): Add `Toast` component

Step 5: Publish a pull request

When you're ready, you can push your feature branch to our remote repository.

There are just a few things to keep in mind:

  • When titling a pull request, always use conventional commits in the same convention as in Step 4. The title is used as the commit description when a PR is squashed and merged.
  • You should use our pull request template and fill it out as much as possible.
  • If there are visual diffs or a11y issues between your branch and main, Chromatic will generate a list of changes that must be approved before the PR should be merged. This can be found in the Github actions list.
  • The team will be automatically assigned to take a look.

Note: if you are creating a pull request from a fork, CI checks will only run when it is ready for review. To run Chromatic, you will need to make a build locally in the terminal using the project token found in Chromatic:

$ pnpm chromatic --project-token PROJECT_TOKEN --branch-name FORKED_BRANCH --build-script-name storybook:build --exit-once-uploaded --only-changed --externals "packages/icons/src/img/**" --externals "packages/tokens/tokens/**"

Step 6: Test and verify your changes

If you updated the components, icons, or tokens package your PR will be decorated with preview releases (example) which will allow you to install them to your project to test/verify. This is helpful for bug fixes or ensuring no regressions result from a refactoring and/or style changes.

Common Tasks

Local setup

pnpm is the package manager used in this monorepo.

After installing the package manager, run the following command to install the project's dependencies:

$ pnpm install

Storybook

Storybook is used for local development of components.

Run this command to start a local instance in your browser:

$ pnpm storybook

Figma Code Connect

Figma Code Connect is a tool to connect LaunchPad code with LaunchPad Figma Design System real-time. When developers will click component or its insance in design, they will be directed which component and code they should use for implementing the design.

Using Figma connect requires generating an access Token in LaunchDarkly Figma. You can learn more about code connect here.

Test Code Connect Build locally:

npx figma connect publish --dry-run

Publish all changes to Figma Dev Mode:

npx figma connect publish

Running Tests

Unit Tests

Vitest and React Testing Library are used to unit test the code.

The following command will run unit tests in every package of the monorepo:

$ pnpm test

Adding Dependencies to Packages

  • Pin dependencies.
  • Match dependency versions across packages when possible so that we can share dependency versions and reduce bundle sizes.
  • If a package depends on another LaunchPad package, use the workspace syntax to use latest compatible versions:
    • Ex: "@launchpad-ui/tokens": "workspace:~"

Adding Icons to LaunchPad

Do not add icons manually to launchpad-ui. Icons are managed in Figma and synced to the @launchpad-ui/icons package via a script.

First, add your icon to the Figma library

  1. Create a branch in the LaunchPad Figma library and add your icon to the Icons page.
  2. Make sure your new icon is reviewed by Design. You can always ping the @uxteam in #ask-launchpad-design-system if you need help making your icon or to get a review.
  3. Merge the icon to the LaunchPad Figma library

Then, sync @launchpad-ui/icons package with Figma

  1. Trigger the sync-icons workflow by going to the actions tab and clicking "Run workflow". This action will generate a PR with your new icon.
  2. Open your PR. Make sure your icons look correct by opening the Chromatic build preview for your PR. Reviewers will be auto assigned.

Styleguides

Monorepo

We use a monorepo structure to organize our code to be published to NPM.

Versioning

We are using major version zero (0.y.z) semantic versioning to indicate that the project is still in an "initial development" phase and anything may change at any time. When a new package is introduced, the initial version is set to 0.1.0.

Javascript Styleguide

All Javascript code is linted with Biome.

CSS Styleguide

All CSS code is linted with Biome.

Specs Styleguide

  • Include thoughtfully-worded, well-structured Vitest specs in the __tests__ folder of each package.
  • Treat describe as a noun or situation.
  • Treat it as a statement about state or how an operation changes state.