Changelog Format

[t-moe]

Hello,

I appreciate that you're developing Sampo and especially value the zero-configuration approach, which strives to "do the right thing out of the box". ( With knope have to mention every crate and their intra-depenceny in knope.toml)

I'm writing to ask about the changelog format and its future direction. Currently, neither Sampo nor Knope adheres to a widely recognized standard like Keep a Changelog. Could it make sense to adopt such a standard format?

I've made a few observations about how the current formats differ, which informs my curiosity about your roadmap:

• File Introduction: Knope allows for a header/intro at the top of the file, whereas Sampo simply prepends new versions, ignoring any existing intro.
• Custom Headings: Knope permits the introduction of new headings/types (e.g., a "Notes" section).
• Content Complexity: Knope supports items that are simple or more complex (with a heading plus a Markdown body). Sampo currently copies the changeset content unmodified.

Given these differences, I am wondering: Are there any steps planned in extending or refining the current changelog format in Sampo?

I'm simply looking for information on your team's existing roadmap or intentions regarding the evolution of the changelog format.

Thank you.

[goulvenclech]

Hi @t-moe ,

Thanks for your message, I'm glad to read Sampo is of interest! I'm currently on holiday, and I won't be able to fully dig into your points until October 1st... but here three quick reactions:

1. Sampo should definitely preserve any Changelog header/intro. I’ll fix that.
2. Sampo currently copies the Markdown from each changeset as-is, so you should be able to include headers, lists, or any other formatting. Could you clarify what specific functionality or formatting you're looking for that's missing right now?
3. I’m not familiar with Keep a Changelog or common Knope custom type usages. I’m slightly reluctant to move away from Sampo’s current, very SemVer/Changesets/Lerna-style format, because I think it keeps things simpler both for maintainers and for users. That said, nothing is set in stone at this stage, I'm open to being convinced 🙂

I’ll follow up in more details after my break!

[goulvenclech]

Hi again, just a quick update :

1. Changelog intro / header
Tracked in #75 and fixed in #76. When updating changelogs, Sampo now preserves any intro content or custom main header before the first ## section. You can also manually edit previously released entries, and Sampo will keep them intact.

As said in the issue/PR body, this won't support custom sections between the intro and version entries (e.g., an ## Unreleased section), because this would require parsing the changelog file... I don't really like that, as I want to keep Sampo easy to opt in and out, without assuming that previous sections were generated by Sampo, and to allow users to manually edit previous release sections after generation.

2. Content complexity / headings in items
Awaiting your clarification on this.

3. Standardized categories (Keep a Changelog, etc.)
I haven’t created an issue yet, since the design isn’t settled and it’s not a priority at this stage. But here's my current thinking:

Sampo should continue to default to Changesets/Lerna-style output (with changes grouped by bump level), which is way easier (I believe so) to adopt and understand, both for maintainers and users. But I do see the value in supporting optional custom categories (like Added, Changed, Deprecated, etc. from Keep a Changelog), which users could define (and maybe map to a bump level ?) in the config. The CLI would then let you pick a category (e.g., Added as minor, Removed as major), and changelogs would be generated with the appropriate sections. That would allow teams who want to follow Keep a Changelog (or similar formats) to do so, without changing the out-of-the-box behavior (and Knope's changeset parser already support custom types, handy!)

I'd be happy to hear your thoughts or feedback on this 🙂

[t-moe]

Hi @goulvenclech ,
Thank you for the quick response, and super quick fix of #75.

Content complexity / headings in items

Sampo behaves a bit different compared to knope:

• Sampo copies the changeset body as-is into the changelog.
• Knope supports two kinds of changesets and does some processing on the changeset body for complex changes: https://knope.tech/reference/concepts/release-notes/#simple-vs-complex-changes

I'm not saying we need the same behavior in sampo. I just noticed the difference, and was curious about your roadmap.

Standardized categories (Keep a Changelog, etc.)

I'm not familiar with lerna-style output.
But I do observe that Rust open source projects often adhere to Keep a Changelog. There is often no fixed mapping between bump type (major,minor,patch) and heading (Added, Changed, Removed,..). Instead, I do see that some projects add a **Breaking** in front of a line, to indicate major bumps, but apart from that stick to the standardized headings (Added, Changed, Removed,..)

Would you be open to merging PRs that enhance or extend the changelog formatting to support these more standardized styles? We could implement this on an opt-in basis to maintain the current Lerna-style output as the default.

[goulvenclech]

Unrelated, but I really liked the release timestamps on version headers in Keep A Changelog, so that was added via #78 .

Content complexity / headings in items

Personally, I much prefer Sampo’s approach, which I find both simpler to understand, easier to use, and easier to adapt to one’s needs. Especially via the CLI: the user selects the version bump, then writes a free-form message, without having to remember any specific conventions or structures.

If a change requires more details, the user can simply open the corresponding Markdown file and add any explanation or formatting he want... what you write is exactly what will be published in the changelog (with enrichment such as the commit hash and contributor thanks, which can be disabled in the config), with no further parsing or transformation (WYSIWYG).

This solution has proven its robustness and scalability on large open-source projects like PNPM, Astro, and SvelteKit (all three use Changesets), so I don’t think the additional burden of stricter conventions is really justified.

Standardized categories (Keep a Changelog, etc.)

I have a proposal to keep the current behavior as the default, but also allow the use of Keep a Changelog (or similar formats) in Sampo:

Add a config option called changelog.tags (placeholder name, open to better suggestions) that can accept strings like Added, Fixed, Deprecated, etc. When this option is empty (which would be the default), the CLI behavior remains unchanged. But when this option is set, a new dialog appears between the bump selection and the message entry—something like “Tagged as…?” with a radio menu for the available tags. This tag is then stored in the changeset as something like package: minor (Added) (which the changesets crate would parse as ChangeType::Custom("minor (Added)")). The first part is used to compute the bump, and the second part is used for changelog generation (e.g., ### Added instead of ### Minor changes).

What do you think? I’m ready to work on a solution like this (or something similar), but only after the other items currently on my TODO list (finishing the current release about prerelease branches, then adding NPM support and improving the publishing workflow).

If you’d like to contribute tho (once we’ve discussed and agreed on a general direction), you’re more than welcome to. Of course, we’ll be available to review and merge your PR as quickly as possible.

[t-moe]

Thank you. I like your proposed changelog.tags configuration. Right now, I need to focus on some higher-priority, unrelated tasks. I'll get back to you if I find I really need this feature down the road. Feel free to close this discussion in the meantime.

[goulvenclech]

No problem @t-moe , I’ve opened issue #120 to track this proposal, and I should have bandwidth to handle it soon. If you have any other ideas or comments in the meantime, let’s continue the discussion there.