From 533e6d8192c77d75b466ca3472c37f15b573bb3d Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Mon, 19 Oct 2026 04:24:57 +0700 Subject: [PATCH] docs(development): point at the app's apple/ paths --- AGENTS.md | 2 +- STYLE.md | 2 +- development/overview.mdx | 6 +++--- development/plugin-development.mdx | 8 ++++---- development/plugin-registry.mdx | 6 +++--- development/testing-plugins.mdx | 8 ++++---- features/acknowledgements.mdx | 2 +- installation.mdx | 2 +- scripts/check-docs-against-source.py | 9 +++++---- 9 files changed, 23 insertions(+), 22 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8b792747..b07aa861 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,7 +40,7 @@ Run the three scripts against an app checkout at the `main` the change describes - **A change that documents an app change** opens as a draft pull request whose description names the app pull request (`TableProApp/TablePro#1234`). CI checks against the app's `main`, so it goes green once the app pull request merges; mark it ready then. - **The daily run** catches an app change that broke a claim here. Fix the page, not the check. -- **Releases.** For each stable release, the app's `release` skill opens a `docs(changelog): vX.Y.Z` pull request whose `` block in `changelog.mdx` is written by the app's `scripts/release/notes.py docs`, and merges it once the release is published. Every version in the app's `CHANGELOG.md` must be on that page. +- **Releases.** For each stable release, the app's `release` skill opens a `docs(changelog): vX.Y.Z` pull request whose `` block in `changelog.mdx` is written by the app's `apple/scripts/release/notes.py docs`, and merges it once the release is published. Every version in the app's `apple/CHANGELOG.md` must be on that page. ## Writing style diff --git a/STYLE.md b/STYLE.md index e3cb4484..aef1b3cd 100644 --- a/STYLE.md +++ b/STYLE.md @@ -251,7 +251,7 @@ Verbs: **click** a button, **choose** a menu item, **select** a row or a checkbo **deselect** a checkbox. Never "click on", never "uncheck". **Menu paths** are one bold run with ` > `: `**File > Import from Other App…**`, never -`**File** > **X**`. Verify the leaf against `TablePro/Core/Menu/*MenuBuilder.swift` every time. Eight +`**File** > **X**`. Verify the leaf against `apple/TablePro/Core/Menu/*MenuBuilder.swift` every time. Eight paths were wrong at once because the Database menu shipped and nobody re-checked. **Shortcuts** in backticks, modifiers spelled out, joined with `+`: `` `Cmd+Option+F` ``. Never bold, diff --git a/development/overview.mdx b/development/overview.mdx index dc8546d4..47b01cf7 100644 --- a/development/overview.mdx +++ b/development/overview.mdx @@ -5,9 +5,9 @@ description: Build TablePro from source, contribute a change, or write a databas Building and contributing to the app is documented in the app repository, next to the code it describes: -- [CONTRIBUTING.md](https://github.com/TableProApp/TablePro/blob/main/CONTRIBUTING.md): setup, building, tests, code style, architecture, pull requests and translation. -- [AGENTS.md](https://github.com/TableProApp/TablePro/blob/main/AGENTS.md): the invariants and rules every change has to meet. -- [RELEASING.md](https://github.com/TableProApp/TablePro/blob/main/RELEASING.md): release builds, notarization and the release tag. +- [apple/CONTRIBUTING.md](https://github.com/TableProApp/TablePro/blob/main/apple/CONTRIBUTING.md): setup, building, tests, code style, architecture, pull requests and translation. +- [AGENTS.md](https://github.com/TableProApp/TablePro/blob/main/AGENTS.md) and [apple/AGENTS.md](https://github.com/TableProApp/TablePro/blob/main/apple/AGENTS.md): the invariants and rules every change has to meet. +- [apple/RELEASING.md](https://github.com/TableProApp/TablePro/blob/main/apple/RELEASING.md): release builds, notarization and the release tag. These pages live in [TableProApp/docs](https://github.com/TableProApp/docs). A docs change that goes with an app change is a pull request there. diff --git a/development/plugin-development.mdx b/development/plugin-development.mdx index f376ffe1..81159782 100644 --- a/development/plugin-development.mdx +++ b/development/plugin-development.mdx @@ -3,7 +3,7 @@ title: Plugin Development description: Write a database driver plugin, implement the PluginKit protocols, and package it as a .tableplugin bundle --- -Start from a plugin that already works. `Plugins/SurrealDBDriverPlugin/` is the compact reference: no C bridge, an HTTP transport, the schema-aware query hooks filled in, and an editor language of its own. +Start from a plugin that already works. `apple/Plugins/SurrealDBDriverPlugin/` is the compact reference: no C bridge, an HTTP transport, the schema-aware query hooks filled in, and an editor language of its own. Two protocols do the work. `DriverPlugin` describes the database (name, port, capabilities, SQL dialect) and creates driver instances; `PluginDatabaseDriver` is the connection itself. Implement both in a `.tableplugin` bundle linked against **TableProPluginKit**, and `PluginDriverAdapter` bridges your driver to the app's internal `DatabaseDriver`. A driver that connects and lists tables gets the whole UI without asking: connection form, sidebar, data grid, editor, import, export. @@ -48,7 +48,7 @@ The host also injects three reserved `additionalFields` keys before it creates a A `.number` field takes a whole number of 0 or more. The form keeps ASCII digits only and will not save anything else. Use `.stepper(range:)` for a bounded or signed integer, and `.text` for a value with a decimal point. -The remaining fifty-odd statics all have defaults: connection mode, URL schemes, brand color, editor language, `sqlDialect` (keywords, functions, completions), navigation model, system database names, and two dozen `supports*` capability flags. Override the ones that differ. `Plugins/TableProPluginKit/DriverPlugin.swift` is the full list. +The remaining fifty-odd statics all have defaults: connection mode, URL schemes, brand color, editor language, `sqlDialect` (keywords, functions, completions), navigation model, system database names, and two dozen `supports*` capability flags. Override the ones that differ. `apple/Plugins/TableProPluginKit/DriverPlugin.swift` is the full list. ## Implementing PluginDatabaseDriver @@ -100,7 +100,7 @@ Two changes look additive and are not. Both have shipped, and both surface the s [`.claude/rules/plugin-system.md`](https://github.com/TableProApp/TablePro/blob/main/.claude/rules/plugin-system.md) in the app repository carries the full additive-versus-breaking list and the checklist a breaking bump obliges you to run, including re-releasing every registry plugin before the app ships. ```bash -scripts/check-pluginkit-abi.sh [base-ref] +apple/scripts/check-pluginkit-abi.sh [base-ref] ``` -Run it before merging any change under `Plugins/TableProPluginKit/`. It builds the framework at your tree and at the base ref with one toolchain and diffs the two public interfaces, so a Swift version difference between machines can never fake a diff. The base ref defaults to `origin/main`; pass the merge base when reviewing a branch. Commit or stash first, since it refuses a dirty working tree. +Run it before merging any change under `apple/Plugins/TableProPluginKit/`. It builds the framework at your tree and at the base ref with one toolchain and diffs the two public interfaces, so a Swift version difference between machines can never fake a diff. The base ref defaults to `origin/main`; pass the merge base when reviewing a branch. Commit or stash first, since it refuses a dirty working tree. diff --git a/development/plugin-registry.mdx b/development/plugin-registry.mdx index 3f1e16ba..d053852a 100644 --- a/development/plugin-registry.mdx +++ b/development/plugin-registry.mdx @@ -9,13 +9,13 @@ The app reads the manifest to install a driver when someone picks a database typ ## Getting a plugin into the registry -Contribute it to TablePro's repository, as a target in the `RegistryPlugins` aggregate of `project.yml` and an entry in `.github/plugin-registry.json` that gives its display name. The next release publishes it: a beta tag publishes to the `beta` channel, a stable tag to `stable`. A fix to a plugin ships the same way, in the next beta or patch. +Contribute it to TablePro's repository, as a target in the `RegistryPlugins` aggregate of `apple/project.yml` and an entry in `.github/plugin-registry.json` that gives its display name. The next release publishes it: a beta tag publishes to the `beta` channel, a stable tag to `stable`. A fix to a plugin ships the same way, in the next beta or patch. Bundled plugins ship inside the app and never appear in the manifest. The app never installs a registry copy over a bundled one. ## The manifest -`https://updates.tablepro.app/plugins/v3.json`, served by GitHub Pages from the `feeds` branch that the release workflow writes through `scripts/release/registry.py`. The schema version is part of the path, so a later schema ships beside this one instead of replacing it. Within v3, changes only add fields. +`https://updates.tablepro.app/plugins/v3.json`, served by GitHub Pages from the `feeds` branch that the release workflow writes through `apple/scripts/release/registry.py`. The schema version is part of the path, so a later schema ships beside this one instead of replacing it. Within v3, changes only add fields. ```json { @@ -75,7 +75,7 @@ Plugins are sorted by `id`, and each plugin's releases by `build`, highest first Releases whose `minimumSystemVersion` is above the running macOS are skipped. - `pluginKit` has to fall between `TABLEPRO_PLUGINKIT_MINIMUM_VERSION` and `TABLEPRO_PLUGINKIT_VERSION` in `Configs/PluginKit.xcconfig`. + `pluginKit` has to fall between `TABLEPRO_PLUGINKIT_MINIMUM_VERSION` and `TABLEPRO_PLUGINKIT_VERSION` in `apple/Configs/PluginKit.xcconfig`. The highest `build` left wins. diff --git a/development/testing-plugins.mdx b/development/testing-plugins.mdx index de04dcd5..06efffad 100644 --- a/development/testing-plugins.mdx +++ b/development/testing-plugins.mdx @@ -23,7 +23,7 @@ Do not reuse a built-in plugin's bundle ID. Installing over one fails outright, ## Install with the dev script ```bash -scripts/install-plugin-dev.sh MyDriverPlugin +apple/scripts/install-plugin-dev.sh MyDriverPlugin ``` It finds the newest `MyDriverPlugin.tableplugin` under DerivedData and copies it into the user plugins directory. Relaunch TablePro to load it. Build from Xcode first: the script reads DerivedData, and a command-line `xcodebuild` writes to `build/Debug` instead, where the script never looks. @@ -34,7 +34,7 @@ Never edit the copied bundle, `Info.plist` included. Any change invalidates the ## Bundle it into the app instead -A plugin embedded in `PlugIns/` skips the signature check entirely, which is the shortest path when the team check is the thing in your way. Add the target to the app's dependency list in `project.yml`: +A plugin embedded in `PlugIns/` skips the signature check entirely, which is the shortest path when the team check is the thing in your way. Add the target to the app's dependency list in `apple/project.yml`: ```yaml targets: @@ -46,10 +46,10 @@ targets: destination: plugins ``` -Then run `scripts/generate-project.sh` and build. XcodeGen puts the bundle in an **Embed Dependencies** copy phase with `CodeSignOnCopy`, so it is re-signed with your debug identity on the way in. +Then run `apple/scripts/generate-project.sh` and build. XcodeGen puts the bundle in an **Embed Dependencies** copy phase with `CodeSignOnCopy`, so it is re-signed with your debug identity on the way in. -`TablePro.xcodeproj` is generated and gitignored, so adding the plugin through the Xcode UI survives exactly until the next `scripts/generate-project.sh`. Edit `project.yml`. Take the entry back out before you open a pull request, or the plugin rides into a release build. +`apple/TablePro.xcodeproj` is generated and gitignored, so adding the plugin through the Xcode UI survives exactly until the next `apple/scripts/generate-project.sh`. Edit `apple/project.yml`. Take the entry back out before you open a pull request, or the plugin rides into a release build. ## Skip the signature check diff --git a/features/acknowledgements.mdx b/features/acknowledgements.mdx index 6c148b99..f3955295 100644 --- a/features/acknowledgements.mdx +++ b/features/acknowledgements.mdx @@ -9,7 +9,7 @@ Pick one and the detail pane gives its exact shipped version, its SPDX identifie Two labels carry meaning: -- **Modified** marks a library TablePro patches before building. The patches live in `scripts/patches/` in the public repository, next to the build script that pins the version. FreeTDS is patched for federated authentication and libssh2 for backported security fixes; nothing else is. +- **Modified** marks a library TablePro patches before building. The patches live in `apple/scripts/patches/` in the public repository, next to the build script that pins the version. FreeTDS is patched for federated authentication and libssh2 for backported security fixes; nothing else is. - **License Not Yet Confirmed** is a separate section for libraries whose own project publishes no license file. TablePro cannot state one for them, and lists them anyway so the gap stays visible. TablePro's own source is available under the AGPL v3 at [github.com/TableProApp/TablePro](https://github.com/TableProApp/TablePro). If a library is missing, credited wrongly, or attributed to the wrong license, [open an issue](https://github.com/TableProApp/TablePro/issues). diff --git a/installation.mdx b/installation.mdx index e4bc0070..3ead93a8 100644 --- a/installation.mdx +++ b/installation.mdx @@ -50,4 +50,4 @@ rm ~/Library/Preferences/com.TablePro.plist Connection passwords are in the macOS Keychain and survive both commands. Delete them in Keychain Access by searching for `com.TablePro`. Data already synced through iCloud stays in your iCloud account. -Building from source is in [CONTRIBUTING.md](https://github.com/TableProApp/TablePro/blob/main/CONTRIBUTING.md#setup). A launch that fails or a connection that will not open is in [Troubleshooting](/troubleshooting). +Building from source is in [apple/CONTRIBUTING.md](https://github.com/TableProApp/TablePro/blob/main/apple/CONTRIBUTING.md#setup). A launch that fails or a connection that will not open is in [Troubleshooting](/troubleshooting). diff --git a/scripts/check-docs-against-source.py b/scripts/check-docs-against-source.py index fdb4954f..e819661c 100755 --- a/scripts/check-docs-against-source.py +++ b/scripts/check-docs-against-source.py @@ -74,9 +74,10 @@ def leaf_forms(leaf: str) -> set[str]: def app_root(path: str) -> Path: - root = Path(path).resolve() + # Every claim checked here is about the macOS app, which lives in the checkout's apple/. + root = Path(path).resolve() / "apple" if not (root / "TablePro" / "Core" / "Menu").is_dir(): - sys.exit(f"{path} is not a TablePro app checkout") + sys.exit(f"{path} is not a TablePro app checkout: it has no apple/TablePro/Core/Menu") return root @@ -197,7 +198,7 @@ def check_pluginkit_version(root: Path, docs: Path) -> list[str]: config = (root / "Configs" / "PluginKit.xcconfig").read_text() current = re.search(r"^TABLEPRO_PLUGINKIT_VERSION\s*=\s*(\d+)\s*$", config, re.M) if not current: - return ["Configs/PluginKit.xcconfig no longer sets TABLEPRO_PLUGINKIT_VERSION"] + return ["apple/Configs/PluginKit.xcconfig no longer sets TABLEPRO_PLUGINKIT_VERSION"] expected = current.group(1) failures = [] @@ -220,7 +221,7 @@ def check_pluginkit_version(root: Path, docs: Path) -> list[str]: def check_changelog_parity(root: Path, docs: Path) -> list[str]: """Every release in CHANGELOG.md must appear on the changelog page. - The app's scripts/release/notes.py docs writes each stable's block from its CHANGELOG.md + The app's apple/scripts/release/notes.py docs writes each stable's block from its CHANGELOG.md section. The check stays one-way: the page may carry a version the file does not, which is how 0.39.0 is documented. It shipped, failed to launch with errno 163, and 0.39.1 replaced it the same day.