Skip to content

Latest commit

 

History

History
235 lines (169 loc) · 33.4 KB

releasing.md

File metadata and controls

235 lines (169 loc) · 33.4 KB

Releasing

.github/workflows/release-linux.yml publishes a release or a beta. This page is what a maintainer does around it. ADR 0018 says why the channels are a Launchpad PPA and a COPR project, and ADR 0041 why betas have their own, why every other distribution gets a Flatpak repository of ours, and what every GitHub release carries.

Setup before the first release

A repository admin does these once. The workflow's header names the same secrets and variables.

  1. The signing key, on a machine you trust, kept for uploads only. Launchpad confirms a key by mail encrypted to it, so it needs an encryption subkey too:

    gpg --batch --passphrase '' --quick-generate-key 'TablePro Releases <hello@tablepro.app>' rsa4096 sign never
    gpg --list-secret-keys --with-colons 'TablePro Releases' | awk -F: '$1 == "fpr" { print $10; exit }'
    gpg --batch --passphrase '' --quick-add-key <fingerprint> rsa4096 encr never
    gpg --keyserver hkps://keyserver.ubuntu.com --send-keys <fingerprint>
    gpg --armor --export-secret-keys <fingerprint> > linux-ppa-signing-key.asc
  2. Launchpad, signed in as the maintainer whose account will hold the key:

    1. Add the fingerprint at OpenPGP keys and open the link in the encrypted mail Launchpad sends. Launchpad mails a failed build to the owner of the key that signed the upload, so that account's mail has to reach someone.
    2. Register a team named tablepro, with that account a member.
    3. On the team's page, Create a new PPA twice: URL tablepro, display name TablePro, and URL tablepro-beta, display name TablePro beta. In the beta one's description, tell testers to add ppa:tablepro/tablepro as well.
    4. On each PPA, Edit PPA dependencies: add ~rust-toolchain/ubuntu/staging. Change details: under Processors, amd64 and arm64, and turn on Build debug symbols and Publish debug symbols.
  3. COPR:

    1. A COPR group is a Fedora Accounts group, which only Fedora Infrastructure creates: open a ticket asking for the group tablepro, then add the maintainers at Fedora Accounts.

    2. Sign out of COPR and in again, so it reads the group, and choose Activate this group on My groups.

    3. With copr-cli and the API token from COPR's API page in ~/.config/copr, from the repository root:

      for project in tablepro tablepro-beta; do
          copr-cli create "@tablepro/$project" \
              --chroot fedora-44-x86_64 --chroot fedora-44-aarch64 \
              --chroot fedora-45-x86_64 --chroot fedora-45-aarch64 \
              --follow-fedora-branching on --appstream on
          copr-cli add-package-custom "@tablepro/$project" --name tablepro --webhook-rebuild on --timeout 36000 \
              --script linux/build-aux/rpm/copr-sources.sh --script-builddeps 'curl rpmdevtools'
          for chroot in fedora-44-x86_64 fedora-44-aarch64 fedora-45-x86_64 fedora-45-aarch64; do
              copr-cli edit-chroot "@tablepro/$project/$chroot" --rpmbuild-without check
          done
      done

      COPR builds without %check: the release dry run already runs it with this spec on the same Fedora versions and architectures. A chroot that Fedora branching adds needs the same edit-chroot.

    4. In each project's Settings, tell tablepro-beta's users under Instructions to enable @tablepro/tablepro as well, and turn on build failure emails for the admins. Integrations shows the custom webhook URL; add the package name to it: https://copr.fedorainfracloud.org/webhooks/custom/<id>/<uuid>/tablepro/.

  4. The Flatpak repository, in the Cloudflare account that holds the tablepro.app zone:

    1. R2: under R2 Object Storage, create the bucket tablepro-flatpak. Leave its r2.dev public URL off.

    2. The domain: in the bucket's Settings, under Custom Domains, connect flatpak.tablepro.app. Cloudflare adds the DNS record. The release job uploads repo/ and beta-repo/ there.

    3. The token: under R2, Manage API tokens, create a token with Object Read & Write on tablepro-flatpak only. Keep its Access Key ID, its Secret Access Key and the S3 endpoint it shows, https://<account id>.r2.cloudflarestorage.com.

    4. The key: a key of its own, not the PPA's. Every installed remote trusts it, and a new one makes every user add the repository again, so keep a copy offline:

      gpg --batch --passphrase '' --quick-generate-key 'TablePro Flatpak <hello@tablepro.app>' rsa4096 sign never
      gpg --list-secret-keys --with-colons 'TablePro Flatpak' | awk -F: '$1 == "fpr" { print $10; exit }'
      gpg --armor --export-secret-keys <fingerprint> > linux-flatpak-key.asc
  5. GitHub: the linux-release environment takes a required reviewer and deploys from linux-v* tags and the main branch only. The branch is for a packaging fix.

    • Secrets in it: LINUX_PPA_SIGNING_KEY, the file the first step exported; LINUX_COPR_WEBHOOK, the URL of @tablepro/tablepro; LINUX_COPR_WEBHOOK_BETA, the URL of @tablepro/tablepro-beta; LINUX_FLATPAK_GPG_KEY, the Flatpak key's file; LINUX_FLATPAK_R2_ACCESS_KEY_ID and LINUX_FLATPAK_R2_SECRET_ACCESS_KEY, the R2 token's. Then delete the exported key files.
    • Repository variables: LINUX_PPA set to tablepro/tablepro, LINUX_PPA_BETA set to tablepro/tablepro-beta, LINUX_FLATPAK_R2_ENDPOINT set to the S3 endpoint, POSTHOG_PROJECT_KEY set to the project API key (phc_...) of the one PostHog project, which the macOS release builds with too. It is public by design, so a variable, not a secret; the .deb, the .rpm and the Flatpak send usage data to it unless the user turns it off (ADR 0039), and a release fails without it. LINUX_BRANCH stays unset unless a release comes from a maintenance branch.
    gh secret set LINUX_PPA_SIGNING_KEY --env linux-release --repo TableProApp/TablePro < linux-ppa-signing-key.asc
    gh secret set LINUX_COPR_WEBHOOK --env linux-release --repo TableProApp/TablePro
    gh secret set LINUX_COPR_WEBHOOK_BETA --env linux-release --repo TableProApp/TablePro
    gh secret set LINUX_FLATPAK_GPG_KEY --env linux-release --repo TableProApp/TablePro < linux-flatpak-key.asc
    gh secret set LINUX_FLATPAK_R2_ACCESS_KEY_ID --env linux-release --repo TableProApp/TablePro
    gh secret set LINUX_FLATPAK_R2_SECRET_ACCESS_KEY --env linux-release --repo TableProApp/TablePro
    gh variable set LINUX_PPA --body tablepro/tablepro --repo TableProApp/TablePro
    gh variable set LINUX_PPA_BETA --body tablepro/tablepro-beta --repo TableProApp/TablePro
    gh variable set LINUX_FLATPAK_R2_ENDPOINT --body 'https://<account id>.r2.cloudflarestorage.com' --repo TableProApp/TablePro
    gh variable set POSTHOG_PROJECT_KEY --repo TableProApp/TablePro

