markdown-studio-release-prep

Markdown Studio Release Prep

Goal

Bring this repository to a release-ready handoff state without performing the final human polish or Marketplace publish.

Stop before actions that should remain human-owned:

• Do not run vsce publish unless the user explicitly asks for publishing.
• Do not create or push the release tag until changelog, package version, tests, package output, and release impact are explained to the user and the user explicitly approves tagging.
• Do not rewrite the final marketing copy beyond factual release-note cleanup unless requested.

Release Handoff Definition

The handoff is ready when:

• Working tree is clean or only intentionally generated local artifacts are ignored.
• package.json version matches the intended release version.
• CHANGELOG.md has the intended version/date section and no release content stranded under Unreleased.
• examples/demo.pdf is committed when regenerated by release verification.
• @vscode/vsce is not stale enough to emit package warnings during npm run package.
• Verification commands have passed or failures are clearly documented.
• dist/markdown-studio-local-<version>.vsix exists from the latest package run.
• The current commit is pushed to origin/main.
• Tag status is resolved clearly: existing tag verified, tag pending human confirmation, or tag created and pushed after confirmation.

Workflow

1. Inspect state:

   • git status --short --branch
   • node -p "require('./package.json').version"
   • git tag --sort=-v:refname | head -20
   • sed -n '1,80p' CHANGELOG.md

2. Reconcile release notes:

   • If Unreleased contains items intended for the release, move them into the target version section.
   • Use the actual release date.
   • Keep a blank ## [Unreleased] section only if useful for future work.

3. Verify version and tooling:

   • Confirm package.json and package-lock.json agree on the version.
   • If npm run package reports a stale @vscode/vsce, update the local devDependency and lockfile.
   • Keep dev reinstall warnings suppressed in scripts/dev/reinstall.sh rather than asking repeatedly about [DEP0169].

4. Run verification:

   • npm run test:ci
   • npm run test:demo-render
   • npm run test:local-only
   • npm run test:e2e
   • npm run package
   • npm audit --omit=dev --audit-level=high

5. Treat generated demo artifacts as release artifacts:

   • If verification regenerates examples/demo.pdf, stage and commit it with the release changes.
   • Do not repeatedly ask the user whether to include examples/demo.pdf; include it unless explicitly told not to.

6. Commit and push:

   • Review git diff --stat and key diffs.
   • Commit all intended release-prep changes with a concise message.
   • Push main to origin.

7. Tag confirmation and automation:

   • Report the exact release situation before asking for confirmation:
     • Intended version and tag name, for example v1.0.3.
     • Current commit SHA and whether it is pushed to origin/main.
     • Working tree status.
     • Verification status for tests, demo render, E2E, package, audit, and VSIX output.
     • Whether the tag already exists locally or on origin.
     • The effect of pushing the tag: .github/workflows/release.yml runs lint, unit, integration, and test:local-only, then builds the VSIX and creates the GitHub Release on v* tag push. If any check fails, no VSIX or release is produced.
   • If the tag already exists, verify it points to the intended commit. If it points elsewhere, stop and explain the mismatch.
   • If the tag is missing and all gates pass, ask for explicit human confirmation such as: May I create and push v<version> now?
   • After confirmation, create and push the tag automatically:
     • git tag v<version>
     • git push origin v<version>
   • Do not merely hand back tag commands unless the user asks to perform tagging manually.

8. Publish handoff:

   • Confirm the tag's Release workflow run succeeded (gh run list --workflow release.yml --limit 1). If it failed, do not publish: the full checks did not pass for that commit.
   • Before recommending or running Marketplace publish, verify the stored Marketplace token:
     • vsce verify-pat
   • If PAT verification fails, stop and explain the failure. Do not publish.
   • If PAT verification succeeds and tests/package are green, give the final publish command:
     • vsce publish
   • Run vsce publish only when the user explicitly authorizes Marketplace publishing after the PAT and release gates are green.
   • Leave final Marketplace publish decision to the human unless explicitly authorized.

Project-Specific Notes

• This repo publishes kino6.markdown-studio-local.
• Release workflow is tag-driven: .github/workflows/release.yml runs on v* tags.
• npm run package creates dist/markdown-studio-local-<version>.vsix.
• scripts/dev/reinstall.sh is used frequently; keep it quiet and deterministic for local validation.
• AGENTS.md is a repository agent note and must stay excluded from VSIX via .vscodeignore.