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 On Thu, Jan 19, 2023 at 2:18 AM <an.leopa...@gmail.com> wrote: > 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. > 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 > <https://groups.google.com/d/msgid/elixir-lang-core/591D839A-C8EE-40F4-88AB-8B1E5AF59A71%40gmail.com?utm_medium=email&utm_source=footer> > . > -- Austin Ziegler • halosta...@gmail.com • aus...@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+unsubscr...@googlegroups.com. 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.