Until these exist, a tag still builds and checks everything, and each publishing step that lacks its secret or variable fails and publishes nothing.

README.md gives users these PPAs, COPR projects and Flatpak repositories; change it if one gets another name.

A dry run

Before a tag, run the workflow by hand on the release commit, from the branch while it is still at that commit:

gh workflow run release-linux.yml --ref main -f dry-run=true

It checks the version's metadata as the release-metadata test does, and builds, tests and installs both packages and the Flatpak on amd64 and arm64. It signs the Flatpak with a throwaway key into both repositories, served on 127.0.0.1, and on Ubuntu 22.04, 24.04 and 26.04 installs it from there and from a bundle, updates both, and switches between the release and the beta. It keeps every file a tag would publish, SHA256SUMS among them, as the run's linux-release artifact, checked against build-aux/packaging/release-matrix.json. It publishes nothing and needs no reviewer. A new Ubuntu series or Fedora release joins that file, and CI builds it from then on.

The tag publishes what this run built and tested, and builds none of it again (ADR 0043). It takes the newest green dry run of the tag's commit, while that run's artifacts last, the retention-days the workflow sets on them. A dry run made green by rerunning failed jobs counts. The run then keeps the failed attempt's artifacts too, and the tag takes the newest of each name, so never delete a dry run's artifacts by hand: deleting the passing attempt's would bring back the failed attempt's, and nothing but the dry run's own tests checks the unsigned Flatpak. Deleting artifacts needs Actions write, which only maintainers hold. When the tag's run finds no green dry run, because the branch had moved past the release commit or its artifacts expired, it fails and publishes nothing: run the dry run on the tag, --ref linux-vX.Y.Z, then rerun the tag's run as its error says.

