diff --git a/.agents/skills/README.md b/.agents/skills/README.md new file mode 100644 index 000000000000..0bc11da3ea7a --- /dev/null +++ b/.agents/skills/README.md @@ -0,0 +1,62 @@ +# AI Skills + +This directory contains project-specific AI skills following the open +[Agent Skills standard](https://agentskills.io/specification), so the same +skill files work across multiple AI coding tools (Devin, Devin CLI, Windsurf, +and other compatible agents). Skills defined here are committed to git and +shared with the whole team. + +`.agents/skills/` is the recommended location per the +[Devin skills guide](https://docs.devin.ai/product-guides/skills). + +## Adding a skill + +Create a directory named after your skill with a `SKILL.md` file inside: + +``` +.agents/skills/ +└── my-skill/ + └── SKILL.md +``` + +The directory name is the skill's identifier — users can invoke it explicitly +(e.g. `/my-skill` or `@skills:my-skill`), and the agent can also invoke it +autonomously when relevant. + +## SKILL.md template + +```markdown +--- +name: my-skill +description: One-line summary shown in the skill list +argument-hint: '[optional arguments hint]' +allowed-tools: + - read + - grep + - glob + - exec +triggers: + - user + - model +--- + +Your prompt content goes here. Write clear, step-by-step instructions +for the agent to follow when this skill is invoked. +``` + +## Frontmatter reference + +| Field | Default | Description | +| --------------- | --------------- | --------------------------------------------------------- | +| `name` | directory name | Display name of the skill | +| `description` | none | Short summary shown in the skill list | +| `argument-hint` | none | Hint describing expected arguments (e.g. `[filename]`) | +| `allowed-tools` | all tools | Restrict which tools the skill can use | +| `triggers` | `[user, model]` | `user` = explicit invocation, `model` = agent auto-invoke | + +All frontmatter is optional — a plain markdown file with just prompt content is +a valid skill. Set `triggers: [user]` to prevent the agent from invoking a +skill on its own. + +Arguments passed at invocation time are substituted into the skill body +wherever `$ARGUMENTS`, `$0`, `$1`, etc. appear. diff --git a/.agents/skills/prepare-major-version/SKILL.md b/.agents/skills/prepare-major-version/SKILL.md new file mode 100644 index 000000000000..681de034cf2b --- /dev/null +++ b/.agents/skills/prepare-major-version/SKILL.md @@ -0,0 +1,276 @@ +--- +name: prepare-major-version +description: Prepare the THEOplayer documentation for a new major version (snapshot current docs as a versioned copy, prepare /theoplayer for the next major) +argument-hint: '[new major version, e.g. v12]' +triggers: + - user + - model +--- + +# Prepare documentation for a new THEOplayer major version + +This skill prepares the docs for a new THEOplayer major release. It moves the +current docs in `/theoplayer` to `/theoplayer_versioned_docs/version-v`, +and prepares `/theoplayer` to become the docs for the new major version. + +Reference PRs (use them if in doubt about any step): + +- v11: https://github.com/THEOplayer/documentation/pull/576 +- v10: https://github.com/THEOplayer/documentation/pull/407 + +## Determine versions + +- `OLD` = the major version of `theoplayer/version.txt` (e.g. `11` if it contains `11.7.0`). +- `NEW` = `OLD + 1`, or the version given as `$ARGUMENTS` (e.g. `v12`). + +Work on a new branch named `theoplayer-v`. + +Make **one commit per step below**, using the step title as the commit message. +This keeps the PR reviewable, exactly like the reference PRs. + +## Step 1: `npm run docusaurus docs:version:theoplayer v` + +Run exactly that command. It copies `theoplayer/` to +`theoplayer_versioned_docs/version-v/`, creates +`theoplayer_versioned_sidebars/version-v-sidebars.json`, and adds `v` +to `theoplayer_versions.json`. + +The command copies **everything** inside `theoplayer/`, including `assets/`, +`external/` and `static/`. **Delete those three directories** from +`theoplayer_versioned_docs/version-v/` before committing, so no extra +files are created that would need to be deleted again in a subsequent commit: + +- `assets/` and `static/` stay shared with the current docs (relative links + into them are fixed in step 5). +- `external/` contains plain-file copies of the submodule checkouts; it is + re-added as proper git submodules in step 2. + +Commit with the literal command as the message: `npm run docusaurus docs:version:theoplayer v`. + +## Step 2: Add submodules for v + +The versioning command does **not** copy the `external/` submodules. Add new +entries to `.gitmodules` for each submodule under `theoplayer/external/`, +following the exact pattern of the existing `-v` entries: + +| Submodule name | Path under `theoplayer_versioned_docs/version-v/external/` | Branch | +| -------------------------------- | --------------------------------------------------------------- | --------- | +| `react-native-v` | `react-native-theoplayer` | `.x` | +| `flutter-v` | `flutter-theoplayer-sdk` | `.x` | +| `web-connectors-v` | `web-connectors` | `main` | +| `android-connector-v` | `android-connector` | `.x` | +| `ios-connector-v` | `iOS-Connector` | `.x` | +| `react-native-connectors-v` | `react-native-connectors` | `main` | + +All new entries must have `shallow = true`. Use the same URL as the +corresponding current-version submodule. Verify the `.x` branches actually +exist in the upstream repos (`git ls-remote --heads ".x"`); if a +branch doesn't exist yet, ask how to proceed and flag it in the PR +description. Then initialize them: + +``` +git submodule update --init --depth 1 -- theoplayer_versioned_docs/version-v/external +``` + +## Step 3: Update config for v + +In `docusaurus.config.ts`, in the `theoplayer` docs plugin: + +- Add `'v'` to the non-production `onlyIncludeVersions` list (after `'current'`). +- Add a `v` entry to `versions` (before `v`): + ```ts + v: { + label: fs.readFileSync(path.join(__dirname, 'theoplayer_versioned_docs/version-v/version.txt'), 'utf8').trim(), + banner: 'none', + noIndex: true, + }, + ``` +- Change the `v` entry's `banner` from `'none'` to `'unmaintained'`. + +## Step 4: Make v the latest version + +Until the new major is actually released, `v` must stay the "latest" +(default) version in production. In the `theoplayer` plugin config, change: + +```ts +lastVersion: 'current', +``` + +to: + +```ts +lastVersion: 'v', +includeCurrentVersion: !isProductionDeployment, +``` + +Since the current version is now excluded from production builds, the +`current` entry in the `versions` map must also be conditional, otherwise a +production build fails with `unknown versions (current) found`: + +```ts +versions: { + ...(!isProductionDeployment && { + current: { + label: fs.readFileSync(path.join(__dirname, 'theoplayer/version.txt'), 'utf8').trim(), + }, + }), + // ... +}, +``` + +Verify with a production-mode build (`docusaurus build` sets +`NODE_ENV=production`; CI PR builds set `DOCUSAURUS_PR_NUMBER` which makes +`isProductionDeployment` false). + +This commit is **reverted at the end** of the PR (see step 12), right before +the new major version ships. If the PR will only be merged when v is +released, still make this commit and its revert, so it can be cherry-picked if +plans change. + +## Step 5: Fix asset links + +The `theoplayer/assets/` directory is not copied into the versioned docs. +In `theoplayer_versioned_docs/version-v/`, links like: + +``` +../assets/img/foo.png +``` + +must be rewritten to point at the current docs' assets, adding the extra +directory levels: + +``` +../../../theoplayer/assets/img/foo.png +``` + +Search for `assets/` in the new versioned docs and fix every relative link +that resolves to a non-existent path (the number of `../` segments depends on +the depth of the referencing file). + +## Step 6: Copy THEOplayer examples to v + +- Copy `theoplayer/static/theoplayer/v/examples/` to `theoplayer/static/theoplayer/v/examples/`. + Copy **only** the `examples/` subfolder — the rest of + `theoplayer/static/theoplayer/v/` (e.g. `api-reference/`) is large + generated content that must not be duplicated. +- In `theoplayer/examples/*.mdx`, update iframe URLs from `/theoplayer/v/examples/...` to `/theoplayer/v/examples/...`. + +The versioned docs (`version-v/examples/`) keep pointing at the v examples. + +## Step 7: Fix links to versioned docs + +In `theoplayer_versioned_docs/version-v/`, links into _other_ versioned +docs that were written from the perspective of `theoplayer/` no longer resolve. +Rewrite paths like: + +``` +../../theoplayer_versioned_docs/version-v4/faq/foo.md +``` + +to relative paths within the versioned docs tree: + +``` +../../version-v4/faq/foo.md +``` + +Keep the **same number** of `../` segments and only remove the +`theoplayer_versioned_docs/` segment: the versioned copy lives one directory +deeper than `theoplayer/`, which exactly compensates for the removed segment. + +Also fix any links from the versioned docs to files that only exist in the +current docs. Run a local build (step 11) to find all broken links. + +## Step 8: Update links to API references for version + +In the **current** docs (`theoplayer/`), update API reference links: + +- `pathname:///theoplayer/v/api-reference/...` → `pathname:///theoplayer/v/api-reference/...` + +Only change files under `theoplayer/`, not the versioned docs. Note: these +links will 404 until the v API reference is published; that's expected, +since this PR only merges when v ships. + +After the release, also update `sidebarsTheoplayer.ts` (`apiReferencesLink` +hrefs) and API links in the other doc trees (`ads/`, `millicast/`, `theolive/`) +that point to `/theoplayer/v/api-reference/`. + +## Step 9: Update version for v + +Set `theoplayer/version.txt` to `.0.0`. + +## Step 10: Migration guides + +1. **Move** (git mv, preserving numeric prefixes) the migration guides in the + current docs, renaming `` to ``: + - `theoplayer/getting-started/01-sdks/01-web/13-migrating-to-theoplayer-.md` + - `theoplayer/getting-started/01-sdks/02-android/03-migrating-to-theoplayer-.md` + - `theoplayer/getting-started/01-sdks/03-ios/03-migrating-to-theoplayer-.md` + - `theoplayer/getting-started/01-sdks/09-roku/01-migrating-to-theoplayer-.md` + + Commit as "Move migration guides". + +2. **Prepare** each guide as a template for the new version, as a separate + "Prepare migration guides" commit: + - Update the title and intro: "Migrating to THEOplayer SDK .x", + "...updating from THEOplayer SDK version (from version )". + - Bump install snippets (`npm install theoplayer@`, + `com.theoplayer.theoplayer-sdk-android:core:.+`, etc.). + - **Remove** all breaking-change sections specific to the old major, keeping + only the generic "Update THEOplayer" and empty "Replace usages of + deprecated APIs" skeleton. The real breaking changes are added later by + each platform team before release. + - Keep the structure/wording aligned across the four platform guides. + +3. Check for any older versioned docs (e.g. v4) that link to "latest version" + migration guides and update them. + +## Step 11: Update metadata for v changelog, run Prettier, verify + +- Retitle `theoplayer_versioned_docs/version-v/changelog.md` from + `# Changelog` (with the "release notes for ... and higher" intro) to: + + ```md + # Changelog for version .x + + + + + ``` + +- Update the intro list in `theoplayer/changelog.md` to say "release notes for + THEOplayer .0.0 and higher" and add a link line for + `[Version .x](https://optiview.dolby.com/docs/theoplayer/v/changelog/)`. +- Run Prettier over the changed files (`npx prettier --write .`), commit as "Run Prettier". +- Verify with `npm run build`; the build fails on broken links — fix any + reported in `theoplayer/` or `version-v/` (add "Fix link" commits). + +## Step 12: When v is released (before merging the PR) + +- Revert the "Make v the latest version" commit (step 4), i.e. restore + `lastVersion: 'current'`, remove `includeCurrentVersion`, and make the + `current` entry in `versions` unconditional again. Commit as + "Make v the latest version". +- Merge the v.0.0 release-notes PR (created by the bot) into this branch, + and update both changelogs so the `.0.0` entry only lives in + `theoplayer/changelog.md` and the v changelog stays at `.x`. +- Update `sidebarsTheoplayer.ts` API reference links and remaining + `/theoplayer/v/api-reference/` links in other doc trees to `v` + (see step 8). +- **Fix links to the v migration guides**: the `.0` release notes in + both `theoplayer/changelog.md` and + `theoplayer_versioned_docs/version-v/changelog.md` link to the + migration guides; point them at the versioned docs, e.g. + `/theoplayer/getting-started/sdks/web/migrating-to-theoplayer-/` → + `/theoplayer/v/getting-started/sdks/web/migrating-to-theoplayer-/`. + This must happen **after** the flip to `lastVersion: 'current'` — while + v is still the latest version, its docs are served at `/theoplayer/` + without the `/v/` prefix, so these links would break the build. +- Ensure the platform teams have filled in the migration guides (Web, Android, + iOS, Roku) with the real breaking changes. + +## PR description + +Use the same summary as the reference PRs: + +> This PR moves the v docs to `/theoplayer_versioned_docs/version-v`, +> and prepares `/theoplayer` to contain the v docs.