changie: a changelog tool that keeps release notes out of your commits

The problem is the conflict, not the writing

The one line pitch in the README is unusually precise: separate your changelog from commit messages without conflicts.

Most changelog workflows have the same shape. Someone writes a CHANGELOG.md, or accumulates entries in a scratch file, and at release time the changelog has to be committed. If two releases overlap, or a hotfix lands while a release is being prepared, that commit conflicts with the branch everyone else is working from. The changelog then becomes the reason a release is delayed.

Changie's answer is to make the changelog file-based rather than commit-based. The features list puts it first: file based changelog management keeps your commit history and release notes separate.

The second feature is about when the writing happens. Track changes while you work while the knowledge is fresh. That is the real argument for a separate tool. A commit message is written to describe one change to one file, and a release note needs to describe a change to the product as a user experiences it. Those two texts are not the same, and the moment when a person still remembers both is the moment right after the work, not the moment before the release.

The other two features are about fit. There are extensive configuration options to fit your project, and Changie is language and framework agnostic using a single Go binary. That last point is what makes it usable in a polyglot organisation: the tool has no opinion about your build system, it just writes files and reads a configuration.

Fragments in .changes, unreleased in then/

The repository layout shows the data model without needing the documentation.

At the top level there is a `.changes/` directory and a `then/` directory, plus a `.changie.yaml` configuration file and a `changie.json`. The `then/` name suggests the staging area for changes that are recorded but not yet released, and `.changes/` is where the released fragments live.

So the workflow implied by the layout is: while you work, each change is captured as its own small file rather than being appended to one shared document. At release time, the pending fragments are batched into a new version section and the changelog is regenerated. Because each pending change is a separate file, two people recording changes at the same time never touch the same file, and there is nothing to conflict.

That also explains the last feature of the list in the README, that Changie's own Changelog is generated by itself. A project whose changelog is its own first user is the cheapest possible proof that the tool works on a real project, and the CHANGELOG.md in the repository is the output of the tool running on its own history.

The `examples/` directory reinforces the picture. It contains `quick_start.gif` with its `.tape` source, `custom_prompts_config.yaml` with `custom_prompts.gif`, and `projects_config.yaml` with `projects.gif`. Those two configuration files are the interesting ones, because they name the two dimensions of configuration the project treats as first class: the prompts contributors are shown, and the notion of projects, which is how a monorepo tracks changes to several components separately.

The `.tape` files next to the gifs are VHS tape definitions, so the examples are recorded as reproducible terminal sessions rather than hand edited screen captures.

Prompts and projects are configuration, not code

Changie is described as an automated changelog tool for preparing releases with lots of customization options, and the configuration surface is the point of the project.

Two configuration files at the repository root make that concrete: `.changie.yaml`, the YAML form, and `changie.json`. The Go module confirms YAML is a first class input, with `gopkg.in/yaml.v3` as a direct dependency, and `github.com/invopop/jsonschema` for generating a JSON schema, which is how a configuration editor can offer completion and validation.

The `custom_prompts` example is the mechanism for making the tool fit a team's release process. Rather than asking a fixed question such as what changed, the project defines its own set of prompts, so a team can ask for a breaking change flag, a component name, an issue reference, or anything else their process requires, and the answers land in the fragment file.

The `projects` configuration is the other axis. A monorepo that releases several components needs the changelog to record which component changed, and needs to be able to batch and release those components independently. The example file `projects_config.yaml` shows that as a supported mode rather than a workaround.

Two more dependencies hint at what the tool does internally. `github.com/Masterminds/sprig/v3` is the template function library used for the version header and body templates, which is how the changelog format is customised without writing Go. And `github.com/kballard/go-shellquote` is there for building shell commands safely, which is how a fragment can record a command to run rather than just a note.

The CLI itself is built on `github.com/spf13/cobra`, and the interactive prompts use `github.com/cqroot/prompt` with the `charmbracelet/bubbletea` terminal UI underneath.

One binary, four ways to get it

Changie ships as a single Go binary, and the repository shows four delivery routes.

The npm route is a wrapper package. The package.json declares the binary as `changie` bound to `npm/changie.js`, and the `files` array lists prebuilt executables for darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-ia32.exe and win32-x64.exe, along with the launcher script and the README and LICENSE. So a team that already has Node in its toolchain can add the changelog tool with the package manager they already use, without a separate installation step.

The Docker route is as small as a container image gets:

FROM scratch
ENTRYPOINT ["/changie"]
COPY changie /