Source archives

build-aux/packaging/make-sources.sh calls make-dist.sh for the source archive and builds the vendor archive. make-dist.sh uses git archive on committed workspace, core and Linux files. It refuses uncommitted changes to those inputs. Core ADR 0001, Decision is the current archive design; the meson dist text in older Linux ADRs is historical. The workflow builds and tests these archives through the package jobs. That is not Meson's automatic dist test.

A release or a beta

linux-vX.Y.Z is a release and linux-vX.Y.Z-beta.N a beta; the workflow refuses any other tag. Packages and the metainfo spell a beta X.Y.Z~beta.N, which sorts below X.Y.Z in dpkg, RPM and AppStream, while the tag and meson.build keep the hyphen, since git refuses a tilde.

  1. The release commit, a pull request titled chore(release): linux-vX.Y.Z or chore(release): linux-vX.Y.Z-beta.N, sets one version and one date (UTC) everywhere:

    • version in meson.build: X.Y.Z or X.Y.Z-beta.N.
    • A new first <release> in data/app.tablepro.TablePro.metainfo.xml.in.in, with the date, a <url type="details"> to https://github.com/TableProApp/TablePro/releases/tag/ and the tag, and a short description. A release's is version="X.Y.Z". A beta's is version="X.Y.Z~beta.N" with type="development". A release's entry goes above its betas', which stay.
    • Version (X.Y.Z or X.Y.Z~beta.N), Release: 1%{?dist} and a new first %changelog entry in build-aux/rpm/tablepro.spec, with the same date.
    • A release only: the version's section in CHANGELOG.md, from the fragments in changelog.d/. From the repository root, with the towncrier venv of the root RELEASING.md, Notes: .venv/bin/towncrier build --dir linux --version X.Y.Z --date YYYY-MM-DD --yes. It deletes the fragments and stages CHANGELOG.md. An X.Y.0 types its lead under the heading, at most 6 plain lines naming what a reader would change their behavior over. A beta adds no section and keeps the fragments, so the release lists them; its notes are a towncrier draft of the fragments at the tag.
    • The .TH line of data/tablepro.1: the date and TablePro with the version as meson.build has it.

    The pull request changes only these files and changelog.d/. The release-metadata Meson test checks that they agree from the commit that sets a beta's version, or adds a release's changelog heading, so the pull request fails before the tag does. Pull request CI does not block an untranslated string, while the dry run's Translation template job does: check the shipped catalogues against the template before opening the pull request. Merge it on the date it sets, in UTC; the dry run takes about four and a half hours, so a date of tomorrow means merging after midnight UTC.

  2. The tag: linux-vX.Y.Z or linux-vX.Y.Z-beta.N on the merged commit, after its green dry run, pushed the same UTC day. The workflow compares the metainfo date with the committer date of the tagged commit; when the release commit landed a day early, tag a later commit on main from the right day instead, after its own dry run. Tags run one at a time, and a tag pushed while another waits cancels that one, so push a tag when no other release run is waiting.

  3. The workflow checks the tag and takes the tarballs, template, source packages, packages and unsigned Flatpak repositories from the dry run of its commit, or fails before it publishes anything when there is none. It pulls the published Flatpak repository from R2, signs the new commits into it and bundles them, and checks that every file but the bundles matches the dry run's SHA256SUMS. It attests every file, publishes the packages and bundles on GitHub with the tarballs, the translation template tablepro.pot, SHA256SUMS, and the version's changelog section as notes, a beta as a pre-release, and checks what the release then serves against SHA256SUMS. Then it uploads the Flatpak repository to R2, the signed source package to the PPA, and posts the tag to the COPR project: the stable ones for a release, the beta ones for a beta. A reviewer approves each step that uses the environment.

  4. Afterwards: watch the Launchpad build page of each series and the COPR build the workflow prints. A failed build there does not fail the workflow. flatpak remote-info on the TablePro remote shows the new Flatpak commit.

