Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
155 lines (90 loc) · 9.04 KB

CONTRIBUTING.md

File metadata and controls

155 lines (90 loc) · 9.04 KB

Contributing to Typist

The following is a set of guidelines for contributing to Typist. Please spend several minutes reading these guidelines before you create an issue, pull request or discussion.

Code of Conduct

Doist has adopted the Contributor Covenant as its Code of Conduct, and we expect contributors to Typist to adhere to it. Please read the full text so that you can understand what actions will and will not be tolerated.

Open Development

All work on Typist happens directly on GitHub. Both core team members and external contributors send pull requests that go through the same review process.

Semantic Versioning

Typist follows semantic versioning. We release patch versions for critical bugfixes, minor versions for new features or non-essential changes, and major versions for any breaking changes.

Every significant change is documented in the CHANGELOG.md file.

Branch Organization

Submit all changes directly to the main branch. We do our best to keep main in good shape, with all tests passing.

For pre-release testing, the next branch is used to publish pre-release versions to npm before promoting to stable. See Release Process for details.

Proposing a Change

If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend opening a GitHub Discussion with the core team first. Although we welcome all contributions, this lets us reach an agreement on your proposal before you put significant effort into something that might not fit Doist product requirements.

Your First Pull Request

Working on your first Pull Request? You can learn how from this free video series:

If you decide to fix an issue, please be sure to check the comment thread in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you intend to work on it so other people don't accidentally duplicate your effort.

Project Setup

Before you can contribute to the codebase, you will need to fork the Typist repository, and the following steps will help you hit the ground running:

  1. Fork the repository (click the Fork button at the top right of this page);

  2. Clone your fork locally;

git clone https://github.com/<your_github_username>/typist.git
cd typist

  1. Install all dependencies by running npm install;

    Note

    If you're not using npm 7+, install peer dependencies with npx npm-install-peers.

Development Workflow

After cloning Typist and installing all dependencies, several commands are at your disposal:

  • npm run build: Builds the @doist/typist package for publishing to npm and GitHub Packages;
  • npm run check: Validates code quality with ESLint, styling with Prettier, and types with TypeScript;
  • npm run clean: Removes temporary directories used for multiple caches;
  • npm run storybook:build: Builds Storybook as a static Web application;
  • npm run storybook:start: Starts Storybook Web application (available at http://localhost:6006/);
  • npm run test: Runs all unit test with Jest and end-to-end tests with Storybook.

Release Process (core team only)

The release process for Typist is fully automated with semantic-release. Pushing to main (after CI passes) triggers a stable release automatically.

Pre-releases

To test features before publishing a stable release:

  1. Sync next with main before starting new work, and after each stable release (required for semantic-release to correctly initiate the next pre-release versioning cycle):

    git checkout next
git merge main -m "chore: sync next with main [skip ci]"
git push origin next

  2. Develop on a feature branch based off next and open a PR targeting next.

  3. Automatic pre-release: Each PR merge into next triggers CI → a pre-release version (e.g., 9.1.0-next.1) is published to the @next dist-tag on npm and GitHub Packages.

  4. Promote to stable: When ready, open a PR to merge next into main. The PR title must follow Conventional Commits (e.g., feat: ..., fix: ...) as it determines the version bump for the stable release.

Note: The CHANGELOG.md is only updated for stable releases on main. Pre-releases still get GitHub release notes and npm publication.

Visual Studio Code

CSS Modules for Storybook

Typist Storybook makes use of typescript-plugin-css-modules, a TypeScript language service plugin for CSS Modules, which provides type information to IDEs and any other tools that work with TypeScript language service plugins.

To use this plugin with Visual Studio Code, you should set your workspace's version of TypeScript, which will load plugins from your tsconfig.json file. For instructions, please see: Using the workspace version of TypeScript.

Sending a Pull Request

Pull requests are actively monitored, and only need the approval of one or more core team members. We will review your pull request and either merge it, request changes to it, or close it with an explanation.

Before submitting a pull request, please take the following into consideration:

  • Fork the repository and create your branch from main;
  • Follow the Commit Message Guidelines below;
  • Add tests for code that should be tested (like bug fixes);
  • Ensure the test suite passes with flying colours;
  • Do not override built-in validation and formatting checks.

Commit Message Guidelines

Atomic Commits

If possible, make atomic commits, which means:

  • A commit should not mix whitespace and/or code style changes with functional code changes;
  • A commit should contain exactly one self-contained functional change;
  • A commit should not create an inconsistent state (e.g., test errors, linting errors, partial fix, etc.).

Commit Message Format

This repository expects all commit messages to follow the Conventional Commits Specification to automate semantic versioning and CHANGELOG.md generation.

As a quick summary, each commit message consists of a header, an optional body, and an optional footer. The header has a special format that includes a type, an optional scope, and a description:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit types, such as feat: or fix:, are the only ones that will affect versioning and CHANGELOG.md generation, whereas commit types such as build:, chore:, ci:, docs:, perf:, refactor:, revert:, style: and test: will not. They are still valid, and it would be great if you could use them when appropriate.

A commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A breaking change can be part of commits of any type.

How Commits Map to the CHANGELOG

The commit header (subject line) and footer metadata — including BREAKING CHANGE: notes and issue references (e.g., Closes #123) — are used to generate the CHANGELOG.md. The commit body is ignored by the changelog generator.

When squash-merging a PR, GitHub lets you edit the commit message and extended description. Keep the following in mind:

  • The commit message (header) becomes the entry under its type section (e.g., Features, Bug Fixes).
  • A BREAKING CHANGE: footer in the extended description becomes a separate entry in the Breaking Changes section. Use it to describe the impact for consumers.
  • Using ! in the header without a BREAKING CHANGE: footer will duplicate the subject line in both the type section and the Breaking Changes section. To avoid this, always include a BREAKING CHANGE: footer with a distinct description when introducing breaking changes.

License

By contributing to Typist, you agree that your contributions will be licensed under its MIT license.

Attribution

This document is based on reactjs.org contributing guidelines.