A `scratch` base means no shell and no package manager inside the image, so the image contains the static binary and nothing else. That is the right choice for a tool invoked from a CI pipeline.

The Go route is the package itself. The go.mod declares the module as `github.com/miniscruff/changie` and requires Go 1.26, with a dependency list that reads like a description of the tool:

require (
	github.com/Masterminds/semver/v3 v3.5.0
	github.com/Masterminds/sprig/v3 v3.3.0
	github.com/charmbracelet/bubbletea v0.24.2
	github.com/cqroot/prompt v0.9.3
	github.com/invopop/jsonschema v0.14.0
	github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51
	github.com/spf13/cobra v1.10.2
	gopkg.in/yaml.v3 v3.0.1
)

`Masterminds/semver` is there for version parsing and comparison, `cobra` for the command structure, `bubbletea` for the terminal prompts, and `yaml.v3` for the configuration file.

There is also a Ruby wrapper, `changie.rb`, in the repository root, and a `changie.json` alongside it, so the tool is reachable from Ruby tooling as well.

Finally, there is a Changie GitHub Action, a separate repository at miniscruff/changie-action, which is the piece that fits into a release pipeline rather than a developer's terminal.

The CLI is the compatibility contract, the package is not

The Semantic Version Compatibility section is short and unusual enough to be worth reading twice.

Changie is focused around the CLI and its configuration options and aims to keep existing CLI commands and options supported in major versions. So the promise is about the surface a user or a CI script actually touches: the commands and the flags.

The next sentence is the one that matters if you are considering importing it as a library. It is possible to use Changie as a dependent package but no support or compatibility is guaranteed.

So the package is importable, the Go module is published on pkg.go.dev, and the internal API can change without a major version bump. That is a deliberate division, and it makes sense for a tool whose value is its command line behaviour, but it means the code in `core/` is not a stable dependency. A team that wants to vendor the logic rather than call the binary should assume they own the fork.

The same logic applies to the configuration file. Since the configuration options are explicitly part of what major versions keep supported, the `.changie.yaml` you write is portable across major versions, and it is the thing to treat as an interface in your own repository.

The documentation is the other half of the contract. The README points to the website at changie.dev for user documentation, with the guide at changie.dev/guide as a good place to start, and a separate configuration reference at changie.dev/config. The repository builds that site with mkdocs and the material theme, which the requirements.txt shows pinned in full, including mkdocs-macros-plugin and mkdocs-material-extensions.

MIT terms and a release cadence you can plan around

Changie is distributed under the MIT License, with the LICENSE file at the repository root and the same licence declared in the npm package. MIT is the pragmatic choice for a build-time CLI that sits in everyone's release pipeline, and it means the fragments and the changelog it produces carry no obligations of their own.

The release history is regular. The tags are v1.25.1 on 2026-07-20, v1.25.2 on 2026-08-04 and v1.26.0 on 2026-08-20, with the last push on 2026-10-17. Patch releases inside a minor line and a minor release every few weeks is the pace of a tool whose users are release pipelines, where a change in behaviour is felt immediately by whoever cuts the next release.

The project tooling around it is conventional. There is a Makefile, a `.golangci.yml` for linting, a `.goreleaser.yml` for building and publishing the binaries, a Dockerfile for the scratch image, a `cmd/` directory for the command entry points with `core/` holding the implementation, `main.go` at the root, `docs/` for the mkdocs site source with `mkdocs.yml` beside it, and `.github/` for the workflows.

The project is also explicit about how it wants contributions. Bug reports and feature requests go to GitHub issues, help requests go to the discussions page, and the README asks you to file an issue before creating a pull request unless the change is something simple like a typo. CONTRIBUTING.md and CODE_OF_CONDUCT.md are both in the repository.

One last detail that says a lot about the project's own release discipline: the CHANGELOG.md at the repository root is generated by Changie itself, from fragments in `.changes/`, with the unreleased queue in `then/`.

Editorial conclusion

Adopt changie when your team ships often enough that assembling release notes from commit messages is a recurring chore, and you want contributors to record a change while the context is fresh. Skip it if you need a single hand written changelog file, or if you cannot accept a CLI whose configuration is the compatibility contract. Verify first that the fragment format in `.changes/` and the `then/` directory match how you tag releases, and read the configuration reference at changie.dev/config before you commit to a layout, since the configuration options are the stable surface. The licence field on the repository says MIT, the last push was on 2026-10-17, and the current release is v1.26.0.

Frequently asked questions

Official sources

1. License: MIT
2. miniscruff/changie on GitHub
3. Project website
4. README
5. Releases