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 On Thursday, January 19, 2023 at 9:26:18 PM UTC-5 ma...@jonrowe.co.uk wrote: > 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. > > On Thu, 19 Jan 2023, at 7:27 PM, Austin Ziegler wrote: > > 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.le...@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 <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. > > > > > > 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-co...@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-co...@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 • halos...@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-co...@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 > > <https://groups.google.com/d/msgid/elixir-lang-core/CAJ4ekQsn8Akf8x%2Bam7oZ3s6d_4FJg_EuJnO%2BSUdog5vXjxgJ%3Dw%40mail.gmail.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/254d7621-150b-4369-84aa-cc581edf3ba1n%40googlegroups.com.
