Skip to content

Latest commit

 

History

History
399 lines (284 loc) · 11.6 KB

CONTRIBUTING.md

File metadata and controls

399 lines (284 loc) · 11.6 KB
Raw

Contributing Guide

This document aims to describe the workflows and rules used for developing this project.

This includes, but is not limited to:

  • how to contribute code (coding standards, testing, documenting source code)
  • how pull requests are handled
  • how to file bug reports

Getting Started

Follow the steps below to setup your local development environment:

  1. Clone repository

    git clone https://github.com/flex-development/vfile-lexer
cd vfile-lexer

  2. Install binaries with Homebrew

    brew bundle --file ./Brewfile

  3. Set node version

    nvm use

  4. Configure commit signing

  5. Update ~/.gitconfig

    git config --global commit.gpgsign true
git config --global tag.gpgsign true
git config --global user.email <email>
git config --global user.name <name>
git config --global user.username <username>

    See .gitconfig for a global Git config example.

  6. Install dependencies

    yarn

    Note: This project uses Yarn 2. Consult .yarnrc.yml for an overview of configuration options and required environment variables. Furthermore, if you already have a global Yarn configuration, or any YARN_* environment variables set, an error will be thrown if any settings conflict with the project's Yarn configuration, or the Yarn 2 API. Missing environment variables will also yield an error.

  7. ZSH setup

  8. Update $ZDOTDIR/.zprofile:

    # PATH
# 1. local node_modules
[ -d $PWD/node_modules/.bin ] && export PATH=$PWD/node_modules/.bin:$PATH

# DOTENV ZSH PLUGIN
# https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/dotenv
export ZSH_DOTENV_FILE=.env.zsh

# GIT
# https://gist.github.com/troyfontaine/18c9146295168ee9ca2b30c00bd1b41e
export GIT_EMAIL=$(git config user.email)
export GIT_NAME=$(git config user.name)
export GIT_USERNAME=$(git config user.username)
export GPG_TTY=$(tty)

# HOMEBREW
# https://brew.sh
export HOMEBREW_PREFIX=$(brew --prefix)

# NVM
# https://github.com/nvm-sh/nvm
export NVM_DIR=$HOME/.nvm

# YARN
export YARN_RC_FILENAME=.yarnrc.yml

  9. Load dotenv plugin via $ZDOTDIR/.zshrc:

    plugins=(dotenv)

  10. Reload shell

    exec $SHELL

Environment Variables

name
CODECOV_TOKEN
GITHUB_TOKEN
HOMEBREW_BREWFILE
NODE_NO_WARNINGS
ZSH_DOTENV_FILE

GitHub Actions

Variables are prefixed by secrets. in workflow files.

Git Config

The examples in this guide contain references to custom Git aliases.

See .github/.gitconfig for an exhaustive list.

Contributing Code

Husky is used to locally enforce coding and commit message standards, as well as run tests pre-push.

Any code merged into the trunk must confront the following criteria:

  • changes should be discussed prior to implementation
  • changes have been tested properly
  • changes should include documentation updates if applicable
  • changes have an associated ticket and pull request

Branching Model

