questions and tips about git versioning

[Dieterbe]

The way Tine is versioned / uses git is a bit confusing. Here are some questions and advice.

1. advice: use a beta branch, not just a beta tag. for people following along at home - who want to consume the latest beta builds - they currently have to untag the beta tag at each beta release, and re-tag. just use a branch, it's designed for this. then we can just git pull
2. suggestion: rename master to main (there's various articles explaining the reasoning and steps to do it. i'm sure your agent can do it easily). for now, i'll keep referring to master.
3. for those who may wonder, it seems that the beta3 release was abandoned after release (master is derived from v0.7.0-beta.2 and select fixes, not beta.3); but i notice both the release and the abandonment could be cleaner:

• don't forget to make the "selected fixes on top of beta" part of the beta line (right now they are only in master). my understanding from Tine Beta: a second, smaller Tine #617 is that beta should always run ahead of master, and not behind. beta tag still points to 00e7c6fc4906ec789b56b60dbcb64f4084c58648 - the beta3 release without those fixes). it would be cleaner to make some reverts to the beta line and/or cherry-pick only the good stuff from beta.3, skipping the bad stuff before merging to master. then both beta and master are up to date. going forward, it would also suggest to make a new release, e.g. beta.4, and doing a bit of testing, before merging back into master. I probably speak for all of us beta testers, we are happy to help test beta's, but now it seems that master is more bleeding edge than beta.
• general best practice: the diff between master and beta should be only some project/branch/CI metadata + commits that are temporarily not merged to master yet. right now there's a lot more.
• https://github.com/martinkoutecky/tine/releases shows a beta3 release; however there is no v0.7.0-beta.3 tag (in contrast to v0.7.0-beta.2 and v0.7.0-beta.1). each release should have a tag

4. my advice: try to only prepare/create releases on the corresponding branch (stable releases on master; beta releases on beta). i see that the 0.7.0 release was constructed in a 3rd "temporary" branch which branched off beta, before the merge into master. not a big deal, but would result in a cleaner history. e792416 seems to show something similar. maybe i'm missing something, but preparing and cutting a release should be very lightweight and not require another branch. any coding work should be done either in the beta/master branch directly, or in a branch for that feature; not in release branch like release/0.7;

hope this is helpful. HTH!

[martinkoutecky]

Thank you, Dieter. This is useful, and you were right that the process had drifted out of line with itself. Martin read it and approved the following changes:

1. Beta branch. It already exists: the og branch is the Beta line, and every Beta is built from it. We never documented that, sorry. To follow the latest Beta code, git pull on og. We will rename it to beta. First we have to move the in-app updater off the beta tag URL (releases/download/beta/latest.json), because installed Betas fetch updates from there. That tag is the only one we ever move, for that reason alone.
2. master → main. Not now. We are keeping master for the time being.
3. Beta ahead of stable, every release tagged. All work now lands on the Beta line first. Stable (master) takes only cherry-pick -x copies of fixes that reproduce there, so master's handful of fixes since 0.7.0 are already on the Beta line. The missing v0.7.0-beta.3 tag now exists (on 00e7c6fc4). From now on every Beta is tagged vX.Y.Z-beta.N when it is published. The next Beta, 0.8.0-beta.1, is being prepared and will bring the Beta line back ahead of stable.
4. Releases on their own line, no release branches. Agreed. Beta release commits go on the Beta line, and stable releases are cut on master: master is brought to a soaked Beta tag with one merge, then gets fixes only. We dropped the release/X.Y branch model we had planned.

We also deleted about 375 already-merged branches from the GitHub repo. From now on, a work branch is removed once it has merged.

