Revision of readme and changeset for monorepo toolchain migration

Author: Jiří Fencl

.changeset/curly-books-knock.md

@@ -24,4 +24,8 @@
 "@merkur/cli": patch
 ---
 
-Migrate build and publish tooling from Lerna to NX and Changesets.
+Migrate monorepo build and publish tooling from Lerna to NX and Changesets.
+
+- **What** The internal monorepo toolchain for versioning and publishing all `@merkur/*` packages has been replaced. Lerna is removed; NX is used for task orchestration and Changesets is used for versioning and changelog generation.
+- **Why** Lerna's versioning model was difficult to maintain for independent package releases and offered limited caching. NX provides better incremental build support and task pipelines, while Changesets gives contributors a structured, PR-friendly workflow for describing and grouping version bumps.
+- **How** No changes required for consumers of `@merkur/*` packages — the published API is unaffected. Internal contributors should use `npm run changeset` to record changes and `npm run release` to publish new versions. See the CONTRIBUTING.md for detailed instructions on the new workflow.

README.md

@@ -42,6 +42,38 @@ We are using [Changesets](https://github.com/changesets/changesets) for versioni
 
 > **Note:** The release process is documented **only** in this root README. Any per-package README sections that still describe a Lerna/Conventional Commits–based release flow are outdated and should be ignored in favour of the instructions below.
 
+### Changeset format
+
+Each changeset file (`.changeset/*.md`) must follow this structure:
+
+**Frontmatter** — standard Changesets YAML listing affected package names and bump types (`patch`, `minor`, `major`).
+
+**First line after frontmatter** — a single brief sentence summarising the change. No heading, no bold, no trailing bullet — just a plain declarative sentence. This section is not required but helps to quickly understand the change when browsing the changesets.
+
+**Body** — three bullet points in this exact order, with no blank lines between them:
+
+- **What** One or more sentences describing what changed: which APIs, files, or behaviours were added, removed, or fixed. Make sublists if needed to break down complex changes, but keep each bullet point as a single paragraph.
+- **Why** One or more sentences explaining the motivation: why the change was necessary or beneficial.
+- **How** Migration steps for consumers or contributors. If no action is required, write exactly: `Nothing.`
+
+Additional rules:
+- Each bullet is a single paragraph — no nested lists, no code blocks inside a bullet.
+- Do not use headings (`##`, `###`) inside the body.
+- Code symbols (function names, paths, package names) use backtick inline code.
+
+Example:
+
+```markdown
+---
+"@merkur/example": minor
+---
+
+Add `createFoo` helper for simplified widget initialisation.
+
+- **What** New `createFoo(options)` export in `@merkur/example` wraps the low-level `initFoo` call and applies sensible defaults for `name` and `version`.
+- **Why** Every project was duplicating the same boilerplate to call `initFoo`; centralising it reduces setup friction and ensures consistent defaults.
+- **How** Replace direct `initFoo` calls with `createFoo({ name, version })`. The returned object is API-compatible, so no further changes are needed.
+```
 
 ### Release
 

packages/cli/README.md

@@ -40,7 +40,7 @@ Contribute to this project via [Pull-Requests](https://github.com/mjancarik/merk
 
 We are using [Changesets](https://github.com/changesets/changesets) for versioning and releasing. To add a changeset describing your changes, run `npm run changeset` from the root of the monorepo.
 
-> **Note:** The release process is documented in the [root README](https://github.com/mjancarik/merkur#release), which is the source of truth for all contribution and release guidelines.
+> **Note:** The release process and [changeset format](https://github.com/mjancarik/merkur#changeset-format) are documented in the [root README](https://github.com/mjancarik/merkur#contribution), which is the source of truth for all contribution and release guidelines.
 
 ---
 

packages/core/README.md

@@ -40,7 +40,7 @@ Contribute to this project via [Pull-Requests](https://github.com/mjancarik/merk
 
 We are using [Changesets](https://github.com/changesets/changesets) for versioning and releasing. To add a changeset describing your changes, run `npm run changeset` from the root of the monorepo.
 
-> **Note:** The release process is documented in the [root README](https://github.com/mjancarik/merkur#release), which is the source of truth for all contribution and release guidelines.
+> **Note:** The release process and [changeset format](https://github.com/mjancarik/merkur#changeset-format) are documented in the [root README](https://github.com/mjancarik/merkur#contribution), which is the source of truth for all contribution and release guidelines.
 
 ---
 

packages/create-widget/README.md

@@ -40,7 +40,7 @@ Contribute to this project via [Pull-Requests](https://github.com/mjancarik/merk
 
 We are using [Changesets](https://github.com/changesets/changesets) for versioning and releasing. To add a changeset describing your changes, run `npm run changeset` from the root of the monorepo.
 
-> **Note:** The release process is documented in the [root README](https://github.com/mjancarik/merkur#release), which is the source of truth for all contribution and release guidelines.
+> **Note:** The release process and [changeset format](https://github.com/mjancarik/merkur#changeset-format) are documented in the [root README](https://github.com/mjancarik/merkur#contribution), which is the source of truth for all contribution and release guidelines.
 
 ---
 

packages/integration-custom-element/README.md

@@ -40,7 +40,7 @@ Contribute to this project via [Pull-Requests](https://github.com/mjancarik/merk
 
 We are using [Changesets](https://github.com/changesets/changesets) for versioning and releasing. To add a changeset describing your changes, run `npm run changeset` from the root of the monorepo.
 
-> **Note:** The release process is documented in the [root README](https://github.com/mjancarik/merkur#release), which is the source of truth for all contribution and release guidelines.
+> **Note:** The release process and [changeset format](https://github.com/mjancarik/merkur#changeset-format) are documented in the [root README](https://github.com/mjancarik/merkur#contribution), which is the source of truth for all contribution and release guidelines.
 
 ---
 

packages/integration-react/README.md

@@ -40,7 +40,7 @@ Contribute to this project via [Pull-Requests](https://github.com/mjancarik/merk
 
 We are using [Changesets](https://github.com/changesets/changesets) for versioning and releasing. To add a changeset describing your changes, run `npm run changeset` from the root of the monorepo.
 
-> **Note:** The release process is documented in the [root README](https://github.com/mjancarik/merkur#release), which is the source of truth for all contribution and release guidelines.
+> **Note:** The release process and [changeset format](https://github.com/mjancarik/merkur#changeset-format) are documented in the [root README](https://github.com/mjancarik/merkur#contribution), which is the source of truth for all contribution and release guidelines.
 
 ---
 

packages/integration/README.md

@@ -40,7 +40,7 @@ Contribute to this project via [Pull-Requests](https://github.com/mjancarik/merk
 
 We are using [Changesets](https://github.com/changesets/changesets) for versioning and releasing. To add a changeset describing your changes, run `npm run changeset` from the root of the monorepo.
 
-> **Note:** The release process is documented in the [root README](https://github.com/mjancarik/merkur#release), which is the source of truth for all contribution and release guidelines.
+> **Note:** The release process and [changeset format](https://github.com/mjancarik/merkur#changeset-format) are documented in the [root README](https://github.com/mjancarik/merkur#contribution), which is the source of truth for all contribution and release guidelines.
 
 ---
 

packages/plugin-graphql-client/README.md

@@ -40,7 +40,7 @@ Contribute to this project via [Pull-Requests](https://github.com/mjancarik/merk
 
 We are using [Changesets](https://github.com/changesets/changesets) for versioning and releasing. To add a changeset describing your changes, run `npm run changeset` from the root of the monorepo.
 
-> **Note:** The release process is documented in the [root README](https://github.com/mjancarik/merkur#release), which is the source of truth for all contribution and release guidelines.
+> **Note:** The release process and [changeset format](https://github.com/mjancarik/merkur#changeset-format) are documented in the [root README](https://github.com/mjancarik/merkur#contribution), which is the source of truth for all contribution and release guidelines.
 
 ---
 

packages/plugin-http-cache/README.md

@@ -40,7 +40,7 @@ Contribute to this project via [Pull-Requests](https://github.com/mjancarik/merk
 
 We are using [Changesets](https://github.com/changesets/changesets) for versioning and releasing. To add a changeset describing your changes, run `npm run changeset` from the root of the monorepo.
 
-> **Note:** The release process is documented in the [root README](https://github.com/mjancarik/merkur#release), which is the source of truth for all contribution and release guidelines.
+> **Note:** The release process and [changeset format](https://github.com/mjancarik/merkur#changeset-format) are documented in the [root README](https://github.com/mjancarik/merkur#contribution), which is the source of truth for all contribution and release guidelines.
 
 ---