Installed-bundle smoke pass

Before announcing a beta, run this on normal GNOME and Plasma desktop sessions with the installed release-profile bundle. The container smoke test is not this pass. Use test databases and test credentials. Record the tag, bundle checksum, architecture, distribution, desktop version, session type, Flatpak version and portal backends in the release PR. Record each result and any issue link for both desktops; leave an unrun check open.

  • Install the bundle, launch it from the app menu and check About's version. Record its origin, branch and commit from flatpak info app.tablepro.TablePro//beta.
  • Save a database password, quit and relaunch, then reconnect without re-entering it. Lock the keyring and dismiss its prompt once; retry and unlock it. Repeat for the MCP token and an AI key if those features are used.
  • Open a local SQLite or DuckDB file with the chooser. Run a query and export rows to a chosen folder. Confirm the exported file exists and opens on the host.
  • Open About's help link in the default browser. Complete an export with the window in the background and check its notification and return to the app.
  • Connect to a network database and a local database. Check a local socket where supported, and an SSH tunnel through the host agent. Run a read and a test write, then reconnect.
  • In a disposable desktop session with a required portal backend absent, check the error and recover using Flatpak connections. Restore the backend and repeat the affected secret, chooser or link flow. Record the missing interface and recovery result. Do not disable host security controls to make a check pass.
  • If an earlier beta exists, update it through its origin and repeat launch and secret reload. If a stable branch exists, switch to it and back using README, Betas. Check saved connections and drafts after each switch. Record unavailable earlier versions as not applicable, with the reason.

For a replacement beta, also record the old and new versions and the result of the user recovery path below. A failed or unrun check remains a release gate.

A partial publish

GitHub publishes before the Flatpak repository, PPA upload and COPR trigger. Those jobs can finish independently. Launchpad and COPR then build outside Actions, so a green workflow alone does not prove availability.

  1. Pause announcements, promotion and further tags. Save the run URL and logs. Inspect all four destinations before retrying anything, including after a timeout.

  2. Record this table in the release PR, with links and results for every series and architecture in build-aux/packaging/release-matrix.json:

    Destination Check
    GitHub Release exists; all expected assets download and match SHA256SUMS and their attestations
    Flatpak Public beta repository resolves both app architectures and their debug refs; install and update reach the expected signed commits
    PPA Upload accepted for each series; both architectures built and are available to apt
    COPR Trigger returned a build ID; each target built and is available to dnf
  3. Read the failure before retrying. If a destination accepted nothing and the fault was temporary, retry only that failed publishing job. If GitHub created the release before its download check failed, verify the existing assets instead of rerunning gh release create. The job has no resume mode for an existing release; publish beta.N+1 if its failure left downstream jobs blocked. Do not rerun the whole workflow or replace uploaded assets.

  4. For an interrupted Flatpak upload, keep the objects already uploaded. Resume the publisher with the same signed repository artifact only if no newer release has published. Its object-before-summary order and final pruning are in build-aux/packaging/flatpak-publish.sh. Check the public repository with a fresh install and an update afterwards.

  5. For a PPA upload or COPR trigger that may have succeeded, inspect the builder first. Retry a failed external build through that service only when its source is unchanged and the failure was temporary. Never blindly resend all source uploads or the webhook. When Launchpad accepted some series and refused another before taking a file, send only the refused one: download the run's linux-source-package artifact, debsign that series' _source.changes with the PPA key and dput it alone, as the ppa job does. Rerunning the job sends the accepted series again, which Launchpad rejects by email. If packaging or source must change, or the accepted state cannot be established, publish beta.N+1 through the normal release steps. The stable-only packaging fix dispatch cannot repair a beta.

  6. Resume announcements only after all destinations pass and the installed-bundle smoke pass is recorded. If the beta itself is bad, withdraw it below instead of completing its publication.

