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.

Reply via email to