Skip to content

Instantly share code, notes, and snippets.

@julrich

julrich/release.md

Last active June 12, 2026 11:33
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save julrich/6a3d949dc7a0ea6299030748d7032d2d to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save julrich/6a3d949dc7a0ea6299030748d7032d2d to your computer and use it in GitHub Desktop.
Download ZIP
Release 2.0.1
Raw
release.md

Release PRD: v2.0.1 (post-2.0.0 fixes)

Goal

Cut a patch release v2.0.1 of @kickstartds/telekom-salespartner-kit that bundles the 13 follow-up fixes landed on main after v2.0.0 (form-field behaviour and styling, header/footer regressions, missing icon/font, copy corrections). Produce all release artifacts (snapshots, diffs, changelog, per-module docs), publish to npm, integrate into the sibling website-toolkit repo.

Scope decisions (locked)

  1. Version: 2.0.1 — patch bump. All deltas are bugfixes / minor polish on top of the v2.0.0 markup baseline; no new public API, no intentional breaking change.
  2. Working tree: must be clean before release work starts (same pre-flight as v2.0.0).
  3. Baseline: v2.0.0. The v2.0.0 tag exists on origin, so scripts/release/previous-version.sh resolves the previous tag automatically. Revert the TEMP hardcode in scripts/release/postversion.sh (PREVIOUS_VERSION="v1.2.0") back to the script invocation before running yarn version.
  4. Release flow: manual yarn version + the existing postversion.sh hook (same as v2.0.0). Not using auto / release-it.
  5. Changelog scope — user-visible deltas vs. v2.0.0 only: same rule as v2.0.0, anchored on v2.0.0 instead of v1.2.0. The diffs in diffs/v2.0.1/ (v2.0.0 → v2.0.1) are the source of truth for what changed in the markup; commit messages are only a hint at why.
    • ❌ Internal refactors that net out to zero markup change.
    • ✅ Any DOM / class / attribute change present in diffs/v2.0.1/*.patch.
    • ✅ Visible behaviour change (e.g. hover state restored, font fixed) even if not captured by the static snapshot diff.

Commits in scope (13, since v2.0.0 on main)

Snapshot at PRD time; re-verify with git log v2.0.0..HEAD before Step 1.

  • fbbd2b4 chore: update documentation and changelogs
  • ff4c62d [enhancement] updated preview screenshots
  • 72407cc fix: add note to changelog about css and js
  • 2b33521 fix: update typo
  • fb6a612 fix: missing font in accordion label
  • c032576 fix: spacing between congstar and body text on Leistungen page
  • 7299ca0 fix: one more instance of spacing between congstar and body text
  • 2f5210f fix: missing icon in gk services
  • f1b2d26 fix: add legal notes from startpage to offers page
  • f130aad fix: footer visited and hover states for menu links
  • 0b4abff fix: form styles and behaviour (ODSTextField, ODSTextArea, text-field.client.js)
  • 270fa35 fix: responsive header font sizing
  • 5a0e12b fix: checkbox icon hover states

Touched component areas (from git diff --stat v2.0.0..HEAD -- src/):

  • accordion/ — AccordionComponent.tsx, accordion.client.js
  • footer/footer.scss
  • form-fields/checkbox/ — ODSCheckbox.tsx, checkbox.scss
  • form-fields/text-area/ — ODSTextArea.tsx, text-area.scss
  • form-fields/text-field/ — ODSTextField.tsx, text-field.client.js
  • header/header.scss
  • services/Services.stories.tsx
  • solutions/Solutions.stories.tsx
  • Page stories: Angebote.stories.tsx, Leistungen.stories.tsx, Service.stories.tsx

Expected diffs/v2.0.1/ candidates: Accordion, Footer, Header (responsive typography may or may not flip a static snapshot), text-field / text-area / checkbox form rendering, plus page stories that pulled in the Offers legal-notes addition / GK service icon / spacing tweaks.

Out of scope

  • Anything that would change shipped behaviour beyond the 13 commits listed above (no opportunistic refactors, no new modules, no ODS re-pin).
  • Re-running the v2.0.0 changelog filter — the v2.0.0 entry in docs/docs/changes/index.md stays as-is.
  • Re-generating diffs/v2.0.0/ or snapshots/v2.0.0/.

Pre-flight (must be green before step 1)

  • Working tree clean (git status empty).
  • On branch main, up to date with origin/main.
  • git fetch --tags → git tag --list 'v*' includes v2.0.0.
  • scripts/release/previous-version.sh v2.0.1 prints v2.0.0.
  • Revert the TEMP hardcode in scripts/release/postversion.sh so PREVIOUS_VERSION is computed via previous-version.sh again. Commit separately: chore(release): restore dynamic previous-version lookup.
  • yarn install clean, no peer-dep warnings.
  • yarn schema && rollup -c builds without TS errors.
  • yarn build-docs builds (docs changelog parses, no broken anchors except the known /modules/contact-request#v120-21082025 from v2.0.0).

Execution steps

Step 1 — Regenerate test snapshots on main

Smaller delta than v2.0.0, but same procedure. Run before bumping the version so postversion.sh captures the correct baseline.

  1. yarn schema && yarn build
  2. yarn markup — regenerates src/components/*/__snapshots__/*.snap (vitest). Review diffs; expect changes in accordion, form-fields, page stories touched by the 13 commits.
  3. yarn test — regenerates __snapshots__/*.png. Review the changed subset visually (form fields, header at narrow viewport, accordion label, footer link states, checkbox hover, GK services icon).
  4. Optional: yarn create-component-previews to refresh static/img/screenshots if visually changed (the ff4c62d commit already refreshed them — only re-run if Step 2/3 surfaces further visual deltas).
  5. Commit: chore(release): regenerate snapshots for v2.0.1.

Acceptance: yarn markup green, no uncommitted snapshot files.

Step 2 — Bump version

yarn version --new-version 2.0.1

postversion (after the TEMP hardcode revert in pre-flight) automatically:

  • Runs scripts/release/postversion.sh v2.0.1, which:
    • save-snapshots.sh v2.0.1 → writes snapshots/v2.0.1/*.snap.html and *.snap.cjs.
    • generate-snapshot-patches.sh v2.0.0 v2.0.1 → writes diffs/v2.0.1/<Component>-Beispiel.snap.html.patch per module that changed. Patches are generated against the normalized snapshot via scripts/release/normalize-html-attrs.mjs (Strategy 3 attr order).
  • git add . && git commit --amend --no-edit folds artifacts into the version commit.
  • git tag -f v2.0.1 retags.

Acceptance: snapshots/v2.0.1/ populated, diffs/v2.0.1/ populated (may be small or empty for some modules), HEAD is the version-bump commit, v2.0.1 tag points at it.

Step 3 — Review generated diffs

Inspect every diffs/v2.0.1/*.snap.html.patch. Expect a much smaller set than v2.0.0. The diff list drives:

  • Which modules need a new ### v2.0.1 block in their .mdx.
  • Which modules need a bullet under ✏️ Markup in the changelog.

For each patch decide:

  • Real markup change → document in module + changelog.
  • Whitespace-only / attribute-reorder-only → squelch from changelog (still keep the patch file). The normalizer should have eliminated most reorder noise already; remaining tiny patches are most likely meaningful.

If a fix is behaviour-only (e.g. hover state CSS) with no snapshot diff, document under 🐛 Bugfixes without a Markup subsection.

Step 4 — Write changelog entry

Edit docs/docs/changes/index.md, prepending a ## v2.0.1 (<DD.MM.YYYY>) block above v2.0.0. Match the structure used by v2.0.0.

Filter rule (per Scope decision 5): only include items where the v2.0.1 output differs from the published v2.0.0 output.

Sections (omit any with no entries):

  • ### 🐛 Bugfixes — primary section for this release. Expected bullets, grouped by module:
    • Hover/visited states für Footer-Menü-Links wiederhergestellt (Footer)
    • Responsive Schriftgrößen im Header korrigiert (Header)
    • Fehlende Schriftauszeichnung im Accordion-Label ergänzt (Accordion)
    • Hover-State des Checkbox-Icons korrigiert (Contact Request)
    • Verhalten und Styling der Formularfelder (ODSTextField, ODSTextArea) korrigiert (Contact Request)
    • Fehlendes Icon in GK-Services ergänzt (Services)
  • ### ⌨️ Inhalt — only if content changed vs. v2.0.0. Expected bullets:
    • Rechtshinweise von der Startseite zusätzlich auf der Angebote-Seite ergänzt (Angebote)
    • Abstand zwischen congstar und Body-Text auf Leistungen-Seite korrigiert (Leistungen)
    • Typo korrigiert
  • ### ✏️ Markup — list of all modules with a non-empty patch in diffs/v2.0.1/, linking each to its module page anchor #v201-<DDMMYYYY>, plus the [hier zusammengefasst](/changes/2.0.1/) pointer only if Step 5 produces a release-summary page.

Source material for bullets, in priority order:

  1. diffs/v2.0.1/*.patch — authoritative markup deltas vs. v2.0.0.
  2. git diff v2.0.0..HEAD -- src/**/*.scss src/**/*.tsx src/**/*.client.js — visual / behavioural deltas vs. v2.0.0.
  3. The 13 commit messages — only as hints; never copy 1:1.

