Docs

Flexprice Docs — Changelog Skill

Generate and directly write weekly changelog entries for Flexprice into docs/changelog.mdx, following the exact structure and editorial voice of the existing file.

Repo Locations

All repos live at /Users/tsage/Desktop/flexprice/:

The changelog file is at:

/Users/tsage/Desktop/flexprice/flexprice-docs/docs/changelog.mdx

Step-by-step Workflow

1. Determine the Date Range

Ask the user (or infer from context) what time window to cover. Typical cases:

• Weekly: last 7 days from today
• Specific range: "after March 30th through April 6th"

The changelog label date is the end date of the range (e.g., April 6th 2026).

2. Gather Raw Material

IMPORTANT: Use git -C <path> to run git from outside the repo directory. Do NOT cd into repos — shell state does not persist between commands.

# Backend — use upstream/develop (the canonical source of truth, NOT origin/main which is the fork)
git -C /Users/tsage/Desktop/flexprice/flexprice log \
  remotes/upstream/develop \
  --format="%h %ad %s" --date=short \
  --since="YYYY-MM-DD" --until="YYYY-MM-DD" \
  --no-merges 2>&1 | head -100

# Frontend — use origin (flexprice-front is not a fork, origin IS upstream)
git -C /Users/tsage/Desktop/flexprice/flexprice-front log \
  --format="%h %ad %s" --date=short \
  --since="YYYY-MM-DD" --until="YYYY-MM-DD" \
  --no-merges 2>&1 | head -100

Key notes on the backend remote setup:

• origin = Tsage's personal fork (subratsahilgupta/flexprice) — often out of date, missing recent commits
• upstream = the real flexprice org repo — use remotes/upstream/develop for the authoritative commit history
• Always run backend git log against remotes/upstream/develop, not origin/main

If output is empty, try --all to check all branches:

git -C /Users/tsage/Desktop/flexprice/flexprice log --all \
  --format="%h %ad %s" --date=short \
  --since="YYYY-MM-DD" --until="YYYY-MM-DD" 2>&1 | head -50

Run both backend and frontend queries in parallel (single message, two tool calls) for speed.

3. Cross-Reference Against Prior Changelog

Before writing, read the current top entry in changelog.mdx to avoid duplicating anything already published. Use the Read tool — anything already in the most recent <Update> block is off-limits.

4. Categorize Changes

Every commit goes into one of these buckets:

Skip entirely (do not include):

• Internal testing suite additions (integration test suites, testutil updates)
• WIP commits, xyz, wip, design spec docs
• CI/CD pipeline plumbing with no user-facing impact
• SDK README-only changes with no feature content

A typical entry has 3–6 major features and then the accordion section. Only include accordion sections that have content.

5. Deep-Dive Into Major Features

For each major feature, read source code to understand what was built — commit messages alone are not enough.

flexprice/internal/api/         → HTTP handlers, request/response structs
flexprice/internal/service/     → Business logic, orchestration
flexprice/internal/domain/      → Domain models, enums, constants
flexprice/ent/schema/           → Database schema (Ent ORM)
flexprice/internal/temporal/    → Background workflow definitions
flexprice-front/src/pages/      → Dashboard page components
flexprice-front/src/components/ → Shared UI components
flexprice-front/src/api/        → API client hooks and types
flexprice-docs/docs/            → Existing documentation pages
flexprice-docs/images/docs/     → Screenshots for changelog

• Check for screenshots in flexprice-docs/images/docs/ — if relevant images exist, include them in a <Frame>
• Check for existing docs — look in flexprice-docs/docs/ for a matching page; if found, link it with a <Card>

6. Write the Changelog Entry

Read references/changelog.md for the full annotated MDX template. Structural summary:

<Update label="Month Xth YYYY">
  ## Feature Heading 1

  Brief 1-2 sentence description.

  * **Sub-feature**: Detail
  * **Sub-feature**: Detail

  <br />

  <Frame>
    <img src="/images/docs/..." alt="..." style={{ borderRadius: '0.5rem' }} />
  </Frame>

  <br />

  <Card icon="book-open" horizontal={true} href="/docs/..." title="Feature - Documentation" />

  <br />

  ## Feature Heading 2

  Description.

  * **Label**: Detail

  <br />

  **Other changes**

  <AccordionGroup>
    <Accordion title="Improvements">
      * Bullet
    </Accordion>

    <Accordion title="Fixes">
      * Bullet
    </Accordion>

    <Accordion title="API">
      * Bullet
    </Accordion>
  </AccordionGroup>
</Update>

Formatting rules:

1. Date label: <Update label="Month Xth YYYY"> with ordinal suffixes (1st, 2nd, 3rd, 4th…23rd, 24th…30th, 31st)
2. ## headings for each major feature — never # or ###
3. Description: 1-2 sentences, neutral or second-person voice ("Subscriptions now support…")
4. Bullets: * **Bold label**: Description — every bullet starts with a bolded label
5. <br /> between every section (after bullets, after Frame, after Card, before "Other changes")
6. Images: <Frame><img src="..." alt="..." style={{ borderRadius: '0.5rem' }} /></Frame>
7. Cards: icon "book-open" for docs, "code" for API reference; always horizontal={true}
8. Accordion bullets: use * (not -), 6-space indent inside the <Accordion> tag
9. 2-space indentation throughout the <Update> block
10. No marketing words: skip "exciting", "powerful", "seamless" — just describe what it does

7. Directly Write to the Changelog File

Do NOT save to a separate staging file. Write directly to changelog.mdx by prepending the new <Update> block right after the frontmatter --- line (line 6), before the first existing <Update>.

Use the Edit tool:

• old_string: the closing --- of the frontmatter + blank line + opening of the PREVIOUS top <Update> tag (e.g., ---\n\n<Update label="March 30th 2026">)
• new_string: ---\n\n + new <Update> block + \n\n<Update label="March 30th 2026">

Verify by reading the first ~100 lines of the file after saving.

8. Check for Broken Links

Before opening a PR, run the Mintlify broken-links checker from the docs repo root:

cd /Users/tsage/Desktop/flexprice/flexprice-docs && mint broken-links

• If it passes cleanly — proceed to the PR step.
• If it reports broken links — fix every broken link in the changelog entry you just wrote, then re-run until clean. Do not open a PR with broken links.

9. Open a PR Branched from Upstream Main

The flexprice-docs repo has two remotes:

• upstream = the production repo (flexprice/flexprice-docs) — always branch from here

cd /Users/tsage/Desktop/flexprice/flexprice-docs

# Fetch latest production main
git fetch upstream
git checkout upstream/main
git checkout -b changelog/<LABEL>   # e.g. changelog/May-11th-2026

# Stage and commit
git add docs/changelog.mdx
git commit -m "docs(changelog): add weekly entry for <LABEL>"

# Push to origin and open PR against upstream/main
git push origin changelog/<LABEL>
gh pr create \
  --title "docs(changelog): <LABEL>" \
  --base main \
  --body "Weekly changelog entry covering <SINCE> → <UNTIL>."

The branch name is always changelog/<LABEL> where <LABEL> matches the <Update> label exactly — e.g. changelog/May-11th-2026.

Return the PR URL to the user.

Editorial Voice

• Neutral or second-person: "Subscriptions now support…" or "You can now configure…" — not "We added…"
• Concise: One to two sentences per description. Every word earns its place.
• Technical but accessible: Name the mechanism (API endpoint, config field, UI component) and the user benefit
• Present tense: "Invoices now show…" not "We've added…" or "Invoices will show…"
• No fluff: Skip "exciting", "powerful", "seamless", "robust"

Reference Files

Read references/changelog.md for the full annotated MDX template with real examples from the existing changelog, inline comments explaining every section, and integration instructions.