Proposal: branching & release flow for stable vs. beta

[Luca-Timo]

Problem

main (stable) and beta are fed off the same line, so a bugfix can't reach stable users without dragging along every half-finished beta feature. Fixes end up hostage to features.

Concretely: I noticed main (stable) is ~3 weeks old with no bugfix shipped, while beta has moved well ahead. I think the flow below would let us solve exactly this — ship fixes to stable quickly while features keep landing on beta.

As far as I see, without really more work for you @the-luap as project owner.

Proposed model — dual-track

bugfix/* ──▶ main ──▶ (forward-merge) ──▶ beta
feature/* ─────────────────────────────▶ beta ──▶ main (promote when stable)

• All changes go through bugfix/* or feature/* branches (PR + CI + review, no direct commits to main/beta).
• Bugfix: merge to main after testing, then forward-merge main → beta so the fix lives on one timeline.
• Feature: merge to beta only.
• Promote beta → main occasionally, once its features are considered stable. Because main is always merged forward into beta, beta stays a superset of main and promotions stay near-conflict-free.

Three rules that make it work

1. Forward-merge fixes (main → beta right after a fix lands) — keeps main an ancestor of beta, so promotions don't conflict.
2. Feature flags as insurance, not the gate — big/risky features land behind a default-off backend flag, so they can be promoted "code-complete but off," enabled per-instance later, and killed instantly if needed (the new Live Slideshow already works this way). Optional, not mandatory for every change.
3. Timestamp migration IDs — switch new migrations from sequential NNN_ to a timestamp prefix (YYYYMMDDHHMM_*.js). The shared counter is the one thing that collides under parallel branches; timestamps are unique per branch and sort after the legacy NNN_ files (~1-line change to the migration runner's filename filter; history untouched). Keep migrations additive / addColumnIfNotExists-guarded so interleave order never matters.

What this changes

• A short RELEASING.md documenting the flow + a checklist ("feature → flag, default-off, safe-when-off; migration → additive/timestamped").
• One small change to run-migrations-safe.js to accept timestamp IDs.
• release-please keeps cutting versions; main just gets patch releases between feature promotions.

Open questions

• Comfortable making main direct-merge for fixes, or should fixes also soak on beta first?
• Promote beta → main on a fixed cadence, or "when it's ready"?
• OK to flip new migrations to timestamp IDs going forward?

[the-luap]

yes, that would be an option. What I was thinking of is to move the beta release channel to main while creating a new stable branch and then have at least a weekly main to beta for all the bug fixes.

I also thinking of moving this project to an organization

[Luca-Timo]

Want to make sure I got your idea right: main becomes the rolling dev line (what beta is now), and a new stable branch holds the released version, with a weekly merge down to it for the bugfixes. Is that the gist? (Only thing I wasn't sure on was the "main to beta" part — whether you'd keep a separate beta tier, or if that's just the stable branch.)

That's close to what I was thinking, just cleaner — I had fixes going straight to main and features promoted up, but a single dev line promoting down on a cadence is simpler and fewer branches to babysit.

One thing I'm not totally sure about with the weekly main → stable: it means unreleased feature code (and any new migrations) ride down into stable behind the flags. That's fine for new stuff that's properly gated, but two cases give me pause — (1) the dark code still sits in the stable release (bigger surface to audit, and only safe as long as every flag is a real backend deny), and (2) a larger rewrite of something already live can't really hide behind a flag, so it'd hit stable the moment it's on main. Curious how you'd want to handle those? Might be a non-issue, just wanted to raise it.

And like I mentioned above re the 137_* collision between #646 and #649 — would it be worth moving new migrations to a timestamp-style name (YYYYMMDDHHMM_...) instead of the sequential numbers? Then two parallel PRs could never grab the same id and there'd be no renumbering/coordination. Happy to take a stab at it if you think it makes sense.

[Luca-Timo]

One thought on the organization, also a good idea, especially for future additions outside of core functionality, e.g. PicPeak App / desktop tool, to change settings offline then sync when network is available again. Scan incoming bills, expenses can be added directly from the phone. Contracts could be better signed via Apple / S Pen on a Tablet, by both parties face to face.

Please make sure that you remain the soal reviewer / merging authority for the moment (at least for classic PicPeak, not app :)

[the-luap]

right, that is what I meant to first have main which is always latest build but with beta content and then a stable build. right the weekly must be just for bug fixes and no new feature so we would need to be careful to split PRs and create bug PRs as small as possible to merge it to both branches.

for migrating, yes will stay the same. Probably I will do it next weekend and I still have a fear that some items like the docker image link will not work after migration, so there could be pain for users on migrating as well, not sure how good github is handling those redirects.

[Luca-Timo]

@the-luap you would like to cherrypick the pr's which go to stable? this was the idea of splitting the commit branches to bugfix and feature, so there would ideally be no manual cherrypicking

I would also be happy to discuss on the phone