Contributing Guide #
Getting started #
The Architecture Guide contains a high-level overview of chezmoi’s source code.
Developing locally #
chezmoi requires Go 1.17 or later.
chezmoi is a standard Go project, using standard Go tooling, with a few extra tools. Ensure that these extra tools are installed with:
$ make ensure-tools
$ go build
Run all tests:
$ go test ./...
$ go run .
Generated code #
chezmoi generates shell completions, the install script, and the website from a single source of truth. You must run
$ go generate
if you change includes any of the following:
- Adds or modifies a command.
- Adds or modifies a command’s flags.
- Adds or modifies the list of supported OSs and architectures.
- Modifies the install script template.
chezmoi’s continuous integration verifies that all generated files are up to date. Changes to generated files should be included in the commit that modifies the source of truth.
Contributing changes #
All changes are made via pull requests. In your pull request, please make sure that:
All existing tests pass.
There are appropriate additional tests that demonstrate that your PR works as intended.
The documentation is updated, if necessary. For new features you should add an entry in
docs/HOWTO.mdand a complete description in
All generated files are up to date. You can ensure this by running
make generateand including any modified files in your commit.
The code is correctly formatted, according to
gofumports. You can ensure this by running
The code passes
golangci-lint. You can ensure this by running
The commit messages match chezmoi’s convention, specifically that they begin with a capitalized verb in the imperative and give a short description of what the commit does. Detailed information or justification can be optionally included in the body of the commit message.
Commits are logically separate, with no merge or “fixup” commits.
The branch applies cleanly to
Managing releases #
Releases are managed with
To build a test release, without publishing, (Linux only) run:
$ make test-release
Publish a new release by creating and pushing a tag, e.g.:
$ git tag v1.2.3 $ git push --tags
$ snapcraft export-login --snaps=chezmoi --channels=stable,candidate,beta,edge --acls=package_upload -
brew formula must be updated manually with the command:
$ brew bump-formula-pr --tag=v1.2.3 chezmoi
If you’re packaging chezmoi for an operating system or distribution:
chezmoi has no build or install dependencies other than the standard Go toolchain.
Please set the version number, git commit, and build time in the binary. This greatly assists debugging when end users report problems or ask for help. You can do this by passing the following flags to
-ldflags "-X main.version=$VERSION -X main.commit=$COMMIT -X main.date=$DATE -X main.builtBy=$BUILT_BY"
$VERSIONshould be the chezmoi version, e.g.
vprefix is optional and will be stripped, so you can pass the git tag in directly. The command
git describe --abbrev=0 --tagswill return a suitable value.
$COMMITshould be the full git commit hash at which chezmoi is built, e.g.
4d678ce6850c9d81c7ab2fe0d8f20c1547688b91. The command
git rev-parse HEADwill return a suitable value.
$DATEshould be the date of the build in RFC3339 format, e.g.
2019-11-23T18:29:25Z. The command
date -u +%Y-%m-%dT%H:%M:%SZwill return a suitable value.
$BUILT_BYshould be a string indicating what system was used to build the binary. Typically it should be the name of your packaging system, e.g.
Please enable cgo, if possible. chezmoi can be built and run without cgo, but the
.chezmoi.grouptemplate variables may not be set correctly on some systems.
chezmoi includes an
upgradecommand which attempts to self-upgrade. You can remove this command completely by building chezmoi with the
chezmoi includes shell completions in the
completionsdirectory. Please include these in the package and install them in the shell-appropriate directory, if possible.
If the instructions for installing chezmoi in chezmoi’s install guide are absent or incorrect, please open an issue or submit a PR to correct them.
Updating the website #
Before building the website, you must download the Hugo Book Theme by running:
$ git submodule update --init
Test the website locally by running:
$ ( cd assets/chezmoi.io && hugo serve )
and visit http://localhost:1313/.
To build the website in a temporary directory, run:
$ ( cd assets/chezmoi.io && make )
From here you can run
$ git show
to show changes and
$ git push
to push them. You can only push changes if you have write permissions to the chezmoi GitHub repo.