[PROPOSAL] Automate versioning and changelog generation with release-please

[rhysmcneill]

Summary

I'd like to suggest adopting release-please to automate versioning, changelog generation, and release tagging. Given the project's high release cadence and already-structured CHANGELOG, this feels like a natural next step.

---

Current release workflow (as I understand it)

1. Maintainer writes a CHANGELOG.md entry by hand
2. Decides the next version number manually
3. Pushes a v* tag
4. The release.yaml workflow fires, runs GoReleaser, builds cross-platform binaries and the UI archive, then publishes the GitHub release and updates the Homebrew tap

This works well — but as the project scales, the manual steps become the highest-friction part of the loop.

---

The problem at current release velocity

Looking at the changelog, skillshare ships very frequently — v0.20.5 through v0.20.9 landed across just three days (2026-06-02 to 2026-06-05). At that pace:

• Handwritten changelog entries accumulate fast. The CHANGELOG.md is already ~195KB / 2700+ lines, and every entry is manually authored.
• Version decisions are a constant interruption. For each release someone has to reason about whether it's a patch, minor, or major bump.
• Tag pushes are easy to forget or mistype. A mis-tagged commit means a wrong release name is published to all install methods (Homebrew, install.sh, PowerShell, GitHub Actions).

---

What release-please would change

release-please reads Conventional Commits and does three things automatically:

Today (manual)	With release-please (automated)
Write CHANGELOG.md entry	Generated from commit messages, same structured format
Decide semver bump	Derived automatically: feat: → minor, fix: → patch, breaking change footer → major
Push git tag	Happens when the Release PR is merged

Concretely, the workflow becomes:

1. Commits land on main using Conventional Commit messages (e.g. feat: add zed target, fix: respect .skillignore in audit)
2. release-please opens (or updates) a Release PR — a single PR titled "chore(main): release v0.20.10" — that contains the bumped version and generated changelog diff
3. When you're ready to ship, merge the PR — release-please creates the tag
4. The existing release.yaml fires on the new tag, GoReleaser does everything it already does today

Step 4 requires zero changes to your GoReleaser setup or existing release.yaml.

---

Why this fits skillshare particularly well

• You're already close. Your .goreleaser.yaml changelog.filters already excludes docs:, test:, ci: — the conventional-commit vocabulary is informally in use. release-please just formalises it.
• The CHANGELOG format maps cleanly. Your current headings (### New Features, ### Bug Fixes, ### Breaking Changes, ### Performance) correspond directly to how release-please renders its sections (feat, fix, feat!/BREAKING CHANGE, perf).
• Release PRs give a review moment. At your shipping pace, having a pending PR that accumulates all changes before a release gives you a natural gate — merge it when you're ready, skip it when you're not.
• Single-maintainer friendly. The entire release is a PR merge. No local commands, no tag pushes, no manual version arithmetic.

---

Rough migration path

This is just for illustration — happy to adapt based on your preferred approach:

# .github/workflows/release-please.yaml
name: Release Please

on:
  push:
    branches:
      - main

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          release-type: go

The existing release.yaml (which triggers on v* tags) would continue to work without modification.

A release-please-config.json can also tell it to skip bumping the Go module path if needed, and the changelog sections can be customised to match the existing headings exactly.

---

What I'm not proposing

• Replacing GoReleaser — it stays exactly as-is for artifact building and Homebrew publishing
• Enforcing commit message linting via CI (though that's a natural follow-on)
• Any change to the development setup or devcontainer

---

Happy to put together a draft proposal in proposals/ if that's the right next step per the contributing guide. Let me know if this is something worth exploring or if there's a reason the current manual flow is intentional that I've missed.

[runkids]

Thanks for the detailed write-up — well researched. The manual version bump and tag push are genuinely the highest-friction steps, so I'm happy to explore this.

A proposal in proposals/ following the contributing guide sounds like a great next step. Please go ahead — thanks!

[rhysmcneill]

Hey @runkids!

I'm glad you are onboard with the idea, I have implemented this release-flow automation in many other projects that were using a manual release workflow, and release-please significantly improves DevEx.

I'll put together the proposal in due course, and afterwards we can speak about the granularities - Happy to work on this as well if you are happy to go forward with the proposal when it's created.

Thanks!

[rhysmcneill]

Hi @runkids

Proposal added - I ensured there was significant detail so you understand the workflow e2e. It is actually a medium size change so please do not be frightened by the size of the proposal - extra context for these things is always better than less.

Within the proposal you will see other projects where I have implemented this - take a look if interesteded, or want extra context. I think workflow will benefit this project significantly and let you focus on things that add value rather than worrying about manual releases 🙂

Let me know your thoughts!

[rhysmcneill]

Hey @runkids!

I just noticed that the proposal PR was merged, and closed, along with this issue. However, there has not been any feedback surrounding the proposal.

Can you please let me know about next steps?

[runkids]

Hey @rhysmcneill — sorry for the silence, the issue auto-closed when the PR was merged. The proposal looks great and I'm on board with the direction. It touches the release pipeline though, so I'd like to take some time to research and trial release-please carefully before wiring it in. I'll follow up here once I've experimented and have a clearer idea of how I want to roll it out. Thanks again for the thorough write-up 🙏

[rhysmcneill]

@runkids no worries!

If you need any support, or want any help with implementation then I am here to help.

Additionally, I'm open to creating a PR for the actual change itself but totally understand if it is something you want to implement yourself to understand workflow e2e.

Just let me know which you prefer. 😀

[runkids]

Thanks @rhysmcneill! Go for it — happy to have you open the PR, I'd enjoy reviewing it and learning from your setup. Looking forward to it 🙏

[rhysmcneill]

Sure thing @runkids

Assign this issue to me, and I'll get started on a PR when I get some free time this week.

Thanks