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.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 > > <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/40d3f2cf-be0f-4634-9dfc-13fd25500003%40app.fastmail.com.
