A package to add Conventional Commits and Semantic Releases to your project
Explore the docs »
Report Bug
·
Request Feature
This package provides a series of Git tools for running repositories the "Batch way", following the conventional commits specification. We've bundled commitizen, commitlint and semantic-release to automatically format and lint commit messages and tag and generate changelogs based on your commit messages for each release.
Our workflow goes something like this:
- A new branch is created from master
- Changes are committed using Commitizen and linted with Commitlint
- A pull request is raised targeting the master branch
- Once merged, a GitLab pipeline will run analysing the new commits and generating a changelog, release notes and semver tag
The idea behind this project was to create a simple installable dev tool that enforces consistest, high quality commit messages with auto-generated changelogs/release notes and to remove human emotion from the versioning.
To add this tool to your project simply follow these steps:
You'll need a package.json file to add the git-tools package.
You will also need to have a minimum of git 2.9
If you don't have one simply run:
npm init- Add the package as a dev dependency
npm i @batch/git-tools -D- That's it!
On installation an install script will run that does the following:
- Adds configurations to your package.json file
- Adds a GitLab CI pipeline file for running semantic-commit
The pipeline file will not overwrite an existing file and the configuration is added using a deep merge and will not overwrite existing config.
This package can be used in multiple ways depending on your workflow and team's preferences. We've bundled commitizen for CLI git usage and husky for GUI (e.g. Tower/SourceTree) usage.
When it's time to commit a change either run git cz if you have commitizen installed globally or npm run commit for local usage. Both methods will run Commitizen and pick up on the standard Commitlint configuration bundled in the package.
You can use your GUI of choice and Husky will kick in at the pre-commit hook stage to run commitlint and validate your commit messages.
Note: MacOS users will need to follow this step to get the pre-commit hook to work with Tower/SourceTree (and probably other GUI's).
The default GitLab pipeline that's copied into your project is setup to generate a new release, changelog and tag when new changes are pushed to the master branch.
You'll need to add a GITLAB_TOKEN secret to your repo's CI/CD variables with a personal access token that has access to the api scope.
This package is fully configurable and can be extended in the following ways:
npx husky install
Note: It will create the .husky directory at the current directory you are when running this.
You will use the basis command every time you want to add a new hook to Husky, like: npx husky add .husky/ ""
Add the commit hook;
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'
You can alter the Commitizen config used by altering the config.commitzen.path object in your package.json. See the Commitizen documentation for more information.
You can change the Semantic Release config by updating the release.extends property in your package.json. By default it points to Batch's own config but you can change this to use your own.
"release": {
"extends": "my-custom-config-package"
}
Note: config['@batch/git-tools'].installed must be true otherwise it will overwrite any custom package.json config in CI environments
See the open issues for a list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.
Josh Smith - @batchnz - [email protected]
Project Link: https://github.com/batchnz/git-tools
Thanks to all the hard work by the teams behind the tools used in this project.