Hey Jonatan, Thanks for starting this discussion.
I'm personally a fan of having changes described and available in CHANGELOG.md files at the root of each repository. This has the big benefit of not having to rely on an external service (GitHub) in order to check information about changes: all the information is available and self-contained in the repository. For this reason, in all of the repositories I'm involved with, we also use Git tags to tag releases. In general, for each release, we do something like this: Update version in mix.exs Go through commits since the last Git tag (that is, the last release) and put together a changelog entry. I personally find it important to do this manually and not in an automated way, since changelog entries are generally significantly shorter and more information-dense than just a list of commit messages. Create a commit with the message being something like "Release vX.Y.Z" Create the vX.Y.Z Git tag and push it to GitHub. Release on Hex. This workflow should check the boxes you mention and also the ones I mention: It leaves information about changes in the repository, making the repository self contained. It's discoverable by tools, since tools can look for Git tags to know about releases. Elixir itself is not a great example to follow, because it has a more complex release process than probably any library out there. Last but not least, I'm not 100% convinced that we do need to standardize the community on an approach. Thoughts? Andrea > On 13 Jan 2023, at 17:12, Jonatan Männchen <jona...@maennchen.ch> wrote: > > Cool library, I definitely have to check that one out for some of the > internal projects I'm working on. > > I did think about Conventional Commits when writing this proposal but decided > to only include the publishing mechanism and not the contents of the > changelog / release notes. > The reason for this is, that something like Conventional Commits is a big > change in the development / workflows of the affected projects. > > If all involved parties are open to this massive change, it would open the > doors for a lot of pre-existing tooling like your library or Googles release > please. > > I'm not convinced myself that Conventional Commits are the way to go for > projects like those. The main issue I have with the convention is that > commits don't necessarily describe the intention of changes well. One could > for example make 5 commits about a specific topic but describe it as one > change in the release notes. > On Friday, January 13, 2023 at 3:32:41 PM UTC+1 zachary....@gmail.com wrote: >> Forgot the most relevant point: it can automatically include the generated >> release notes in the git tag that is generated which translates to release >> notes when pushed. >> >> >> On Fri, Jan 13 2023 at 9:31 AM, Zach Daniel <zachary....@gmail.com <>> >> wrote: >>> My library git_ops https://github.com/zachdaniel/git_ops is a native elixir >>> solution for managing a change log with tags for releases. Im sure it could >>> be improved, but it’s a solid foundation that a lot of people are using >>> today. Plus, the conventional commit format is a well known already >>> specified pattern: https://www.conventionalcommits.org/en/v1.0.0/ >>> >>> It provides a mix task that automatically determines the next version based >>> on the types of commits, and writes any relevant commits to a changelog >>> file. >>> >>> In standardizing the changelog practices, you could also standardize the >>> commit/next version practices. >>> >> >>> On Fri, Jan 13 2023 at 6:28 AM, Jonatan Männchen <jon...@maennchen.ch <>> >>> wrote: >>>> 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-co...@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 >>>> >>>> <https://groups.google.com/d/msgid/elixir-lang-core/7744dfd3-e94e-45ed-bb10-ca6d5c732550n%40googlegroups.com?utm_medium=email&utm_source=footer>. > > > -- > 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 > <mailto:elixir-lang-core+unsubscr...@googlegroups.com>. > To view this discussion on the web visit > https://groups.google.com/d/msgid/elixir-lang-core/603e9638-34bf-4cb6-ae75-c308322d6fbfn%40googlegroups.com > > <https://groups.google.com/d/msgid/elixir-lang-core/603e9638-34bf-4cb6-ae75-c308322d6fbfn%40googlegroups.com?utm_medium=email&utm_source=footer>. -- 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/591D839A-C8EE-40F4-88AB-8B1E5AF59A71%40gmail.com.
