Skip to content

Latest commit

 

History

History
299 lines (208 loc) · 9.08 KB

CONTRIBUTING.md

File metadata and controls

299 lines (208 loc) · 9.08 KB

chezmoi contributing guide

Getting started

chezmoi is written in Go and development happens on GitHub. The rest of this document assumes that you've checked out chezmoi locally.

The Architecture Guide contains a high-level overview of chezmoi's source code.

Developing locally

chezmoi requires Go 1.16 or later.

chezmoi is a standard Go project, using standard Go tooling.

Build chezmoi:

$ go build

Run all tests:

$ go test ./...

chezmoi's tests include integration tests with other software. If the other software is not found in $PATH the tests will be skipped. Running the full set of tests requires age, base64, bash, gpg, perl, python, ruby, sed, sha256sum, unzip, and zip.

Run chezmoi:

$ go run .

Run a set of smoketests, including cross-compilation, tests, and linting:

$ make smoketest

Generated code

chezmoi generates 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 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

Bug reports, bug fixes, and documentation improvements are always welcome. Please open an issue or create a pull request with your report, fix, or improvement.

If you want to make a more significant change, please first open an issue to discuss the change that you want to make. Dave Cheney gives a good rationale as to why this is important.

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.md and a complete description in docs/REFERENCE.md.

  • All generated files are up to date. You can ensure this by running make generate and including any modified files in your commit.

  • The code is correctly formatted, according to gofumpt. You can ensure this by running make format.

  • The code passes golangci-lint. You can ensure this by running make lint.

  • The commit messages follow the conventional commits specification.

  • Commits are logically separate, with no merge or "fixup" commits.

  • The branch applies cleanly to master.

Managing releases

Releases are managed with goreleaser.

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

This triggers a GitHub Action that builds and publishes archives, packages, and snaps, and creates a new GitHub Release.

Publishing Snaps requires a SNAPCRAFT_LOGIN repository secret. Snapcraft logins periodically expire. Create a new snapcraft login by running:

$ snapcraft export-login --snaps=chezmoi --channels=stable,candidate,beta,edge --acls=package_upload -

brew automation will automatically detect new releases of chezmoi within a few hours and open a pull request in https://github.com/Homebrew/homebrew-core to bump the version.

If needed, the pull request can be created with:

$ brew bump-formula-pr --tag=v1.2.3 chezmoi

Building and installing with make

chezmoi can be built with GNU make, assuming you have the Go toolchain installed.

Running make will build a chezmoi binary in the current directory for the host OS and architecture. To embed version information in the binary and control installation the following variables are available:

Variable Example Purpose
$VERSION v2.0.0 Set version
$COMMIT 3895680a... Set the git commit at which the code was built
$DATE 2019-11-23T18:29:25Z The time of the build
$BUILT_BY homebrew The packaging system performing the build
$PREFIX /usr Installation prefix
$DESTDIR install-root Fake installation root

Running make install will install the chezmoi binary in ${DESTDIR}${PREFIX}/bin.

Packaging

If you're packaging chezmoi for an operating system or distribution:

  • chezmoi has no build dependencies other than the standard Go toolchain.

  • chezmoi has no runtime dependencies, but is usually used with git, so many packagers choose to make git an install dependency or recommended package.

  • 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 go build:

    -ldflags "-X main.version=$VERSION
          -X main.commit=$COMMIT
          -X main.date=$DATE
          -X main.builtBy=$BUILT_BY"

    $VERSION should be the chezmoi version, e.g. 1.7.3. Any v prefix is optional and will be stripped, so you can pass the git tag in directly. The command git describe --abbrev=0 --tags will return a suitable value.

    $COMMIT should be the full git commit hash at which chezmoi is built, e.g. 4d678ce6850c9d81c7ab2fe0d8f20c1547688b91. The command git rev-parse HEAD will return a suitable value.

    $DATE should be the date of the build as a UNIX timestamp or in RFC3339 format. The command git show -s --format=%ct HEAD returns the UNIX timestamp of the last commit, e.g. 1636668628. The command date -u +%Y-%m-%dT%H:%M:%SZ returns the current time in RFC3339 format, e.g. 2019-11-23T18:29:25Z.

    $BUILT_BY should be a string indicating what system was used to build the binary. Typically it should be the name of your packaging system, e.g. homebrew.

  • Please enable cgo, if possible. chezmoi can be built and run without cgo, but the .chezmoi.username and .chezmoi.group template variables may not be set correctly on some systems.

  • chezmoi includes an upgrade command which attempts to self-upgrade. You can remove this command completely by building chezmoi with the noupgrade build tag.

  • chezmoi includes shell completions in the completions directory. 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

The website is generated with Hugo and served with GitHub pages from the gh-pages branch to GitHub.

chezmoi requires the extended version of Hugo which includes Sass/SCSS support. You can verify your Hugo version by looking for extended in the output of hugo version, for example:

$ hugo version
hugo v0.90.0+extended darwin/arm64 BuildDate=unknown

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.