Withdraw a bad beta

There is no Linux withdrawal workflow. .github/workflows/withdraw.yml edits macOS Sparkle and plugin feeds only; do not dispatch it for a Linux tag.

  1. Stop announcements and promotion. Cancel pending publication of the bad beta and pause further release approvals while its state is checked. Record every destination already reached using A partial publish.
  2. Mark the GitHub release title WITHDRAWN: linux-vX.Y.Z-beta.N. Prepend notes that name the fault, affected installs and the recovery path. Keep its tag, assets, checksums and attestations unchanged. Do not move the tag or upload different bytes under the same version.
  3. In Launchpad, delete the affected beta source version from the beta PPA and cancel its pending builds. In COPR, cancel pending builds and remove the affected build's published results from the beta project. Check repository metadata after removal. These actions do not remove a package already installed or cached by a user.
  4. If the bad commit reached the Flatpak beta repository, temporarily block public access to beta-repo/ at its hosting layer while preparing the replacement. Preserve the R2 objects and signed repository history; leave repo/ alone. Check that the public endpoint no longer serves the bad ref, including through caches. Do not edit signed summaries by hand. Installed copies and downloaded bundles still exist, so the withdrawal notice must tell users to stop using them.
  5. Fix the cause in a PR and publish beta.N+1, following A release or a beta. For Flatpak, keep public access paused until the replacement repository is fully uploaded and checked, then restore access and test a public update. Do not announce it until all four destinations are verified.
  6. Test recovery from the withdrawn beta on saved test state. Link the results and replacement release from the withdrawal notice. If no safe build is available yet, tell users to quit TablePro and wait; do not promise a downgrade can read newer state.

User recovery

Tell users to quit TablePro and copy its files before changing versions. A format-upgrade copy covers app state, not changes made to a server database.

Prefer the corrected beta through the same install source in README, Install. Repository users update with apt, dnf or Flatpak; users of a GitHub .deb or .rpm download the corrected file. Confirm About shows the replacement version before resuming work.

If the notice offers an earlier tested version, link its exact release and package instructions. Disabling a beta PPA or COPR project does not uninstall or downgrade its package. Switching Flatpak branches does not restore older data. Follow After a downgrade for newer-format refusals and restoration, keeping the newer files aside. The maintainer must test that path with the affected versions before recommending it.

A future Flathub submission

ADR 0041, Context amends the older permission-policy history in ADRs 0008 and 0018. Passing the linter is not permission approval. A maintainer writes the manifest and submission by hand, discloses AI-assisted material as required, and obtains Flathub's permission review under its current requirements. A new app enters stable before it can use Flathub beta.

The app's own files also need a maintainer before the submission:

  • Translations. The AI disclosure names each catalogue in po/LINGUAS that an agent translated (Requirements, Generative AI policy). The Localisation policy's bar on machine-generated translations is about the English localisation.
  • Screenshots. Retake any whose window changed since data/screenshots was taken (MetaInfo guidelines, Quality guidelines, Screenshots, Up to date; README.md).
  • Licensing. The metainfo description's last paragraph states what a license gives and when the app asks for one. A change to either changes it in the same release (Requirements, Monetisation policy).
  • Verification. Flathub verifies the app through tablepro.app once it is listed (Quality guidelines, Managed by app author).

Our existing installs keep their TablePro origin. Adding Flathub or changing the default branch does not migrate that origin. Before offering migration instructions, test an explicit origin change from both our stable and beta installs to the accepted Flathub app. Record the commands and before/after origin, branch and commit from flatpak info. Verify updates come from Flathub, secrets still load, saved work survives and rollback works. Keep our repository available until that tested migration is published. Do not promise automatic migration.

Release criteria

What has to hold before 0.1.0, for a user on GNOME 50 with Ubuntu 26.04 or Fedora 44, and where each stands on 2026-11-08:

beta.3 passed all seven items of the installed-bundle smoke pass on Fedora 44 GNOME 50.6 and Fedora 44 KDE Plasma 6.8.2. The record on #4089 includes the beta.1 to beta.3 Flatpak update on both desktops and the known issues. This does not close the manual accessibility pass or the week of daily use below.

