diff --git a/docs/.mintignore b/docs/.mintignore index 9922f06dc8..154b3e31f6 100644 --- a/docs/.mintignore +++ b/docs/.mintignore @@ -5,3 +5,6 @@ # Draft content drafts/ *.draft.mdx + +# Contributor style guide, not a docs page +STYLE.md diff --git a/docs/LICENSE b/docs/LICENSE deleted file mode 100644 index 5411374274..0000000000 --- a/docs/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2023 Mintlify - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 74c313f573..97fd0918d5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,3 +32,7 @@ Preview at `http://localhost:3000`. ## Deployment Changes pushed to the default branch are deployed automatically via the [Mintlify GitHub app](https://dashboard.mintlify.com/settings/organization/github-app). + +## License + +The pages in this directory are covered by the repository's [AGPLv3 license](../LICENSE), like the rest of TablePro. The TablePro name and logo, including `logo/` and `favicon.png`, are trademarks of Ngo Quoc Dat and are not licensed under it. Screenshots of other products belong to their owners. diff --git a/docs/customization/appearance.mdx b/docs/customization/appearance.mdx index 8fa568aea8..62bfc585df 100644 --- a/docs/customization/appearance.mdx +++ b/docs/customization/appearance.mdx @@ -54,7 +54,7 @@ Interface, Sidebar, and Toolbar colors sit on macOS system colors until you over ## Theme files -A theme is one JSON file. **Export…** in the gear menu writes every color the active theme sets, which is the shortest way to start a new one; **Import…** in the **+** menu reads one back into `~/Library/Application Support/TablePro/Themes/`. Community themes install from the [registry](/features/plugins) under **Settings > Plugins > Browse**, Themes category. +A theme is one JSON file. **Export…** in the gear menu writes every color the active theme sets, which is the shortest way to start a new one; **Import…** in the **+** menu reads one back into `~/Library/Application Support/TablePro/Themes/`. Themes published to the [plugin registry](/features/plugins#themes) install from **Settings > Plugins > Browse**, Themes category. | Key | Holds | |-----|-------| diff --git a/docs/development/plugin-development.mdx b/docs/development/plugin-development.mdx index dc079d8171..6cc14743a2 100644 --- a/docs/development/plugin-development.mdx +++ b/docs/development/plugin-development.mdx @@ -97,12 +97,13 @@ Run it before merging any change under `Plugins/TableProPluginKit/`. It builds t A plugin needs TableProPluginKit, not this repository. Every driver happens to live under `Plugins/` here. A new one does not have to. ```bash +git checkout v # the oldest app release your plugin supports scripts/generate-project.sh scripts/build-pluginkit-xcframework.sh # build/pluginkit/TableProPluginKit.xcframework, plus a zip and its SHA-256 ``` -Run that, or download a published XCFramework from the `pluginkit-v` release, and link it from your own Xcode project. Your plugin target then needs nothing else from this repository. +No prebuilt XCFramework is published, so build it this way and link the result from your own Xcode project. Build from a release tag, not `main`: the app rejects a plugin that declares a newer PluginKit than its own, and `main` moves ahead of the shipped app each time the PluginKit version is raised. Your plugin target then needs nothing else from this repository. Link it as **Do Not Embed**. The app supplies TableProPluginKit at runtime, so a copy inside your bundle is a second, conflicting one. The script refuses to emit a framework with no `.swiftinterface`, which is what a build without Library Evolution looks like: it links today and breaks every consumer on the next release. diff --git a/docs/development/plugin-registry.mdx b/docs/development/plugin-registry.mdx index f06edb58b6..9557ff6b28 100644 --- a/docs/development/plugin-registry.mdx +++ b/docs/development/plugin-registry.mdx @@ -3,9 +3,9 @@ title: Plugin Registry description: Registry manifest format, binary selection, publishing, and PluginKit compatibility --- -The registry lives in TablePro's repository, so publishing there means a pull request. Signing a plugin with your own Developer ID and serving it from a manifest you host is the other route, and the format on this page is the same either way. For what install and update look like to a user, see [Plugins & Themes](/features/plugins); to build the plugin in the first place, [Plugin Development](/development/plugin-development). +The official manifest is `plugins.json` in [TableProApp/plugins](https://github.com/TableProApp/plugins), and TablePro's release workflow writes it: a plugin gets there by being contributed to TablePro's own repository and tagged there. A plugin of yours ships the other way: signed with your own Developer ID, it installs from a file or from a manifest you host in the same format. For what install and update look like to a user, see [Plugins & Themes](/features/plugins); to build the plugin in the first place, [Plugin Development](/development/plugin-development). -TablePro's manifest is `plugins.json` at [github.com/TableProApp/plugins](https://github.com/TableProApp/plugins). The app fetches it to fill **Settings > Plugins > Browse** and to auto-install a driver when someone picks a database type with no plugin loaded. +The app fetches the manifest to fill **Settings > Plugins > Browse** and to auto-install a driver when someone picks a database type with no plugin loaded. ## Manifest format @@ -100,7 +100,7 @@ The optional `metadata` object makes an entry self-describing, so the app render ## Publishing a plugin -Every plugin CI can publish has an entry in `.github/plugin-registry.json`, keyed by the slug that appears in its tag. That file maps the slug to a build target, so the mapping has no derivation rule: `mssql` builds `MSSQLDriver` and `cloudflare-d1` builds `CloudflareD1DriverPlugin`. Add the entry before the first tag, or the workflow exits with `Unknown plugin`. +Every plugin CI can publish has an entry in `.github/plugin-registry.json` in TablePro's repository, keyed by the slug that appears in its tag. That file maps the slug to a build target, so the mapping has no derivation rule: `mssql` builds `MSSQLDriver` and `cloudflare-d1` builds `CloudflareD1DriverPlugin`. Add the entry before the first tag, or the workflow exits with `Unknown plugin`. ```bash git tag -a plugin-oracle-v1.0.26 -m "plugin-oracle-v1.0.26" @@ -117,9 +117,9 @@ Dispatching the workflow works too. Its `tags` input takes comma-separated `tag: gh workflow run build-plugin.yml --field "tags=plugin-oracle-v1.0.26" ``` -Either way CI builds both architectures, signs and notarizes the bundles, checks each bundle's declared PluginKit version against the release label, creates the GitHub release, re-verifies the published assets, and updates `plugins.json` through `.github/scripts/update-registry.py`, which writes atomically and rebases on a retry when the matrix jobs collide. +Either way CI builds both architectures, signs and notarizes the bundles, checks each bundle's declared PluginKit version against the release label, creates the GitHub release, re-verifies the published assets, and pushes the updated `plugins.json` to TableProApp/plugins through `.github/scripts/update-registry.py`, which writes atomically and rebases on a retry when the matrix jobs collide. -Most bundled plugins never appear in the registry at all, because their binaries ride with the app release. Ten of them keep a registry arm anyway (SQLite, ClickHouse, Redis, XLSX export, XLSX import, MQL export, SQL import, HTML export, Markdown export, XML export), so a fix can reach users who are already on a shipped app without waiting for the next one. A bulk ABI re-release skips them. +Bundled plugins ride with the app release. Ten of them also have an entry in `.github/plugin-registry.json` (SQLite, ClickHouse, Redis, XLSX export, XLSX import, MQL export, SQL import, HTML export, Markdown export, XML export), so a fix to one can be tagged and published to the registry before the next app release. A bulk ABI re-release skips them. The other seven have no entry and never reach `plugins.json`. ## PluginKit compatibility @@ -177,4 +177,4 @@ defaults write com.TablePro com.TablePro.customRegistryURL "https://your-registr defaults delete com.TablePro com.TablePro.customRegistryURL ``` -HTTP caching keys on the full URL, so a changed registry URL takes effect on the next fetch. A plugin served this way installs once the user agrees to trust its signing team by name. Both commands are also listed in [Settings](/customization/settings). +The custom manifest replaces the official one rather than adding to it. HTTP caching keys on the full URL, so a changed registry URL takes effect on the next fetch. A plugin served this way installs once the user agrees to trust its signing team by name. Both commands are also listed in [Settings](/customization/settings).