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
Follow the steps below to setup your local development environment:
-
Clone repository
git clone https://github.com/flex-development/docast cd docast
-
Install binaries with Homebrew
brew bundle --file ./Brewfile
-
Set node version
nvm use
-
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>
-
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 anyYARN_*
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 # NVM # - https://github.com/nvm-sh/nvm export NVM_DIR=$HOME/.nvm # --------------------------------------------------------------------------- # LOAD ENVIRONMENT VARIABLES IN CURRENT WORKING DIRECTORY # 1. $GITHUB_WORKSPACE [ -d $PWD/.git ] && export GITHUB_WORKSPACE=$(git rev-parse --show-toplevel)
-
Load
dotenv
plugin via$ZDOTDIR/.zshrc
:plugins=(dotenv)
-
Reload shell
exec $SHELL
name |
---|
NODE_NO_WARNINGS |
ZSH_DOTENV_FILE |
Variables are prefixed by secrets.
in workflow files.
The examples in this guide contain references to custom Git aliases.
See .github/.gitconfig
for an exhaustive list.
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
This project follows a Trunk Based Development workflow, specifically the short-lived branch style.
- Trunk Branch:
main
- Short-Lived Branches:
feat/*
,hotfix/*
,release/*
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
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 dependenciesci
: Changes to our CI/CD configuration files and scriptschore
: Housekeeping tasks / changes that don't impact external usersdocs
: Documentation improvementsfeat
: New featuresfix
: Bug fixesperf
: Performance improvementsrefactor
: Code improvementsrevert
: Revert past changesstyle
: Changes that do not affect the meaning of the codetest
: Change that impact the test suitewip
: 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.
Prettier is used to format code and ESLint to lint files.
Source code is located in src
directory.
- 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.
If you need help, make note of any issues in their respective files. Afterwards, start a discussion in the Q&A category.
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/labels.yml
.
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 😉
When you're ready to submit your changes, open a pull request (PR) against
main
:
https://github.com/flex-development/docast/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:
To keep in line with commit message standards after PRs are merged, PR titles are expected to adhere to the same rules.
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
Note: Package and release publication is executed via GitHub workflow.
This is so invalid or malicious versions cannot be published without merging those changes intomain
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>
yarn conventional-changelog -i CHANGELOG.md -s
yarn release
- Open PR from
release/*
intomain
- PR title should match
release: <release-tag>
- e.g:
release: 1.1.0
- e.g:
- link all issues being released
- after review,
squash and merge
PRrelease: <release-tag> (#pull-request-n)
- e.g:
release: 1.1.0 (#3)
- e.g:
- 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
- if successful, the workflow will:
- if successful, the workflow will:
- PR title should match