Claude (working on Martin's behalf)

[Dieterbe]

some more things:
5. today, beta tag points to 00e7c6f, aka 0.7.0-beta.3; should this not point to the latest beta release, which seems to be v0.8.0-beta.1?
this seems to be a valid release already (it's listed on https://github.com/martinkoutecky/tine/releases#release-beta)
6. some tickets are closed with the label "fixed-in-beta", which is confusing, since og (branch) and beta (tag) point to different things. we already clarified that the og branch will be renamed to beta (very good decision), i think that means we can deprecate the tag, there should be no need for this tag since we'll just have the beta branch, and on there we can simply tag individual releases
7. avoid cherry-picking, definitely on master, and try to limit it on og/beta branch; only do it when needed, ideally only in temporary feature branches. Why? cherry-picking makes it unclear where a commit came from. When needing to bring in code (e.g. from og/beta to master), do it as a merge rather than a cherry-pick; it's then much clearer where the code came from, whether it has been included in beta releases, etc. If the reason for doing this thus far has been "we want to include some code, but not other code that has proven to be problematic", consider reverting commits in og/beta, prior to merging into master, to achieve what you want in a cleaner way

[martinkoutecky]

Thanks. (5) Good catch, and it's a real trap: on GitHub beta points at 0.8.0-beta.1, but git never moves a tag your clone already has, so a clone fetched before 10/13 still shows 0.7.0-beta.3 (git fetch --tags --force updates it). (6) Agreed, and this is a good reason to retire the moving tag: once the updater no longer reads releases/download/beta/latest.json, we'll drop it and keep only the vX.Y.Z-beta.N tags on the Beta branch. (7) Stable only receives cherry-pick -x copies, which record the source commit, of fixes that reproduce there. Merging Beta into stable would bring along larger unsoaked changes.

Claude (working on Martin's behalf)

[Dieterbe]

re 7; i see now what '-x' does.. still, this makes it a lot more cumbersome to figure out how any version in master relates to any version in the og branch (which i'll refer to as 'beta' below)
I understand you don't want the "larger unsoaked changes" from beta, but i think there are cleaner solutions to that; e.g. you could merge an older version of beta into master instead of the latest beta (e.g. you could use a 7 day cutoff); this way you avoid merging in code that's too new and untested. If there is older code in beta that you still don't want in master because it's known to be bad, than then code should probably be not in beta either and should be reverted in beta as well.

If you want, I can help with defining a more straightforward git versioning scheme based on industry best practices. But it's basically all of the above and no weird things like force pushes to public branches

[martinkoutecky]

Thanks Dieter, taking these in order.

5. The beta tag. It now points at v0.8.0-beta.1 (2edb0931a), and it moves to each new Beta release when it is published.

6. fixed-in-beta. The label means the fix is merged on the Beta line (og) and ships in the next Beta release. The issue is closed once that release is out. The tag exists only because installed Betas fetch updates from releases/download/beta/latest.json. Once the updater reads from somewhere else, the tag goes away and og becomes beta, as you suggested.

7. Cherry-picks. Stable releases are already cut with a merge: one merge commit brings master to a Beta tag that has soaked for at least five days with no open severe bug (0.8.0 will be the first cut done this way). Cherry-picks (-x) are used only for urgent fixes that ship on stable between those cuts, such as 0.7.3. A merge there would also bring every unsoaked Beta change. The next stable merge absorbs the copies, so the two lines meet again at every cut. We never force-push og or master.

I wrote all of this down in docs/VERSIONING.md. Could you read it and tell us whether anything there is unclear or still looks wrong to you?

— Claude (working on Martin's behalf)

[Dieterbe]

The beta tag is the one tag we move: it always points at the latest Beta release, because installed Betas fetch their updates from releases/download/beta/latest.json. Once the in-app updater reads from a different URL, the tag goes away

tags are assumed to be immutable. updating a tag like this is really weird and is bound to introduce ambiguities, stale references and confusion. Suggestion: query the releases and look for the latest pre-release. e.g. something like:

curl -s 'https://api.github.com/repos/martinkoutecky/tine/releases?per_page=100' |
  jq '[.[] | select(.prerelease and (.draft | not))]
      | max_by(.published_at)
      | {name, tag_name, published_at, html_url, body, assets}'

A stable release vX.Y.Z is cut by one merge commit that brings master to a Beta tag that has soaked for at least five days with no open severe bug. After the merge, master's tree equals that Beta tag, so the history shows exactly which Beta became which stable release.

"with no open severe bug" can't always be true I think, maybe rephrase to "with no open severe regressions compared to master" (because a severe bug could be present in both master and beta, and should not stop merging beta into master)

and "After the merge, master's tree equals that Beta tag" can't be true either I think. there is always some difference between the branches (e.g. app name, version details). (side note: when I verify this claim against past merges, there always seems to be a lot more code differences)

We cherry-pick here instead of merging because merging og would also bring every unsoaked change on the Beta line

you don't need to merge og, you could have the bugfix in a branch, and merge that branch into both master and into og/beta. That makes the lineage of fixes more clear.

fixed-in-beta means the fix is merged on the Beta line (og) and will ship in the next Beta release. The issue stays open until a release containing the fix is published, then it is closed with a link to that release.

this is actually nice.

[martinkoutecky]

Thanks Dieter — all four points land.

Moving tag. Agreed, tags should be immutable. We'll serve the Beta update manifest from a fixed address on tine.page instead of releases/download/beta/latest.json. Installed Betas still read the old URL, so beta moves one last time, to the first Beta that reads the new address, and is then frozen and later removed. Planned right after 0.8.0-beta.2.

"No open severe bug." You're right: a bug present in both lines shouldn't block a stable cut. VERSIONING.md will say "no open severe regression compared to stable".

"master's tree equals that Beta tag." Wrong as written, thanks for checking it against history. The lines differ by design in channel identity (app name, identifier, update URL). The doc will name that exact list of files, and the cut will check that nothing else differs.

Fix branches. Adopting this: a fix that also applies to stable starts from master, merges into the Beta line first, then into master. No more cherry-picks to stable. Thanks for the offer of help; please review the updated VERSIONING.md when it lands.

— Claude (working on Martin's behalf)

[Dieterbe]

please review the updated VERSIONING.md when it lands.

i'll re-review when some of the dust has settled. as-in: when all the discussed best-practices should be in action and when we can clean the legacy stuff out of the VERSIONING.md file

[Dieterbe]

We'll serve the Beta update manifest from a fixed address on tine.page instead of releases/download/beta/latest.json

Any particular reason you decided against using the github api to look for the latest pre-release (see the example i posted above)? This seemed elegant to me, because you can mark beta's as "pre-release"; GitHub has native support for this. Although I suppose there's an advantage to decoupling from GitHub, in case we want to switch to another platform later.

My agent had a comment about the new update system:

### High — Beta AppImage zsync updates are not cryptographically authenticated

Beta.3 moves embedded AppImage update metadata to mutable tine.page zsync URLs in release-policy.mjs (scripts/release-policy.mjs:43). The Pages workflow copies zsync control files to that location in pages-beta-manifest.mjs (scripts/pages-beta-manifest.mjs:103).

The app’s normal Tauri updater still verifies minisign signatures, which is good. But the separate AppImage zsync mechanism is not tied to that key, and this repository does not build or enforce validated AppImage signatures. A party able to alter the Pages-served zsync file/content could cause an external AppImage updater to replace the application with attacker-controlled code.

AppImage’s own documentation describes zsync integrity verification separately from signing, and does not make signature validation an inherent guarantee.

Recommendation: disable the embedded beta zsync route, or make it an authenticated release channel with an enforced signature-verification gate. The existing signed Tauri updater is the safer update mechanism.

[Dieterbe]

8. typically, when a change is introduced in a project that fixes an issue, the commit mentions fix #<issue num> in the message, such that it shows up in the respective issue thread. As a viewer/follower it's then easier to see when looking at an issue, what the committed fix is, what the added tests are, etc. Tine currently doesn't do this. Please start doing this. If it's a commit straight to the beta/master branch, than it goes into that commit, if it's a commit that goes into a feature branch which is then merged into beta/master, add the note to the merge commit please. thanks.

[martinkoutecky]

Agreed. From now on every commit that fixes an issue, and the merge commit that brings a branch into Beta or stable, cites it as GH #N, so it shows up in the issue thread. We use a mention and not fixes #N, because a closing keyword closes the issue as soon as the fix reaches stable, before we post the release note with the version and confidence. Commits from earlier than today are inconsistent about this; we won't rewrite them. The rule is now in VERSIONING.md.

Claude (working on Martin's behalf)