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:

Clone repository

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

Install binaries with Homebrew
```
brew bundle --file ./Brewfile
```
Set node version
```
nvm use
```
Configure commit signing

Update ~/.gitconfig

git config --global commit.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.

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.
ZSH setup

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

Load dotenv plugin via $ZDOTDIR/.zshrc:
```
plugins=(dotenv)
```
Reload shell
```
exec $SHELL
```

Environment Variables

name
`CODECOV_TOKEN`
`GITHUB_TOKEN`
`HOMEBREW_BREWFILE`
`NODE_NO_WARNINGS`
`PAT_BOT`
`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.json
 │
 └─⫸ 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.json to view all commit guidelines.

Code Style

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

.dprint.jsonc
.eslintignore
.eslintrc.base.cjs
.eslintrc.cjs

Making Changes

Source code is located in src directory.

Documentation

JavaScript & TypeScript: JSDoc; linted with eslint-plugin-jsdoc

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

Code Coverage

Code coverage is reported using Codecov.

To manually upload coverage reports:

Retrieve CODECOV_TOKEN from a maintainer
Add CODECOV_TOKEN to .env.repo
Reload shell
```
exec $SHELL
```
Install Codecov Uploader
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/tutils/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:

follow this template
be titled appropriately

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.json
 │
 └─⫸ 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.

Before deploying, the following steps must be completed:

Schedule a code freeze
Decide what type of version bump the package needs
- yarn recommended-bump
Bump version
- bump <new-version>
- bump major
- bump minor
- bump patch
- bump premajor --preid <dist-tag>
- bump preminor --preid <dist-tag>
- bump prepatch --preid <dist-tag>
- bump prerelease --preid <dist-tag>
Update CHANGELOG.md
- yarn changelog -sw (remove w to do a dry-run, i.e. yarn changelog -s)
yarn release
Open PR from release/* into main
- PR title should match release: <release-tag>
  - e.g: release: 1.1.0
- link all issues being released
- after review, squash and merge PR
  - release: <release-tag> (#pull-request-n)
    - e.g: release: 1.1.0 (#3)
- on PR merge, release workflow will fire
  - if successful, the workflow will:
    - pack project
    - create and push new tag
    - create and publish github release
    - make sure all prereleased or released issues are closed
    - delete the release branch
  - on release publish, publish workflow will fire
    - if successful, the workflow will:
      - publish package to github package registry
      - publish package to npm

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CONTRIBUTING.md

CONTRIBUTING.md

Contributing Guide

Getting Started

Environment Variables

GitHub Actions

Git Config

Contributing Code

Branching Model

Branch Naming Conventions

Commit Messages

Code Style

Making Changes

Documentation

Testing

Running Tests

Code Coverage

Getting Help

Labels

Opening Issues

Pull Requests

Pull Request Titles

Merge Strategies

Deployment

Files

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing Guide

Getting Started

Environment Variables

GitHub Actions

Git Config

Contributing Code

Branching Model

Branch Naming Conventions

Commit Messages

Code Style

Making Changes

Documentation

Testing

Running Tests

Code Coverage

Getting Help

Labels

Opening Issues

Pull Requests

Pull Request Titles

Merge Strategies

Deployment