Tone: short German bullets, past participle / noun-phrase style, link each bullet to the affected module(s) via the /modules/<slug>#v201-<DDMMYYYY> anchor convention.

Note about consumer integration: only add the "CSS- und JavaScript-Assets aktualisieren" hint (present in the v2.0.0 entry) if dist/ actually changed in a breaking-for-integrators way. For a patch release this is usually still true (any JS/CSS shipped) — keep a short reminder line at the top of the release section.

Step 5 — Create release-summary page (conditional)

Only if diffs/v2.0.1/ contains one or more non-empty patches:

Create docs/docs/changes/2.0.1/index.mdx, mirroring docs/docs/changes/2.0.0/index.mdx:

  • import each diffs/v2.0.1/<Component>-Beispiel.snap.html.patch.
  • For each affected module, render a ## Module → ### [Name](...) block with bullet summary + <Accordion> wrapping <DiffViewer {...Patch} />.
  • Frontmatter: title: Markup v2.0.1.

If no patches survive Step 3 (i.e. all 2.0.1 changes are behaviour-only), skip this step and omit the hier zusammengefasst link from the changelog.

Step 6 — Update per-module docs

For each module in docs/docs/modules/*.mdx whose component has a diffs/v2.0.1/*.patch:

  1. Add import Patch201 from "../../../diffs/v2.0.1/<Component>-Beispiel.snap.html.patch"; alongside the existing Patch200 import.
  2. Insert a new ### v2.0.1 (<DD.MM.YYYY>) section under ## Markup, above the v2.0.0 section, with:
    • Bullet list of changes (1–2 bullets, copied from changelog source).
    • Alle Änderungen aus diesem Release [finden sich hier](/changes/2.0.1/). (only if Step 5 produced a summary page).
    • <Accordion> + <DiffViewer {...Patch201} />.

For modules touched only by a behaviour fix (no patch): add a brief ### v2.0.1 (<DD.MM.YYYY>) under the existing ### 🚀 Verbesserungen / introductory area of the module page if it would help integrators (e.g. "Hover-State der Footer-Links wiederhergestellt"); otherwise leave the module page untouched and surface the fix only in the changelog.

Pattern reference: docs/docs/modules/heroes.mdx ## Markup section.

Step 7 — Visual & a11y verification

  • yarn build-storybook && yarn chromatic — review and approve baselines. Diff set should be small and focused on the changed components.
  • a11y spot-check via Storybook addon-a11y on Header (responsive), Footer (focus/hover/visited), Accordion (label), Contact Request form (field validity + checkbox hover).
  • yarn build-docs and manual walkthrough of /changes/, /changes/2.0.1/ (if created), and every module page with a new v2.0.1 section. Spot-check /pages/angebote, /pages/leistungen, /pages/jobs, /pages/startseite for the content fixes.

Step 8 — Push

  • git push origin main (after Step 1–7 commits land locally).
  • git push origin v2.0.1 (after user confirmation — tag push is hard to reverse).
  • No PR needed; releases now land directly on main.

Step 9 — Publish to npm

After main is pushed:

  • yarn publish (triggers prepublishOnly → build + build-storybook).
  • Verify @kickstartds/telekom-salespartner-kit@2.0.1 on npm.

Step 10 — Integrate into website-toolkit

  • yarn build-docs
  • yarn integrate — copies docs-static/ into sibling ../website-toolkit/.
  • Commit + push in website-toolkit (separate repo, separate confirmation).

Artifacts produced

  • snapshots/v2.0.1/ — HTML + .snap.cjs baselines.
  • diffs/v2.0.1/*.snap.html.patch — per-component patches (expected subset, not all modules).
  • docs/docs/changes/index.md — prepended v2.0.1 entry above v2.0.0.
  • docs/docs/changes/2.0.1/index.mdx — release summary page (only if patches exist).
  • docs/docs/modules/*.mdx — per-module v2.0.1 Markup sections (only for changed modules).
  • package.json — version 2.0.1.
  • Git tag v2.0.1.
  • Published npm package @kickstartds/telekom-salespartner-kit@2.0.1.
  • Updated website-toolkit working copy.

Acceptance criteria

  • scripts/release/postversion.sh no longer hardcodes PREVIOUS_VERSION (TEMP comment removed, previous-version.sh call restored).
  • package.json version 2.0.1, tag v2.0.1 exists.
  • snapshots/v2.0.1/ committed; diffs/v2.0.1/ committed (may be a subset of v2.0.0).
  • docs/docs/changes/index.md has v2.0.1 entry above v2.0.0.
  • docs/docs/changes/2.0.1/index.mdx exists and renders if any non-empty patches exist.
  • Every module with a v2.0.1 patch has a ### v2.0.1 Markup section.
  • yarn build, yarn build-storybook, yarn build-docs all green.
  • yarn markup green; yarn test green; Chromatic baselines approved.
  • npm view @kickstartds/telekom-salespartner-kit@2.0.1 resolves.
  • website-toolkit updated and pushed.

Risks & mitigations

  • postversion.sh hardcode forgotten: pre-flight checklist makes reverting it a blocking step; verify by running scripts/release/previous-version.sh v2.0.1 and confirming it prints v2.0.0 before bumping.
  • Patch set turns out smaller than expected: some fixes are behaviour-only (hover states, JS interaction). That's fine — the changelog can carry the bugfix bullets without a Markup section / summary page. Don't pad diffs/v2.0.1/ artificially.
  • Form-field markup churn: the 0b4abff "form styles and behaviour" commit touched both TSX and client JS; expect non-trivial patches in ContactRequest-Beispiel.snap.html.patch. Budget extra review time there and confirm a11y didn't regress (label/for, aria-invalid).
  • Header responsive typography: viewport-dependent styles may not surface in the static markup snapshot at all. Rely on Chromatic and manual viewport sweep instead of patches for that fix.
  • Tag push is irreversible: same guard as v2.0.0 — explicit user confirmation before git push origin v2.0.1.

Rollback

  • Pre-tag-push: git tag -d v2.0.1 && git reset --hard v2.0.0 (followed by re-applying any non-release-bump commits as needed).
  • Post-tag-push, pre-publish: git push --delete origin v2.0.1 + reset.
  • Post-publish: npm deprecate the bad version; cut 2.0.2 with the fix. Do not unpublish.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment