Skip to content

Commit 71f6a5c

Browse files
eandreeva-twreandreeva-twr
committed
Merge branch 'ADP-5877-NEW' into develop
# Conflicts: # .github/workflows/s3-deploy-development.yml # .github/workflows/s3-deploy-production.yml # .github/workflows/translate.yml # src/styles/global.css
2 parents 40790b0 + 36b3983 commit 71f6a5c

2,191 files changed

Lines changed: 10269 additions & 5171 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/update-whats-new/SKILL.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
---
2+
name: update-whats-new
3+
description: Use when adding a new monthly section to src/content/docs/release-notes/whats-new.mdx — gathers commits to main over a date range, identifies user-facing updates worth featuring, confirms scope with the user, then drafts the section in the existing style.
4+
---
5+
6+
# Update what's new
7+
8+
## Overview
9+
10+
Add a new monthly section to `src/content/docs/release-notes/whats-new.mdx` based on what landed on `main` during a user-specified period. The skill scopes the period, scans commits, classifies them into "include / question / skip", confirms with the user, drafts the section in the established style, and inserts it in the right chronological place.
11+
12+
The page advertises **user-visible updates** — new features, new SDK releases, new integrations, new tools, new platforms, new languages, major site improvements. It is not a changelog of every doc edit.
13+
14+
## When to use
15+
16+
- User says: "update what's new", "draft what's new for [month]", "add a what's new entry", "monthly what's new", or equivalent.
17+
- Filling in a missing month, even if not the most recent one.
18+
19+
## When NOT to use
20+
21+
- The user wants to edit an existing entry → use the `editor` skill instead.
22+
- The user wants a per-PR or per-commit changelog → not this skill.
23+
24+
## Workflow
25+
26+
### 1. Determine the date range
27+
28+
If the user specified a month/year (or any explicit range), use it. Convert to absolute ISO dates.
29+
30+
If not specified, ask both questions in one prompt using AskUserQuestion:
31+
- **Month**: January … December
32+
- **Year**: current year and previous year as options, plus "Other" for free-form
33+
34+
Default unit is a single calendar month — sections in the file are titled `## {Month} {Year}`. Only deviate if the user explicitly asks for a different range.
35+
36+
Convert the answer to `--since=YYYY-MM-01` and `--until=YYYY-MM-01` of the next month (exclusive). Example for March 2026: `--since=2026-03-01 --until=2026-04-01`.
37+
38+
### 2. Read current content to anchor on style
39+
40+
Read `src/content/docs/release-notes/whats-new.mdx` end to end. Note:
41+
- The exact bullet format (see "Style rules" below).
42+
- Which months already exist and their ordering (newest-first).
43+
- Which kinds of items appear — so you can match scope.
44+
45+
If a section for the target month already exists, stop and ask the user whether to append, replace, or rename to a different month.
46+
47+
### 3. Pull commits to main
48+
49+
Run from the repo root:
50+
51+
```bash
52+
git log --since=<start> --until=<end> --pretty=format:"%h|%s" --name-only main
53+
```
54+
55+
This gives commit hash, subject, and changed files for each commit. Keep the full list in working memory — you'll need files-changed to classify.
56+
57+
If the range is wide and the list is long (>~80 commits), batch the analysis but classify every commit.
58+
59+
### 4. Classify each commit
60+
61+
Apply the classifier below. Inspect both subject and changed files — subjects can be misleading.
62+
63+
#### Definitely include (highly likely to be a bullet)
64+
65+
A commit that adds or substantially documents a **user-visible** thing:
66+
67+
- **New feature article(s)** under `src/content/docs/**/*.mdx` introducing something users can now do (e.g., a new dashboard feature, a new analytics chart, a new integration). Look for added `.mdx` files (`A` in `git diff --name-status`) or large additions to existing ones.
68+
- **New SDK migration guide** (filename pattern `migration-to-*`).
69+
- **New integration guide** (filename patterns `ua-*`, `*-integration*`, payment provider guides, attribution guides).
70+
- **New tool, CLI, or AI-assistant guide** (`developer-cli`, `adapty-cursor*`, etc.).
71+
- **New language / locale** for the docs site (entire new directory under `src/locales/<locale>/`).
72+
- **Major doc-site capability** the reader will notice (dark mode, full-text search, redesigned navigation). Small UI polish does NOT count.
73+
- **New platform support** documented (e.g., Capacitor SDK going GA).
74+
75+
#### Worth questioning (present, but ask the user)
76+
77+
Things that are genuinely user-facing but might not clear the bar for this page:
78+
79+
- A new section added to an existing article (e.g., "Revenue override settings for TikTok") — could be a bullet on its own, could be folded into a broader entry, could be skipped.
80+
- A documentation restructure or rewrite of an existing topic.
81+
- A clarification of an SDK behavior that users were confused about.
82+
- New screenshots or examples for an existing article.
83+
- Anything where the commit message says "improve", "update", or "clarify" without naming a new capability.
84+
85+
State the trade-off when presenting these — why it might or might not deserve a bullet.
86+
87+
#### Skip (don't show to the user unless asked)
88+
89+
These are noise. Don't bring them up:
90+
91+
- `chore: update translations` and any commit touching only `src/locales/**` or `.hashes/**`. Localization is auto-translated on push to main.
92+
- Translation script / pipeline changes (`scripts/translate*`, `scripts/generate-*`).
93+
- Lockfile, dependency, or build-config changes (`package*.json`, `yarn.lock`, `astro.config*`, `tsconfig*`, `tailwind.config*`).
94+
- Component / styling changes that don't touch `src/content/docs/**` (`src/components/**`, `src/styles/**`, `src/css/**`).
95+
- Linter, CI, formatting, or tooling commits.
96+
- `minor CLAUDE.md update`, repo-internal docs (`README*`, `TECH_WRITERS_README*`, `.claude/**`).
97+
- Merge commits (`Merge remote-tracking branch …`, `Merge pull request …`) — analyze the commits they reference instead.
98+
- Typo fixes, broken-link fixes, image swaps with no new feature attached.
99+
- The "What's new — {month}" commit itself (don't recursively cite the very entry you replaced).
100+
101+
#### Tie-breakers
102+
103+
- A bullet on this page must answer: "What new thing can a developer do, see, or build?" If you can't answer that in one sentence, it goes in **question** or **skip**.
104+
- Group commits about the same feature into one bullet. Example: three commits adding FunnelFox + Google Ads + revenue-override across `ua-*.mdx` collapse into one or two bullets.
105+
- The same feature shipped across multiple SDKs goes in one bullet with `[iOS](slug) | [Android](slug) | …`-style links.
106+
107+
### 5. Present findings for confirmation
108+
109+
Output three lists in this order. For each item, give: a candidate bullet title, a one-line rationale, and the commit hash(es) it came from. Don't draft full bullets yet.
110+
111+
```
112+
**Recommended (X items)**
113+
- {Title} — {rationale}. Commits: {hash1}, {hash2}
114+
- ...
115+
116+
**Worth questioning (Y items)**
117+
- {Title} — {why this is borderline}. Commits: {hash}
118+
- ...
119+
120+
**Skipping (brief summary)**
121+
N translation chore commits, N build/config commits, N component-only commits.
122+
```
123+
124+
Then ask the user, in plain prose: "Shall I include all recommended? Any of the questioned to add or drop?"
125+
126+
Do not draft the section until the user has confirmed the final list. If the user names something not in the lists, double-check the commits — you may have classified it wrong.
127+
128+
### 6. Draft the section in the established style
129+
130+
Once the list is confirmed, **invoke the `editor` skill** to draft the bullets. Pass:
131+
- The confirmed list of items with commit hashes and the underlying article slugs.
132+
- The style rules (below).
133+
- The final placement instructions (Section 7).
134+
135+
Editor's review mode applies: it should write each bullet against the same STE / clarity bar the rest of the docs use, then check the result.
136+
137+
#### Style rules (from existing entries)
138+
139+
- Section heading: `## {Month} {Year}` — full month name, four-digit year, no punctuation.
140+
- Each bullet: `- **{Feature name}**: {1–2 sentences explaining what it is and why a developer cares}. [Learn more]({slug})`
141+
- Multi-platform feature: `[iOS]({ios-slug}) | [Android]({android-slug}) | [React Native]({rn-slug}) | [Flutter]({flutter-slug}) | [Unity]({unity-slug}) | [Kotlin Multiplatform]({kmp-slug}) | [Capacitor]({cap-slug})` — pipe-separated, no "Learn more" wrapper.
142+
- Anchored link: `[Learn more]({slug}#anchor)`.
143+
- Slugs are filename-based, no `.md`/`.mdx` extension, no folder path. To resolve: take the source `.mdx` filename, drop the extension. Example: `src/content/docs/version-3.0/ua-funnelfox.mdx` → `ua-funnelfox`. If the article defines a `customSlug` in its frontmatter, use that.
144+
- Plain English. No jargon for jargon's sake. Lead with the user-facing capability, not the implementation.
145+
- No images, no code blocks, no `:::callouts`, no nested bullets — single flat list under the heading.
146+
- One blank line between bullets. One blank line between the heading and the first bullet.
147+
148+
### 7. Insert in the correct chronological place
149+
150+
Months run **newest first**. Find the right spot:
151+
152+
- If the new month is more recent than every existing section → insert directly after the intro callout (the `:::note … :::` block), before the first existing `##` heading.
153+
- Otherwise → insert above the first section that's older than the new one.
154+
155+
Use the `Edit` tool. Verify with `Read` after the edit that:
156+
- The new heading appears exactly once.
157+
- The chronological order is preserved.
158+
- No existing section was modified.
159+
160+
### 8. Report
161+
162+
Tell the user, in 2–3 sentences:
163+
- Which month was added.
164+
- How many bullets were included.
165+
- A reminder that `src/locales/**` will be auto-translated on the next push to `main` (no manual edit needed).
166+
167+
## Quick reference
168+
169+
| Step | Tool | What you produce |
170+
|------|------|------------------|
171+
| Scope range | AskUserQuestion (if not given) | `--since`/`--until` ISO dates |
172+
| Read current file | Read | Style anchor + chronological order |
173+
| List commits | Bash (`git log`) | Hash + subject + files for each commit |
174+
| Classify | — | 3 lists: recommended / question / skip |
175+
| Confirm scope | Plain prose | User-approved bullet list |
176+
| Draft section | Skill (`editor`) | Bulleted MDX following Style rules |
177+
| Insert | Edit | Updated `whats-new.mdx` |
178+
| Verify | Read | Heading present once, order preserved |
179+
180+
## Common mistakes
181+
182+
- **Quoting commit subjects verbatim as bullet titles.** Subjects are written for engineers; bullet titles are written for developers reading docs. Rewrite from the user's perspective.
183+
- **Citing translation churn.** `chore: update translations` and `src/locales/**` edits are never user-facing — those locales are auto-generated. Skip silently.
184+
- **Citing the "What's new — {month}" commit itself.** Don't recursively include the entry that wrote the previous month.
185+
- **One bullet per commit.** A single feature often spans many commits and many platforms. Collapse them.
186+
- **Drafting before user confirms.** Section 5 is a hard gate. Don't write bullet copy until the user has signed off on the list.
187+
- **Wrong slug.** A bullet's link must resolve. The slug is the filename, not the folder path. Verify before committing the draft to disk.
188+
- **Inserting in the wrong place.** Newest-first ordering is non-obvious from the file alone — read all existing month headings first, then place.
189+
- **Editing `src/locales/**/whats-new.mdx`.** Never. Translations regenerate on push to `main`.
190+
- **Including UI / styling commits.** Component or CSS changes aren't features unless the reader notices a new capability (e.g., dark mode toggle).
191+
- **Skipping the editor skill.** The user asked for editor to draft so STE rules are applied — don't shortcut that.
192+
193+
## Red flags — STOP and ask
194+
195+
- The target month already has a section in the file.
196+
- The git range produces zero commits (date typo, branch typo, or repo not up to date — run `git fetch origin main` and try again).
197+
- A "Worth questioning" item turns out to map to a doc-only change with no user-facing feature behind it — drop it from the candidate list before presenting.
198+
- Commit history shows a feature shipped but the corresponding `.mdx` article isn't there yet — flag it; the entry can't link to a missing page.

‎.github/workflows/translate.yml‎

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ concurrency:
1919
jobs:
2020
translate:
2121
runs-on: ubuntu-latest
22-
timeout-minutes: 60
22+
timeout-minutes: 90
2323
permissions:
2424
contents: write
2525

@@ -29,17 +29,6 @@ jobs:
2929
# Need parent commit to compute the diff
3030
fetch-depth: 2
3131

32-
# Hashes are gitignored but must persist between runs so --incremental
33-
# only re-translates sections that actually changed within a file.
34-
# The key includes the commit SHA so each push creates a new entry;
35-
# restore-keys fetches the most recent previous entry as a fallback.
36-
- name: Restore translation hash cache
37-
uses: actions/cache@v4
38-
with:
39-
path: src/locales/*/.hashes
40-
key: translation-hashes-${{ github.sha }}
41-
restore-keys: translation-hashes-
42-
4332
- uses: actions/setup-node@v4
4433
with:
4534
node-version: '20'
@@ -67,7 +56,7 @@ jobs:
6756
if: steps.diff.outputs.files != ''
6857
env:
6958
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
70-
run: node scripts/translate.mjs --incremental --only-files "${{ steps.diff.outputs.files }}"
59+
run: node scripts/translate.mjs --incremental --batch --only-files "${{ steps.diff.outputs.files }}"
7160

7261
# Remove translated files and hash caches for deleted source content.
7362
# Sidebars are intentionally excluded: deleting a sidebar JSON is rare and

‎.gitignore‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,6 @@ yarn-error.log*
3333

3434
# Translation
3535
.translate-batch-id
36-
src/locales/zh/.hashes/
37-
src/locales/tr/.hashes/
38-
src/locales/ru/.hashes
3936

4037
# VSCode
4138
/.vscode/*

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ Translated versions of articles live in `src/locales/{locale}/` (e.g., `src/loca
5757

5858
| Component | Import required? | Usage |
5959
|-----------|-----------------|-------|
60-
| `ZoomImage` | Yes | `<ZoomImage id="file.png" width="700px" alt="..." />` |
60+
| `ZoomImage` | Yes | `<ZoomImage id="file.png" width="700px" alt="..." />` — add `float="right"` or `float="left"` to float image beside text |
6161
| `Tabs`/`TabItem` | Yes | `<Tabs groupId="platform"><TabItem value="ios" label="iOS">...</TabItem></Tabs>` |
6262
| `Details` | Yes | `<Details summary="Title">content</Details>` |
6363
| `InlineTooltip` | Yes | `<InlineTooltip tooltip="hover text">[link](page.md)</InlineTooltip>` |

0 commit comments

Comments
 (0)