# The user Holds today Still needed
1 Installs tablepro from the PPA or the COPR project, and gets updates from the system's updater beta.3 is published in the beta PPA for Ubuntu 26.04 and 26.10, amd64 and arm64, and the beta COPR project for Fedora 44 and 45, x86_64 and aarch64. Fresh installs from both repositories passed in containers on both architectures. On 2026-11-08, beta.1 upgraded to beta.3 with apt upgrade from the PPA in Ubuntu 26.04 arm64 and with dnf upgrade from COPR in Fedora 44 aarch64, and both started Nothing
2 Connects to their everyday PostgreSQL, MySQL, MariaDB, SQL Server, ClickHouse, Cassandra, ScyllaDB or SQLite database The supported releases and why others are out, in the README's supported servers. CI runs every driver's Docker suite on each tested release, MySQL 8.0 and SQL Server 2017 and 2019 among them Nothing
3 Browses tables of real-world data (dates, decimals, JSON, UUIDs, NULLs) and sees correct values Per-engine decoding with the type fallback and unsupported-type conformance cases (ADR 0014). A value corpus on every engine, MariaDB too: dates and times at their extremes and in other zones, decimals, JSON, UUIDs, Unicode and binary values, read back through a table tab, Export All and an editor run, and exported as CSV and SQL INSERT and loaded back into an empty copy Nothing
4 Runs typical queries against tables of a million rows or more without running out of memory or freezing The 10,000-row editor limit with Export All, and driver tests over 2,000,000 rows. Pages seek past the edge row's key, or walk PostgreSQL heap block windows for a table with no key; OFFSET only under a user sort, a restored deep offset or a partitioned keyless table. Docker tests page 60k and 25k-row tables both ways and check the plan. A 1,000,000-row table is paged to its end and exported on PostgreSQL, MySQL, MariaDB, SQL Server, ClickHouse, Cassandra, ScyllaDB, SQLite and DuckDB, with bounds on time and on resident peak growth. The file engines' cases run in the cargo suite, each in a test binary of its own, so the peak is its alone Nothing
5 Edits data in place, and the changes commit correctly even when the connection or the app misbehaves Write, row guard and commit resolution conformance on every engine, with the fault fakes and the grid save Docker test. kill_during_save kills TablePro halfway through a SQLite save: the file keeps none of it, and the next launch restores the session with its history, settings and saved tabs. A save into a SQLite file another program holds locked fails as Busy(FileLocked), which says another program or an editor tab holds the file's lock, and leaves the file as it was whether the lock shows at BEGIN IMMEDIATE or at the COMMIT Nothing
6 Trusts the app with credentials: TLS, SSH tunnels, no password in plain text Each engine's own client TLS default, Verify full one choice away, the TLS conformance suite, the Secret Service, and statement logging silenced Nothing. In place of an outside review, a security review by a model other than the one that wrote the code covered every Linux and core surface in .oss-scanner/threat_model.md on the release candidate before 0.1.0-beta.1, and its confirmed findings are fixed
7 Recovers when the network drops or the database restarts Health monitoring, backoff and replay rules with their tests, a stopped container in the liveness tests, and a session test that restarts PostgreSQL: the read in flight runs again, the save in flight does not and leaves no row Nothing
8 Works with a screen reader, the keyboard alone and larger text Label audits of the picker, the connect pages, the workspace, the connect dialog and preferences, labelled cells and real-key tests. Sorting from the cell menu, named filter fields and cell editors, focus handed on when a control hides, and announced query results and errors. Columns move and resize from the keyboard, and a column sized by a key or a header drag draws at that width, also when it comes back. The ER diagram's tables are focusable list items that name their columns and joins R-10 in the roadmap
9 Sees no message that cannot be translated, even while only English ships Every string the app writes is in the template. Core errors carry values the app words itself: CSV import, cell and JSON parsing, type and default syntax, the keyring, certificate files, unsupported features, the SSH host, username and jump host checks, a failed write of the saved connections, the SSH runtime directory checks, ssh's exit status, and an ssh that would not start. A panic, an export encoder failure, an SSH failure with no sentence of its own and a TLS failure the app does not classify show the app's words and log the detail Nothing
10 Uses the app daily for a week without an unrecoverable failure Nothing yet A dated week of daily use
11 Works with a database of many schemas or tables, such as one schema per tenant, without the sidebar or completion freezing The large-catalog case on PostgreSQL with 100 schemas of 500 tables and MySQL with one database of 50,000: the sidebar's first listing, its search a key at a time, and completion after FROM , a key typed into it and after a schema's dot each have a time bound, none may stall the main loop past 100 ms, and the catalog has a bound on resident peak growth (testing.md) Nothing

