3 ms·
We built an internal system that grabs our git history. For each commit you either enter a release note or mark it as not customer facing. It’s worked pretty we
by ddulaney 2y ago
We built an internal system that grabs our git history. For each commit you either enter a release note or mark it as not customer facing. It’s worked pretty well so far: each developer runs through their list writing down something, and a technical writer follows up checking style and grammar. We have confidence that every commit was at least looked at.
We do monthly releases, and the level of effort has been under an hour each month per dev, which has been super worth it for us.
- Jochim 2y agoI've seen the same thing done within the ticketing system. It's useful when you might want non-developers to contribute to the notes. Being able to dedicate a tag, field, or work item type is pretty handy.
- weinzierl 2y agoWe considered generating the changelog from the git commits, the information contained in the PR and from the ticket. Ultimately we also decided to go with the tickets, but I am curious what your reasoning was to go that way?
- Jochim 2y agoSadly, we didn't end up implementing it ourselves. Release notes were a "nice to have" so it became one of those things that gets kicked down the road. The primary advantage of the ticket-based approach is that it's much easier to involve non-dev stakeholders. I'd choose it whenever other people might want input in the process. Most ticketing systems also offer a lot of flexibility, you could incorporate the ticket name, group tickets by relation, block completion states, act on deployments, etc. The ability to edit the note without rebasing is a major bonus as well. The git-based approach potentially leads to a more readable commit history, and strongly associates any release notes with the actual code change. On the other hand, it's a pain to edit and can distract devs while they're problem solving if not setup well.
- ddulaney 2y agoThe reason I didn’t go with a ticket-based approach is that we don’t have a perfect 1-to-1 mapping of commits to tickets. The worry was that we would miss commits because they weren’t well-associated. Because the tool we made is web-based, it’s a little less scary for non-devs.
- keybored 2y agoIt grabs the history? So it is written after the fact (after the commit message)? Where is it stored?
- ddulaney 2y agoIt stores it in a “branch” that’s totally separate from the main branch, kinda like git-notes. We push that branch to our git forge like normal, so there are copies of it all over the place, and we can make a CLI tool if we ever want to. It works really well so far.
- keybored 2y agoThat’s cool that you make it separate from the commit message and yet linked to it. We also might need customer facing release notes at some point. But that shouldn’t be in the commit messages I think since it’s irrelevant in that technical context.
- ddulaney 2y agoYeah, I pretty strongly agree that it shouldn't be in commit messages. A big consideration for us was that we didn't want to get in the way of normal development, and Git is a core part of that loop. By making the release note a thing that happens separately, we let devs batch that work before a release. But the tool displays the commit right as you're writing the note, so you can quickly see what internal-facing commit message you wrote at the time, and copy-paste if you think it's good enough.
- keybored 2y agoI love that approach. Everything is linked but nothing pollutes the wrong context.