Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions .claude/rules/ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,26 +16,26 @@ paths:

## Required checks

- main requires `CI`, the last job of `ci.yml`, and merges through GitHub's merge queue, which builds up to five pull requests at once, each on top of those ahead of it, and squashes. Strict is off. Admins can bypass in pull_request mode.
- main requires `CI`, the last job of `ci.yml`. There is no merge queue and strict is off: a pull request squash-merges on its own green run, and the main push tests what changed again. Admins can bypass in pull_request mode.
- `release/*` requires `CI` and `PR title` (ruleset 25435242). `release/0.82` was cut before `ci.yml`: it keeps its own workflow files and the old per-workflow checks (ruleset 23957966).
- `PR title` (`pr-title.yml`) is advisory on main: the reviewer reads the squash subject. It also runs the changelog check, since a title edit starts no CI run; on main the merge group's Lint job runs it again with the current title.
- `PR title` (`pr-title.yml`) is advisory on main: the reviewer reads the squash subject. It also runs the changelog check, since a title edit starts no CI run.
- `CI` fails when a job it needs failed or was cancelled, or when the plan selected a job that did not succeed. A job the plan left out is skipped, which passes.
- Tags never move (ruleset 25308039, no bypass). Only admins create `release/*` and the `v*`, `ios-v*`, `linux-v*`, `windows-v*`, `libs-*` and `plugin-*` tags.

## Reading a red check

- Open the CI run and read the red job under it. `CI` only lists the results.
- PR CI tests the merge with main as of the trigger. After main is fixed, merge main in instead of re-running.
- A merge group runs `CI` again on the squash of the pull request onto main; a red one drops the pull request from the queue.
- Artifacts, annotations and summaries: `.claude/skills/fix-issue/references/verification-apple.md`, Reading CI.

## What runs where

- `ci.yml` runs on every PR, every merge group, pushes to main and `release/**`, and by dispatch. `Plan` runs the detector per suite, then calls each workflow when its suite is true: `ci-lint.yml` (always; SwiftLint with `swiftlint`, the HANA helper with `hana`), `macos-tests.yml` (`macos`, plugins with `plugins`), `ios-tests.yml` (`ios`, TableProOracle with `oracle`), `build-linux.yml` (`linux-docs`, docs job only unless `linux`; `linux-deps` adds the minimum Rust version, the aarch64 Flatpak and the advisory database), `linux-packages.yml` (`packages`, x86_64), `core.yml` (`core`) and `windows.yml` (`windows`).
- `ci.yml` runs on every PR, pushes to main and `release/**`, and by dispatch. `Plan` runs the detector per suite, then calls each workflow when its suite is true: `ci-lint.yml` (always; SwiftLint with `swiftlint`, the HANA helper with `hana`), `macos-tests.yml` (`macos`, plugins with `plugins`), `ios-tests.yml` (`ios`, TableProOracle with `oracle`), `build-linux.yml` (`linux-docs`, docs job only unless `linux`; `linux-deps` adds the minimum Rust version, the aarch64 Flatpak and the advisory database), `linux-packages.yml` (`packages`, x86_64), `core.yml` (`core`) and `windows.yml` (`windows`).
- `build-linux.yml` on a change runs the fast job, the default server releases, the x86_64 Flatpak Devel build and its tests, translations and supply chain; no job waits for the fast job. `extended` adds every other server release, the minimum Rust version, the aarch64 Flatpak, paths with spaces and the advisory database. The em dash check warns and never fails.
- A `release/**` push, or a PR into one, runs no Linux, core or Windows job: Linux ships from main or `linux-X.Y`, and the core and the Windows app have no release line.
- The base is a PR's base SHA, a merge group's base SHA, or on a main push the head SHA of the last green CI push run on main. No such run, or a dispatch, runs everything. A main push runs no suite when its parent is that last green commit and the commit itself already passed `CI` in a merge group. A dispatch never counts as main's last green run or for a tag.
- Concurrency in `ci.yml`: a PR keeps its newest run, main pushes run one at a time and a newer pending run replaces the older, and each merge group, `release/**` commit and dispatch has its own group. `linux-packages.yml` runs only when called or dispatched, under its caller's concurrency.
- The base is a PR's base SHA, or on a push the head SHA of the last green CI push run on the same branch. No such run, as on the first push of a release line, or a dispatch, runs everything. A dispatch never counts as a branch's last green run or for a tag.
- A release PR changes only the changelog, which no suite reads, so its merge runs Lint only. `version.py check` then takes each test job from the line's last run that passed it (`apple/RELEASING.md`, Branches).
- Concurrency in `ci.yml`: a PR keeps its newest run, main pushes run one at a time and a newer pending run replaces the older, and each `release/**` commit and dispatch has its own group. `linux-packages.yml` runs only when called or dispatched, under its caller's concurrency.
- `nightly.yml` is the one schedule, at 19:17 UTC: every suite in full on main, with core's Arm64 SSH tunnel tests and `build-linux.yml` extended, then `linux-packages.yml` with the Flatpak repository (arm64 too on Sundays, the second cron line), and the Release Build job, which builds and packages the app and every registry plugin as a tag does, unsigned, on `xcode-27`. No tag waits for it. GitHub mails a red run to whoever last edited the schedule.
- macOS Tests runs the Unit and UI plans in full, with no shard, parallel, iteration or retry flag.
- `core.yml` runs the core on Windows x64 and Arm64 and on macOS, where the same job builds and tests the Swift bindings, and SQL Server's integrated login on Windows x64. The SSH tunnel tests through Windows' OpenSSH Server run on x64; Arm64, whose image installs the server in about 20 minutes, runs them nightly.
Expand All @@ -44,8 +44,8 @@ paths:

## Change detector

- `scripts/ci/detect-changed-paths.sh [--base <sha>] [--head <rev>] [--ref <ref>] <suite>` prints `true` or `false`. No base prints true; an all-zero base diffs from the merge base with `origin/main`; `--ref refs/heads/release/*` prints true.
- Suites: `macos`, `plugins`, `ios`, `oracle`, `hana`, `swiftlint`, `linux` (`linux/`, `core/` and the Cargo workspace files at the top; no Markdown but `linux/CHANGELOG.md`, `linux/docs/regression-tests.md` and `linux/data/`), `linux-docs`, `linux-deps` (Cargo manifests and lock, toolchain, `deny.toml`, the Flatpak manifests, the Debian build dependencies), `packages` (Cargo manifests and lock, toolchain, Meson files, `linux/build-aux/` but its tests, `po/LINGUAS`; no Markdown), `core` (`core/`, `Cargo.toml`, `Cargo.lock`, `rust-toolchain.toml`, the FFI Swift package and what builds it; no Markdown), `windows` (`windows/`, `core/`, `Cargo.toml`, `Cargo.lock` and `rust-toolchain.toml` at the top; no Markdown), `release` (what the Release Build job reads) and `shipped` (`release` without `.github/`; `version.py check` reads it).
- `scripts/ci/detect-changed-paths.sh [--base <sha>] [--head <rev>] <suite>` prints `true` or `false`. No base prints true; an all-zero base diffs from the merge base with `origin/main`.
- Suites: `macos`, `plugins`, `ios`, `oracle`, `hana`, `swiftlint`, `linux` (`linux/`, `core/` and the Cargo workspace files at the top; no Markdown but `linux/CHANGELOG.md`, `linux/docs/regression-tests.md` and `linux/data/`), `linux-docs`, `linux-deps` (Cargo manifests and lock, toolchain, `deny.toml`, the Flatpak manifests, the Debian build dependencies), `packages` (Cargo manifests and lock, toolchain, Meson files, `linux/build-aux/` but its tests, `po/LINGUAS`; no Markdown), `core` (`core/`, `Cargo.toml`, `Cargo.lock`, `rust-toolchain.toml`, the FFI Swift package and what builds it; no Markdown), `windows` (`windows/`, `core/`, `Cargo.toml`, `Cargo.lock` and `rust-toolchain.toml` at the top; no Markdown), `release` (what the Release Build job reads) and `shipped` (`release` without `.github/`; `version.py check` reads it, and `macos` and `ios` for a test job a tag's run left out).
- Every suite but `shipped` watches `ci.yml` and its own workflow. A path a suite newly reads joins its pattern in the same change.

## Runners
Expand Down
26 changes: 4 additions & 22 deletions .github/workflows/ci-lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -109,35 +109,17 @@ jobs:
"$RUNNER_TEMP/release-venv/bin/towncrier" build --draft --dir linux --version 0.0.0

# pr-title.yml runs the same check on a title edit, which starts no CI run. The title is read now, not from the
# event, so a merge group or a re-run after a retitle sees the current one.
# event, so a re-run after a retitle sees the current one.
- name: Check only a release pull request edits a CHANGELOG.md
if: github.event_name == 'pull_request'
env:
EVENT: ${{ github.event_name }}
PR_NUMBER: ${{ github.event.pull_request.number }}
GROUP_REF: ${{ github.event.merge_group.head_ref }}
GROUP_BASE: ${{ github.event.merge_group.base_sha }}
REPOSITORY: ${{ github.repository }}
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
case "$EVENT" in
pull_request)
number="$PR_NUMBER"
base="$(git rev-parse HEAD^1)"
;;
merge_group)
number="${GROUP_REF##*/pr-}"
number="${number%%-*}"
base="$GROUP_BASE"
;;
*)
echo "Not a pull request or a merge group, so nothing to check."
exit 0
;;
esac
case "$number" in '' | *[!0-9]*) echo "::error::no pull request number for this $EVENT"; exit 1 ;; esac
title="$(gh api "repos/$REPOSITORY/pulls/$number" --jq .title)"
scripts/ci/check-changelog-edits.sh "$base" "$title"
title="$(gh api "repos/$REPOSITORY/pulls/$PR_NUMBER" --jq .title)"
scripts/ci/check-changelog-edits.sh "$(git rev-parse HEAD^1)" "$title"

