Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
110 lines (63 loc) · 6.18 KB

CONTRIBUTING.md

File metadata and controls

110 lines (63 loc) · 6.18 KB

Contributing to interaction-trace

The following is a set of guidelines for contributing to interaction-trace. 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 interaction-trace 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 interaction-trace happens directly on GitHub. Both core team members and external contributors send pull requests that go through the same review process.

Semantic Versioning

interaction-trace 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 interaction-trace 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>/interaction-trace.git
cd interaction-trace
  1. Install all dependencies by running npm install;

Development Workflow

After cloning interaction-trace and installing all dependencies, several commands are at your disposal:

  • npm run build: Builds the @doist/interaction-trace package for publishing to npm;
  • npm run check: Validates code quality and types with Biome and TypeScript;
  • npm run fix: Automatically fixes linting issues with Biome;
  • npm run test: Runs all unit tests with Vitest;
  • npm run test:watch: Runs tests in watch mode.

Release Process (core team only)

The release process for interaction-trace is automated with release-please. When commits following the Conventional Commits specification are merged to main, release-please automatically creates or updates a release PR. When that PR is merged, a new version is published to npm.

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 interaction-trace, you agree that your contributions will be licensed under its MIT license.

Attribution

This document is based on reactjs.org contributing guidelines.