Replace News with GitHub Releases
Closed this issue · 11 comments
The news section seems to have so little exposition on the website that it might be worth to reconsider if it's really needed. Each article on the news page refers to changelog that links issues on GitHub & describes changes, it sounds like worse replacement to GitHub releases section:
Each release is associated with git tag, so we can even backport older releases:
Currently, using GitHub, the only way to see what changed between versions is to compare git history (commits). To find official release notes you have to go to javalin.io and know, that you can find news through footer, because it's not even in the main menu:
To be fair it's so inconvienient that I mostly end up typing javalin.io/news on my own or in Google. I think that this change would be healthier for the ecosystem & after migration, easier to maitain in the future.
I don't think a lot of people read release notes unprompted (the link used to be in the top bar, and less than 1% of users clicked on it. The purpose of the news pages is more to act as an entry point to the website. This box is arguably more important than the post itself.
It still sounds like a valid point to stop using this in a way it is atm. I'd just move to GitHub releases, it'd be more consistent with how projects are managed on this platform in general + that's how our plugins are released, so it'd be even more consistent between projects in the org. The news may stay hidden as it is now, you'd just leave a link to GitHub releases below this box.
I don't mind linking to release from a news post, but we probably need to rework our commit messages to get the most out of this?
Umm it depends, for quite a long time I was writing release notes manually, lately they've added a basic generator, but I think it's up to you how you want to present that. I don't really mind either way, my point here is to just keep it there.
Speaking of the migration, I think it'd be nice to move older releases there as well - we could move all of them or just e.g. all from 3.x/4.x. News are in markdown:
So we could just basically copy-paste this content there.
I agree with @dzikoysk, I like having releases here.
Since you're already creating tags for each release, it's trivial to automatically generate a release using GitHub actions with the commits.
I use ncipollo/release-action for example.
But should we then also switch to https://www.conventionalcommits.org/en/v1.0.0/ (or something similar) to get the most out of this setup?
But should we then also switch to https://www.conventionalcommits.org/en/v1.0.0/ (or something similar) to get the most out of this setup?
Late reply but seems like a good idea. Although you'll be the one doing the commits since you squash when merging.
I used several approaches, and I personally don't like the convention proposed in this link. The best format that works for me is probably:
Pull request title: GH-{IssueId} Description
Commit message (squash): GH-{PullRequestId} {Description} (Resolves/Fixes {RelatedIssuesIds}
It informs you not only about the type of change, but what's even more important for me, it provides realtively easy way to find associated discussion about requested change (issue) & conversation+decisions made during the impl phase (pull request).
I used several approaches, and I personally don't like the convention proposed in this link. The best format that works for me is probably:
Pull request title:
GH-{IssueId} Description
Commit message (squash):GH-{PullRequestId} {Description} (Resolves/Fixes {RelatedIssuesIds}It informs you not only about the type of change, but what's even more important for me, it provides realtively easy way to find associated discussion about requested change (issue) & conversation+decisions made during the impl phase (pull request).
I do agree traceability on commits/PRs is important, but its nice to know what the change does right away even if it's not related to an issue/PR.
We can automate using this two actions:
https://github.com/marketplace/actions/release-drafter
https://github.com/marketplace/actions/gh-release
Also, when a released is published users that choose to are notified.
This has largely been done now.