# shellcheck cannot tell a library function from a command, so a missing source is exit 127
# at release time (v0.67.1).
Expand Down
49 changes: 13 additions & 36 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,12 @@ name: CI

on:
pull_request:
merge_group:
types: [checks_requested]
push:
branches: [main, 'release/**']
workflow_dispatch:

# A pull request keeps only its newest run. main runs one at a time, and a newer pending run replaces the older one.
# Each merge group, each release/** commit and each dispatch gets its own group, so none is replaced.
# Each release/** commit and each dispatch gets its own group, so none is replaced.
concurrency:
group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || github.event_name == 'workflow_dispatch' && format('dispatch-{0}', github.run_id) || github.ref == 'refs/heads/main' && github.ref || format('{0}-{1}', github.ref, github.sha) }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
Expand Down Expand Up @@ -46,57 +44,39 @@ jobs:
fetch-depth: 0
persist-credentials: false

# A merge group compares with the commit it lands on. A main push compares with the last commit a CI push run
# passed on, so a commit whose run was replaced or failed is tested again; none, one on HEAD itself, or a
# dispatch runs everything. A main push runs no suite when that commit is its parent and the merge queue already
# passed CI at this exact commit, since nothing between them went untested.
# A push compares with the last commit a CI push run on its own branch passed on, so a commit whose run was
# replaced or failed is tested again, and a release line's changelog commit runs Lint only. None, as on the first
# push of a release line, one on HEAD itself, or a dispatch runs everything.
- name: Find the base
id: base
env:
EVENT: ${{ github.event_name }}
PR_BASE: ${{ github.event.pull_request.base.sha }}
GROUP_BASE: ${{ github.event.merge_group.base_sha }}
REF: ${{ github.ref }}
BRANCH: ${{ github.ref_name }}
GH_TOKEN: ${{ github.token }}
REPOSITORY: ${{ github.repository }}
run: |
set -euo pipefail
base=""
tested=false
head="$(git rev-parse HEAD)"
case "$EVENT" in
pull_request) base="$PR_BASE" ;;
merge_group) base="$GROUP_BASE" ;;
push)
if [ "$REF" = refs/heads/main ]; then
passed="$(gh api "repos/$REPOSITORY/actions/workflows/ci.yml/runs?branch=main&event=push&status=success&per_page=1" \
--jq '.workflow_runs[0].head_sha // ""')"
if [ -n "$passed" ] && [ "$passed" != "$head" ] && git merge-base --is-ancestor "$passed" HEAD; then
base="$passed"
fi
if [ -n "$base" ] && [ "$base" = "$(git rev-parse HEAD^1)" ]; then
queued="$(gh api "repos/$REPOSITORY/actions/workflows/ci.yml/runs?event=merge_group&head_sha=$head&status=success&per_page=1" \
--jq '.total_count')"
[ "$queued" = 0 ] || tested=true
fi
passed="$(gh api "repos/$REPOSITORY/actions/workflows/ci.yml/runs?branch=$BRANCH&event=push&status=success&per_page=1" \
--jq '.workflow_runs[0].head_sha // ""')"
if [ -n "$passed" ] && [ "$passed" != "$(git rev-parse HEAD)" ] && git merge-base --is-ancestor "$passed" HEAD; then
base="$passed"
fi
;;
esac
if [ "$tested" = true ]; then
echo "The merge queue passed CI at $head, so no suite runs again."
else
echo "Base: ${base:-none, so every suite runs}"
fi
echo "Base: ${base:-none, so every suite runs}"
echo "base=$base" >> "$GITHUB_OUTPUT"
echo "tested=$tested" >> "$GITHUB_OUTPUT"

