Versioning is a solved problem. Stop doing it by hand!
When I was building PrintLyrics, I wanted a version number displayed at the bottom of the page. For the most part, this was a sanity check for myself to ensure that my deployments were making it to production. It got me thinking: how do people do this? They might have a version file, and the chances of that version being updated consistently and accurately reflecting the state of the application are quite low. When it’s time to create a new release, they look at the commit history, make an educated guess about which part of the semantic version to bump, then create a tag and release based on that number. I’m here to make a proclamation: you don’t have to do this manually!
I talked to a whole bunch of people this past week at SF Ruby Conference, and I was surprised to hear that nobody else had even heard of release-please. Here’s how I use it in my projects. I use Rails, but this tool works across frameworks and project types. It works everywhere.
At a high level, the steps are simple
- Conventional Commits are the input—specifically, PR titles. I’ll get to that.
release-pleasereads the history of mymainbranch.- A release PR is generated or updated based on that history.
- A tag and release are created when that release PR is merged.
In the age of development with AI agents, how do we ensure they commit consistently? There are two main components to making this work effectively.
Bootstrapping the repository
Here’s a bootstrap template that you can send your agent. It does the following:
- Turns on squash-only merges, so every PR hits
mainas a single commit. - Sets the squash commit title to the PR title, so a Conventional Commit title becomes the commit message that
release-pleasewill read. - Requires every PR targeting
mainto pass the checks and policy status checks. - Blocks force pushes and deletion of
main. - Locks
v*release tags so they can’t be changed or deleted. - Requires all review threads to be resolved before merging.
- Shows exactly what it will change before changing anything. Nothing happens without
--apply.
I’ve made some opinionated choices in this script based on my workflows. It’s a starting point, so adapt it to your workflow.
Tell your agent how to commit
If you explicitly tell your agent how to write commits and title PRs, you give it clear guidance for passing the policy check. I do this with two simple components:
- A docs/git_conventions.md file that outlines general Git practices. Again, this is a template—adjust it to your workflow.
- A very simple AGENTS file that tells your agent to look at those Git conventions when performing Git operations.
Working on a team
I’ve found these patterns and practices to be particularly useful when working on a team. The policy checks and repository settings enforce the guidelines. The documentation is referenced from AGENTS.md using a progressive disclosure strategy, so agents that follow AGENTS.md can find the relevant guidance when they need it. If you’re using Claude, do the same with your CLAUDE.md.
Comments