I'm curious what others workflows are for handling...

# library-development

[zt]

I'm curious what others workflows are for handling versions in new releases. My current process is setting the version property in my root build.gradle.kts, then pushing to GitHub, then manually running my release workflow. Of course this has a huge issue where I've forgotten at times to bump the version, or even once, embarrassingly, published the wrong version. Does anyone have tips on how to better handle this process?

[Joffrey]

The way I do it is that I make the version a parameter of the manual workflow run. So you can't forget because it's a requirement. In your build files, leave the version unspecified. When calling Gradle from the workflow, pass the version parameter with -Pversion

[CLOVIS]

The workflow we use at #C078Z1QRHL3:
• Create a git tag: the first line is the version name, the contents are the changelog
• The CI uses git describe --tags to get a unique version identifier (= to the tag if there's one, something else otherwise)
• That is passed to Gradle as -PappVersion , we have a convention plugin that reads it and overwrites Gradle's version field
• We have a script that generates Markdown blog pages for each tag
Bonus: the full changelog is available to anyone who clones the repo, directly in the tags.

Example result

[mbonnin]

I always have the snapshot version in the repo 1.2.3-SNAPSHOT . When I push a tag, the CI script drops the -SNAPSHOT and publishes a release.
Then I bump and commit the version alongside the changelog.

[mbonnin]

Gives you a longer time window to realize the version is wrong. Then doing a release is just pushing a tag

[Joffrey]

I used to have a tag-triggered setup as well, but I find it inconvenient for cases when I want to perform a release from my phone (if I'm AFK), or from another computer that's not my usual computer. I don't want to have to setup git and development tools just to do a release with a PR I could merge from my phone.

So, now, my release workflow takes the version as an input, and a tag is created as part of the workflow. The tag push from the workflow then may trigger other things

[Joffrey]

The other reason why I moved away from a tag-triggered workflow is that I want my tag to point to a commit that already has the changelog of that version. It always bothered me to see the tag 1.2.3, and then right after a commit with the changelog for 1.2.3. It just felt odd.

[Joffrey]

Here is my setup now (admittedly it's mostly hidden behind my custom action now):
https://github.com/joffrey-bion/krossbow/blob/main/.github%2Fworkflows%2Frelease.yml

[mbonnin]

If you commit the CHANGELOG before then you'll have the changelog in the tag? Whether you publish from tags or manually is irrelevant for that purpose?

[Joffrey]

That only works if you don't generate the changelog as part of the release workflow. If I push the tag to trigger the release workflow, it's too late to commit the changelog from the worlflow

[Joffrey]

My changelog is generated from GitHub issues with my GitHub Changelog plugin, and it's called during the release. That's one less manual thing to do

[mbonnin]

Fair enough 👍. I like to create my CHANGELOG manually in all cases.

[Joffrey]

I do create it manually, in the form of GitHub issues :)

[Joffrey]

+ an optional manual summary

[Joffrey]

I profoundly dislike changelogs that are generated from commits, because commits are irrelevant to users. But I carefully craft and label my issues so the changelog makes sense to users and is properly categorized

[CLOVIS]

or from another computer that's not my usual computer.

We'll see if I change my mind in the future, but so far I consider that a feature: tags can only be created from my two main laptops, because they have to be signed

I want my tag to point to a commit that already has the changelog of that version.

Same, this is why the changelog isn't a physical file, and instead is directly the tag message

[mbonnin]

I never managed to get the tag attributes working 😂

[Joffrey]

Same, this is why the changelog isn't a physical file, and instead is directly the tag message

Interesting! Is this integrated automatically with GitHub releases? As in, is the body automatically read from the git tag message?

[mbonnin]

All in all, after years of trying to automate everything, I gave up and I'm now happy with a bit of manual process that requires me to think about what I'm releasing, I see it as a forcing function.

[CLOVIS]

I profoundly dislike changelogs that are generated from commits

Same. I have a script that generates a changelog, but it's only useful for project contributors. The changelog that is published on the website is hand-written, and doesn't include non-user-facing work (e.g. upgrading test dependencies, adding more tests, etc)

[Joffrey]

> I gave up and I'm now happy with a bit of manual process that requires me to think about what I'm releasing, I see it as a forcing function.
I partially agree. My goal is to automate every little thing that doesn't require to think, so I can focus 100% on things that need a human decision. My manual work now is to organize issues (which I would have to do anyway), to decide on the version number based on what's in the release, and to decide when to release. Then the git tagging, github release creation, maven publication, docs publication etc. should (or at least, can) be automated IMO.

[CLOVIS]

Is this integrated automatically with GitHub releases? As in, is the body automatically read from the git tag message?

Yes and no.

On GitHub, I don't create releases, so it shows the 'tags' list instead. There, it does show the full message, but it doesn't interpret Markdown.

However, I expect that most users will look at the website (which has an RSS feed etc).

Also, I primarly develop on GitLab. The releases system is identical, but it prefills the release with the tag contents, so it takes me two clicks to create a proper release. There is a way to automate it fully but I haven't done it yet, that's not at all in the critical path

[CLOVIS]

The one thing I do want to automate is announcing the new version on socials, that takes a lot of time

[CLOVIS]

I wish all social networks allowed you to say "hey, this is an RSS feed I control, repost everything in it"

[Joffrey]

Ah yeah I don't do socials, I don't really care that much about promotion 😄

[Joffrey]

I don't remember the name, but some dev advocates told me about a tool that allows cross-posting to many social platforms in one go

[CLOVIS]

I have to, since I'm primarily on GitLab, I don't have the advertising of GitHub stars 😐

[mbonnin]

Buffer is good

[Joffrey]

Why do you work primarily on Gitlab, by the way? (if that's not a secret of course)

[mbonnin]

Because it has a GraphQL API 😃 (Buffer, not GitLab, I only use GitHub, because it has a GraphQL API lol)

[CLOVIS]

Not only is it not a secret, I've got an FAQ for it 😆
https://ivan.canet.dev/blog/2024/08/21/gitlab-vs-github.html

[CLOVIS]

(since then GitHub did add its own equivalent of merge trains)

[Adam S]

In my projects I sometimes copy-paste this code into settings.gradle.kts that sets the project version based on the git status.

If the project is clean checkout of a tag starting with v then that's the project version. Otherwise, the version is ${branchName}-SNAPSHOT.

https://github.com/adamko-dev/kotlinx-serialization-typescript-generator/blob/e2faa80f579c263da4ce829f7b511e9c1a19f35b/settings.gradle.kts#L56-L131

[CLOVIS]

oh, just now in the Android Study Group #self-promotion, I'm definitely stealing that

[zt]

Great suggestions! I think I'll settle with manually triggering a workflow that requires specifying the version. Thank you @Joffrey