Handling of changelogs in elixir core

[Jonatan Männchen]

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

[Zach Daniel]

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.

--
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.

[Zach Daniel]

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.

[Jonatan Männchen]

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.

[Zach Daniel]

I agree, the changelog needs to be able to be modified after the fact. With `git_ops` today, it allows you to modify the changelog before committing and pushing (or just to run that whole flow yourself, it spits out the commands to run). But it doesn't support modifying the release notes that get added to the tag at this point. But it could be added I'm sure!  I agree it would be a pretty big change, my feelings won't be hurt or anything if people decide not to use it, but its at least an example of an attempt to solve for/standardize some of these kinds of things.

On Fri, Jan 13, 2023 at 10:12 AM, Jonatan Männchen <jon...@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.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@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.

[Austin Ziegler]

That sounds neat, but I *personally* have a problem with conventional commits. For those not familiar, the format is basically

```

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

```

The width of the title line of a commit is supposed to be ~52 characters, but `feat(scope): ` eats up 13 of those characters, meaning that the subject can’t exceed 39 characters. Even if you skip scopes, you’ve lost a minimum of five characters for a commit title line (`bug: `). I know that not everyone writes good commit messages (tpope and Chris Beams have excellent blog posts on these), but using the *title* line to help a program do something useful is the very definition of Doing The Wrong Thing.

I’d support a *trailer* / *footer* like `commit-type: feat!` (feature with breaking change), but I’m already involved with one project that uses conventional commits and I hate writing commits there, because the title should be short but meaningful, and that’s hard in 52 characters.

-a

(Sorry. I’ve not really had a place to rant about this because I stopped blogging years ago, I’ve given up on Twitter, have no Mastodon presence, and no one on Facebook would care.)

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/lcum3vai.3a0f4bc0-3666-4af2-90bc-8381592ba17b%40we.are.superhuman.com.

--

Austin Ziegler • halos...@gmail.com • aus...@halostatue.ca
http://www.halostatue.ca/ • http://twitter.com/halostatue

[Zach Daniel]

I like that idea We have a nimble_parsec commit parser, so we could add support for extending the formats we accept.

On Fri, Jan 13, 2023 at 11:06 AM, Austin Ziegler <halos...@gmail.com> wrote:

That sounds neat, but I *personally* have a problem with conventional commits. For those not familiar, the format is basically

```

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

```

The width of the title line of a commit is supposed to be ~52 characters, but `feat(scope): ` eats up 13 of those characters, meaning that the subject can’t exceed 39 characters. Even if you skip scopes, you’ve lost a minimum of five characters for a commit title line (`bug: `). I know that not everyone writes good commit messages (tpope and Chris Beams have excellent blog posts on these), but using the *title* line to help a program do something useful is the very definition of Doing The Wrong Thing.

I’d support a *trailer* / *footer* like `commit-type: feat!` (feature with breaking change), but I’m already involved with one project that uses conventional commits and I hate writing commits there, because the title should be short but meaningful, and that’s hard in 52 characters.

-a

(Sorry. I’ve not really had a place to rant about this because I stopped blogging years ago, I’ve given up on Twitter, have no Mastodon presence, and no one on Facebook would care.)

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@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.

--
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+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/lcum3vai.3a0f4bc0-3666-4af2-90bc-8381592ba17b%40we.are.superhuman.com.

--

Austin Ziegler • halostatue@gmail.com • austin@halostatue.ca
http://www.halostatue.ca/ • http://twitter.com/halostatue

--
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+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAJ4ekQs3%2BqXmiFhOiQkdZVX8sRob%3DFNw9agDH9jRy5J2UZmKgQ%40mail.gmail.com.

[an.le...@gmail.com]

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

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/603e9638-34bf-4cb6-ae75-c308322d6fbfn%40googlegroups.com.

[Austin Ziegler]

I mostly agree with Andrea. The benefit to a tool (especially one that provides conventional-commits-like support without the header mistake that conventional-commits makes) is that it could gather the commit messages into a meaningful thing to assist in writing the changelog. Then again, one can do this pretty easily with `git log LAST_TAG.. --format=%B --reverse | pbcopy`, which I *also* do quite often in order to update a multi-commit PR message.

I’ve heavily automated the production of the changelog for exactly one of my projects and to some degree, it’s over-automated, but I have had no time to pull it back into something more reasonable.

-a

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/591D839A-C8EE-40F4-88AB-8B1E5AF59A71%40gmail.com.

[Jon Rowe]

As a maintainer (mostly for a Ruby library) I’d love to see a github action that automatically updates releases based on a github tag and extracts the changelog from the manual file, as thats much easier to maintain when working on PRs / branches. So I guess consider that a plus one for manual files / tags, with additional automated tooling around updating GitHub etc.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAJ4ekQsn8Akf8x%2Bam7oZ3s6d_4FJg_EuJnO%2BSUdog5vXjxgJ%3Dw%40mail.gmail.com.

[Yordis “Alchemist Ubi” Prieto]

I have been doing the CHANGELOG.md + GitHub "Generate release notes" on the Releases page for a while. Workflow that has worked for me.

In PR
1. Clear PR title
2. Must update the CHANGELOG.md file under "Unreleased section"
3. (Optional) Bump the version in the `mix.exs`

Release
1. Visit the Release page

2. Create a tag with a format of `v + semver` (v2.4.5)

3. Click in "Generate release notes"
4. (Optional) Release using CI to Hex