Hi Everyone,
I had a discussion with Andrea (@whatyouhide) about how to handle
changelogs in elixir itself as well as core libraries.The way how those
libraries implement changelogs is important both to auto-discovery of
changes with auto updating tools like renovate and also because it is a
place for guidance / inspiration for independent library creators.
This proposal is only about the mechanism of publishing changelogs. It is
not about the contents.
*Current state:*
- Core
- Elixir
- per minor release: CHANGELOG.md file
- GitHub release is automatically created
- Artifacts are stored in release
- manual copy of text into GitHub release
- ExDoc
- global CHANGELOG.md file
- manual copy of entry into GitHub releases
- GenStage
- global CHANGELOG.md file
- no GitHub releases
- ElixirMake
- global CHANGELOG.md file
- no GitHub releases
- Phoenix
- per minor release CHANGELOG.md
- some GitHub releases were created, not up-to-date
- Tzdata
- global CHANGELOG.md
- no GitHub releases
- Jason
- global CHANGELOG.md
- manual GitHub releases
- Plug Cowboy
- per major version CHANGELOG.md
- manual GitHub releases
- Telemetry
- global CHANGELOG.md
- outdated GitHub releases
*Possibilities for standardization: *(i can think of, reply with others if
you think something is missing)
- Only CHANGELOG.md
- Changelogs are written by hand and not published via GitHub releases
- Drawbacks
- Hard to automatically discover changes (for example Renovate Bot)
- not as well integrated in GitHub itself as GitHub releases
- does not support extra artifacts like binaries
- Advantage
- simple
- no extra manual labor
- CHANGELOG.md + GitHub releases manual copy
- On release the CHANGELOG.md file is extended with no information.
After the release the notes are copied over into a new GitHub release
manually.
- Drawbacks
- Needs extra manual labor
- Entries can be missing because people forgot to do it
- CHANGELOG.md & Automated GitHub release note
- On release the CHANGELOG.md file is extended and a GitHub workflow
will parse the CHANGELOG.md and use the text to create a release.
- Drawbacks
- Introduces some complexity & maintenance by adding CI workflows
- GitHub releases & automatic appending of CHANGELOG.md file with
release notes
- To release a person would create a GitHub release and a workflow
would automatically prepend the changes to the CHANGELOG.md file
- Drawbacks
- Same as the option before
- Workflow is more complicated because it would need to commit
code by itself
- Imposes a more rigid process on the release workflow while other
options are more flexible.
- Only GitHub releases
- Changes are only published via GitHub releases
- Drawbacks
- not portable if the community ever migrates away from GitHub
- the CHANGELOG.md file does either not exist in published
libraries or would need to be generated on demand out of the releases
*My personal favorite solution so far:*
CHANGELOG.md & Automated GitHub release note
The reason for that preference is that it is relatively easy to automate
and that it offers the best if both worlds.
*Implementation*
I’m happy to provide a shared action as well as PRs for all core libraries.
Such a shared action could possibly be hosted at ErlEF since it could be a
„community recommendation“.
Thanks & Best,
Jonatan
--
You received this message because you are subscribed to the Google Groups
"elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to elixir-lang-core+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/elixir-lang-core/7744dfd3-e94e-45ed-bb10-ca6d5c732550n%40googlegroups.com.