# --ref makes a release/** push run every suite. Linux ships from main or linux-X.Y, and the core and the Windows
# app have no release line, so a release/** push or a pull request into one skips them.
# Linux ships from main or linux-X.Y, and the core and the Windows app have no release line, so a release/** push
# or a pull request into one skips them.
- name: Decide which suites run
id: decide
env:
BASE: ${{ steps.base.outputs.base }}
TESTED: ${{ steps.base.outputs.tested }}
REF: ${{ github.ref }}
BASE_REF: ${{ github.base_ref }}
run: |
Expand All @@ -105,10 +85,7 @@ jobs:
case "$REF" in refs/heads/release/*) release_line=true ;; esac
case "$BASE_REF" in release/*) release_line=true ;; esac
for suite in macos plugins ios oracle hana swiftlint linux linux-docs linux-deps packages core windows; do
verdict=false
if [ "$TESTED" != true ]; then
verdict="$(scripts/ci/detect-changed-paths.sh --base "$BASE" --ref "$REF" "$suite")"
fi
verdict="$(scripts/ci/detect-changed-paths.sh --base "$BASE" "$suite")"
case "$suite" in
linux | linux-docs | linux-deps | packages | core | windows) [ "$release_line" = false ] || verdict=false ;;
esac
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/ios-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ jobs:
CODE_SIGNING_ALLOWED=NO COMPILER_INDEX_STORE_ENABLE=NO COMPILATION_CACHE_ENABLE_CACHING=NO \
| xcbeautify --renderer github-actions

# Saved by a push or the nightly only: a cache saved on a pull request or merge group ref is visible to it alone.
# Saved by a push or the nightly only: a cache saved on a pull request ref is visible to it alone.
- name: Save Swift package checkouts
if: (github.event_name == 'push' || github.event_name == 'schedule') && steps.tests.outcome == 'success' && steps.spm.outputs.cache-hit != 'true'
uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/macos-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ jobs:
-project TablePro.xcodeproj -scheme TablePro \
-clonedSourcePackagesDirPath ~/.spm-cache -skipPackagePluginValidation

# Saved by a push or the nightly only: a cache saved on a pull request or merge group ref is visible to it alone.
# Saved by a push or the nightly only: a cache saved on a pull request ref is visible to it alone.
- name: Save Swift package checkouts
if: (github.event_name == 'push' || github.event_name == 'schedule') && steps.prepare.outputs.cache-hit != 'true'
uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Native database clients with a native UI per platform: `apple/` holds the macOS

- The PR title is the squash commit subject, `type(scope): description`. The body follows `.github/pull_request_template.md`.
- A rename or signature change updates every caller and test in the same commit.
- Agents merge on green with `gh pr merge <N> --auto`: main's merge queue squashes and refuses `--squash`; a `release/*` pull request takes `--auto --squash`. They create a `release/*` branch or a tag only when the maintainer says to release, and use `--admin` only on the maintainer's word.
- Agents merge on green with `gh pr merge <N> --auto --squash`, into main or a `release/*` line. They create a `release/*` branch or a tag only when the maintainer says to release, and use `--admin` only on the maintainer's word.

## CI

Expand Down
5 changes: 4 additions & 1 deletion apple/RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ Such a change stops the release until a fix lands on `main`.
- `release/X.Y` is cut from `main` at beta.1 and closes when X.(Y+1).0 ships. A later security or data-loss fix for its users ships as a critical patch on the current line.
- Every fix lands on `main` first. A pick is one fix per PR, never a `feat` or a PluginKit bump. A patch takes only a regression from the previous stable, a crash, a plugin that fails to load, a security fix or data loss.
- `release/0.82` predates the move into `apple/` and follows the `RELEASING.md` on that branch: paths at the root, no `ci.yml`, and a `verify` that waits up to 240 min for green macOS Tests, iOS and Package Tests and Release Build push runs covering the tag. A pick from `main` relies on rename detection.
- A line push runs the suites whose paths changed since the line's last green CI push run; the first push of a line runs them all. A release PR's merge changes only the changelog, so it runs Lint only.
- `version.py check` accepts a test job the tag's run left out when the job passed at an ancestor on the line and its suite has not changed since.
- `release/0.86` and older lines run every suite on every push, so a tag had its own test runs (#3584). That re-ran 77 to 114 min of tests after each release PR, so later lines filter like `main`.

```bash
git fetch origin && git switch -c backport/<PR>-X.Y origin/release/X.Y
Expand Down Expand Up @@ -110,7 +113,7 @@ Once the release PR of a stable or patch merges and its tag's App and Plugins jo
git fetch origin && git switch -c forward/vX.Y.Z origin/main
git cherry-pick -x <release commit> && git push -u origin HEAD
gh pr create --base main --title "chore(release): vX.Y.Z" --body "Forward-port of #<PR>."
gh pr merge --auto
gh pr merge --auto --squash
```

- A newer open line gets the same PR from `origin/release/<line>`, with `--base release/<line>`.
Expand Down
Loading
Loading