This project follows a Trunk Based Development workflow, specifically the short-lived branch style.

  • Trunk Branch: main
  • Short-Lived Branches: feat/*, hotfix/*, release/*

Branch Naming Conventions

When creating a new branch, the name should match the following format:

[prefix]/<issue-number>-<branch_name>
 │        │              │
 │        │              │
 │        │              │
 │        │              └─⫸ a short, memorable name
 │        │
 │        └─⫸ check github issue
 │
 └─⫸ feat|feat/fix|hotfix|release

Commit Messages

This project follows Conventional Commit standards and uses commitlint to enforce those standards.

This means every commit must conform to the following format:

<type>[scope][!]: <description>
 │     │      │    │
 │     │      │    │
 │     │      │    └─⫸ summary in present tense (lowercase without punctuation)
 │     │      │
 │     │      └─⫸ optional breaking change flag
 │     │
 │     └─⫸ see .commitlintrc.ts
 │
 └─⫸ build|ci|chore|docs|feat|fix|perf|refactor|revert|style|test|wip

[body]

[BREAKING-CHANGE: <change>]

[footer(s)]

<type> must be one of the following values:

  • build: Changes that affect the build system or external dependencies
  • ci: Changes to our CI/CD configuration files and scripts
  • chore: Housekeeping tasks / changes that don't impact external users
  • docs: Documentation improvements
  • feat: New features
  • fix: Bug fixes
  • perf: Performance improvements
  • refactor: Code improvements
  • revert: Revert past changes
  • style: Changes that do not affect the meaning of the code
  • test: Change that impact the test suite
  • wip: Working on changes, but you need to go to bed 😉

e.g:

  • build(deps-dev): bump cspell from 6.7.0 to 6.8.0
  • perf: lighten initial load

See .commitlintrc.ts to view all commit guidelines.

Code Style

dprint is used to format code and ESLint to lint files.

Making Changes

Source code is located in src directory.

Documentation

Before making a pull request, be sure your code is well documented, as it will be part of your code review.

Testing

This project uses Vitest to run tests.

Husky is configured to run tests against changed files.

Be sure to use it.skip or it.todo where appropriate.

Running Tests

  • yarn test
  • yarn test:cov
  • yarn typecheck

Code Coverage

Code coverage is reported using Codecov.

To manually upload coverage reports:

  1. Retrieve CODECOV_TOKEN from a maintainer

  2. Add CODECOV_TOKEN to .env.repo

  3. Reload shell

    exec $SHELL

  4. Install Codecov Uploader

  5. Run yarn codecov

Getting Help

If you need help, make note of any issues in their respective files in the form of a JSDoc comment. If you need help with a test, don't forget to use it.skip and/or it.todo. Afterwards, start a discussion in the Q&A category.

Labels

This project uses a well-defined list of labels to organize issues and pull requests. Most labels are scoped (i.e: status:).

A list of labels can be found in .github/infrastructure.yml.

Opening Issues

Before opening an issue, make sure you have:

  • read the documentation
  • checked that the issue hasn't already been filed by searching open issues
  • searched closed issues for solution(s) or feedback

If you haven't found a related open issue, or feel that a closed issue should be re-visited, open a new issue.

A well-written issue

  • contains a well-written summary of the bug, feature, or improvement
  • contains a minimal, reproducible example (if applicable)
  • includes links to related articles and documentation (if any)
  • includes an emoji in the title 😉

Pull Requests

When you're ready to submit your changes, open a pull request (PR) against main:

https://github.com/flex-development/vfile-lexer/compare/main...$branch

where $branch is the name of the branch you'd like to merge into main.

All PRs are subject to review before being merged into main.

Before submitting a PR, be sure you have:

  • performed a self-review of your changes
  • added and/or updated relevant tests
  • added and/or updated relevant documentation

Every PR you open should:

Pull Request Titles

To keep in line with commit message standards after PRs are merged, PR titles are expected to adhere to the same rules.

Merge Strategies

In every repository, the rebase and merge and squash and merge options are enabled.

  • rebase and merge: PR has one commit or commits that are not grouped
  • squash and merge: PR has one commit or a group of commits

When squashing, be sure to follow commit message standards:

<type>[scope][!]:<pull-request-title> (#pull-request-n)
 │     │      │   │                    │
 │     │      │   │                    │
 │     │      │   │                    └─⫸ check pull request
 │     │      │   │
 │     │      │   └─⫸ lowercase title
 │     │      │
 │     │      └─⫸ optional breaking change flag
 │     │
 │     └─⫸ see .commitlintrc.ts
 │
 └─⫸ build|ci|chore|docs|feat|fix|perf|refactor|release|revert|style|test

e.g:

  • ci(workflows): simplify release workflow #24
  • refactor: project architecture #21
  • release: 1.0.0 #13

Deployment

Note: Package and release publication is executed via GitHub workflow.
This is so invalid or malicious versions cannot be published without merging those changes into main first.

  1. Get a version bump recommendation
    • grease bump --recommend
  2. Create release chore commit
    • yarn release <new-version>
    • yarn release major
    • yarn release minor
    • yarn release patch
    • yarn release premajor --preid <dist-tag>
    • yarn release preminor --preid <dist-tag>
    • yarn release prepatch --preid <dist-tag>
    • yarn release prerelease --preid <dist-tag>
  3. Push release chore commit
  4. Monitor workflows
    1. release-chore
      • create release branch
      • bump manifest version
      • add changelog entry for new release
      • create release pr
    2. release
      • create and push new tag
      • create and publish github release
      • ensure all relevant issues are closed
    3. publish