The first release

main carries 0.1.0 from before any tag: a metainfo <release> and a spec %changelog entry for it, and the fragments of every change on the way.

  • Placeholders. The first beta's release commit replaces the metainfo's 0.1.0 entry and the spec's 0.1.0-1 entry with its own: the beta's entries come first, and 0.1.0 listed below its beta fails appstreamcli validate. 0.1.0's release commit adds its entries back above the betas'.

  • Notes. The fragments from before the first beta record work on builds nobody installed. The first beta's release commit curates changelog.d/ as a release pull request does (apple/RELEASING.md, Cutting a stable or patch, step 4), so that beta's notes and 0.1.0's describe the app:

    • git rm every fixed, changed, deprecated, removed and security fragment, since no Linux release had what they change. The +ghsa-* security fragments mirror advisories that list only the macOS and iOS apps as affected, so there is nothing to list under Security (SECURITY.md).
    • Keep each added fragment that names something the app does, and git rm one a later fragment replaces.

    Fragments after the first beta are news to testers and go into 0.1.0's section as usual. 0.1.0 types its lead like any X.Y.0, and its notes tell testers who added only the beta repository to add the stable one (README.md).

A packaging fix

A fix to build-aux/debian or build-aux/rpm that needs no new version, such as a missing dependency. It goes to the stable repositories only; a beta's fix is the next beta. The Flatpak's packaging is its manifest, and a fix to it waits for the next release.

PPA. Merge the fix to main, then run the workflow by hand on main:

gh workflow run release-linux.yml --ref main -f tag=linux-v0.1.0 -f revision=2

It downloads that release's two tarballs, checks them against its SHA256SUMS, builds the source package with the packaging from main as 0.1.0-0ppa2~YY.MM, builds and tests the .deb on both architectures, and uploads it to the stable PPA once a reviewer approves. Launchpad accepts the release's own orig tarballs again, and would refuse new ones whose bytes differ. The vendor tarball brings the release's PostHog key with it. Count the revision up for each further upload of the same version. The release's GitHub assets stay as they were.

COPR. COPR builds the spec at the tag, so a fix to it goes in by hand. Raise Release in build-aux/rpm/tablepro.spec on main with a %changelog entry, then, on Fedora with copr-cli signed in, build the source RPM from that spec and submit it:

spectool --get-files --sources build-aux/rpm/tablepro.spec
rpmbuild -bs --define "_sourcedir $PWD" --define "_srcrpmdir $PWD" build-aux/rpm/tablepro.spec
copr-cli build @tablepro/tablepro tablepro-0.1.0-2.*.src.rpm

The next version's release commit sets Release back to 1.

A fix release

0.1.1 is a release like any other, from main. When main already holds work that should wait for 0.2.0, branch linux-0.1 from the linux-v0.1.0 tag, cherry-pick the fixes onto it with their fragments, and open the release pull request into linux-0.1, so towncrier builds the section from those fragments only. Set LINUX_BRANCH to linux-0.1 and allow that branch in the environment, push the tag, then set both back. Afterwards cherry-pick the release commit onto main in a pull request with the same title: it brings the version, the dates and the section, and deletes the fragments 0.1.1 shipped.

Downgrades

A build refuses a file in a storage format newer than its own and never writes over it; a file in a format it knows it reads and writes, whichever release wrote it. Before the first write in a newer format, a build keeps a copy of the older file beside it (storage.md). troubleshooting.md tells users what they see and how to put a copy back.