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.