Skip to content

Latest commit

 

History

History
123 lines (71 loc) · 7.15 KB

CONTRIBUTING.md

File metadata and controls

123 lines (71 loc) · 7.15 KB
Raw

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 don't use separate branches for development or for upcoming releases. We do our best to keep main in good shape, with all tests passing.

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 almost fully automated with semantic-release, only requiring a core team member to trigger this workflow manually whenever a new release needs to be published.

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.

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.