Skip to content

Commit b71fd41

Browse files
committed
Docs: pin every in-repo file link to a release tag instead of main
Links into blob/main break whenever a file moves — this migration being the proof — while tag-pinned links stay valid forever because tags are immutable. All six in-repo main-branch file references (the ThemeObject JSDoc pointer and five tailwind-merge doc links in the vite package docs) now pin v3.6.0 with its pre-monorepo paths: that is the newest tag whose tree actually contains the files, so the links work today and keep working after the merge, unlike the main-based packaged paths they replace, which would only have become valid at merge time. AGENTS.md gains the standing rule: relative links within the repo, and where a link must be absolute (published docs, JSDoc, release notes), pin it to the latest release tag containing the file. The release guide gains the matching follow-up so it isn't forgotten: before @tailwind-merge/vite's first release, bump its docs' pinned tailwind-merge links from v3.6.0 to the freshly released tailwind-merge@<version> tag with packages/tailwind-merge/ paths, matching the version the plugin actually requires.
1 parent ee29441 commit b71fd41

6 files changed

Lines changed: 8 additions & 6 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ Required when relevant:
7474
2. Update `AGENTS.md` whenever repository-wide agent workflow, repo conventions, required commands, or high-level guardrails change.
7575
3. Update the relevant file in `agents/` whenever specialized architecture, workflow, CI, release, or testing guidance changes.
7676
4. Do not regenerate the READMEs during normal development. The library `README.md` and the marked section of the repo-level `README.md` are intentionally generated as part of the version/release flow so visitors are routed to docs for the latest release.
77+
5. Never reference repo files through `blob/main`/`raw/main`/`tree/main` URLs — they break whenever a file moves. Within the repo use relative links; where a link must be absolute (published docs, JSDoc, release notes), pin it to the latest release tag whose tree contains the file (e.g. `blob/v3.6.0/docs/...`, `blob/[email protected]/packages/tailwind-merge/docs/...`).
7778

7879
Definition of done for every PR/change:
7980

‎agents/release-workflow.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ The tag and version-commit format comes from each package's `.npmrc` (`tag-versi
3030
- A PR touching both packages appears in both drafts — correct, since both releases ship it.
3131
- A PR touching neither package directory (repo infrastructure, CI, root docs) appears in no draft; mention it by hand in a changelog if it matters to users.
3232
- First namespaced release per package: `tag-prefix` matches no existing release, so the draft's proposed version is wrong. Set the tag name and title by hand when publishing (for example `[email protected]` following `v3.6.0`), and write the Full Changelog compare line manually (`[email protected]`).
33+
- Before the first `@tailwind-merge/vite` release: its docs pin tailwind-merge doc links to the newest tag containing them (currently `v3.6.0` with pre-monorepo paths); bump them to the freshly released `tailwind-merge@<version>` tag with `packages/tailwind-merge/` paths so the published plugin docs reference the tailwind-merge version they actually require.
3334
- The autolabeler section lives only in the tailwind-merge config; labels are repo-wide.
3435

3536
## Publishing

‎packages/tailwind-merge/src/lib/types.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ type NoInferString<T extends string> = T extends infer S ? S & string : never
205205
* If you want to use a scale that is not supported in the `ThemeObject` type,
206206
* consider using `classGroups` instead of `theme`.
207207
*
208-
* @see https://github.com/dcastil/tailwind-merge/blob/main/packages/tailwind-merge/docs/configuration.md#theme
208+
* @see https://github.com/dcastil/tailwind-merge/blob/v3.6.0/docs/configuration.md#theme
209209
* (the list of supported keys may vary between `tailwind-merge` versions)
210210
*/
211211
export type DefaultThemeGroupIds =

‎packages/vite/docs/api-reference.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,15 +29,15 @@ The stable import surface. While Vite runs, it serves the module generated from
2929

3030
### `twMerge`
3131

32-
The star of the show — [tailwind-merge's `twMerge`](https://github.com/dcastil/tailwind-merge/blob/main/packages/tailwind-merge/docs/api-reference.md#twmerge), configured for your theme.
32+
The star of the show — [tailwind-merge's `twMerge`](https://github.com/dcastil/tailwind-merge/blob/v3.6.0/docs/api-reference.md#twmerge), configured for your theme.
3333

3434
### `getConfig`
3535

3636
Returns the generated configuration object, freshly built per call. Useful for composing with wrapper libraries or inspecting what was generated.
3737

3838
### `extendTailwindMerge`
3939

40-
Like [tailwind-merge's `extendTailwindMerge`](https://github.com/dcastil/tailwind-merge/blob/main/packages/tailwind-merge/docs/api-reference.md#extendtailwindmerge), but it extends **your generated configuration** instead of the default one — which is what you want when adding class groups that don't come from your CSS:
40+
Like [tailwind-merge's `extendTailwindMerge`](https://github.com/dcastil/tailwind-merge/blob/v3.6.0/docs/api-reference.md#extendtailwindmerge), but it extends **your generated configuration** instead of the default one — which is what you want when adding class groups that don't come from your CSS:
4141

4242
```ts
4343
import { extendTailwindMerge } from '@tailwind-merge/vite/runtime'
@@ -53,7 +53,7 @@ const customTwMerge = extendTailwindMerge<'text-style'>({
5353

5454
### `twJoin`, `createTailwindMerge`, `mergeConfigs`, `validators`
5555

56-
Re-exported unchanged from tailwind-merge, so customization never requires a direct tailwind-merge dependency. See the [tailwind-merge API reference](https://github.com/dcastil/tailwind-merge/blob/main/packages/tailwind-merge/docs/api-reference.md).
56+
Re-exported unchanged from tailwind-merge, so customization never requires a direct tailwind-merge dependency. See the [tailwind-merge API reference](https://github.com/dcastil/tailwind-merge/blob/v3.6.0/docs/api-reference.md).
5757

5858
### Types
5959

‎packages/vite/docs/versioning.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,4 @@ This package follows [SemVer](https://semver.org), with the pre-1.0 reading spel
77
- The stable surface the versioning promises apply to is the **plugin's options** and the **`@tailwind-merge/vite/runtime` exports**. Everything else — the shape of the generated module, the internal `/tailwind-merge` subpath, the config-generation machinery — is internal and may change in any release.
88
- The bundled tailwind-merge version is an implementation detail: the plugin upgrades it deliberately, and generated code and runtime always ship in lockstep, so they cannot drift apart.
99

10-
Once 1.0.0 ships, breaking changes will only happen in major releases, following the same practice as [tailwind-merge's versioning](https://github.com/dcastil/tailwind-merge/blob/main/packages/tailwind-merge/docs/versioning.md).
10+
Once 1.0.0 ships, breaking changes will only happen in major releases, following the same practice as [tailwind-merge's versioning](https://github.com/dcastil/tailwind-merge/blob/v3.6.0/docs/versioning.md).

‎packages/vite/docs/what-is-it-for.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ The standalone tailwind-merge package can't know *your* theme, so its default co
66

77
- A custom font size `--text-huge: 2.5rem` produces `text-huge`, which the default config misreads as a text **color** — so `twMerge('text-huge text-sm')` keeps both classes and your element gets an ambiguous font size ([tailwind-merge#684](https://github.com/dcastil/tailwind-merge/issues/684)).
88
- Whole namespaces the default config doesn't model — `--z-index-*`, `--border-width-*`, utility-specific colors like `--text-color-*` — silently fall through to wrong groups.
9-
- The manual fix is [configuring tailwind-merge by hand](https://github.com/dcastil/tailwind-merge/blob/main/packages/tailwind-merge/docs/configuration.md) and keeping that configuration in sync with your theme forever.
9+
- The manual fix is [configuring tailwind-merge by hand](https://github.com/dcastil/tailwind-merge/blob/v3.6.0/docs/configuration.md) and keeping that configuration in sync with your theme forever.
1010

1111
This plugin removes the whole problem class. At dev-server start and at build time, it loads your CSS through Tailwind's own APIs — the same resolution your real build performs, including theme overrides, resets, `@utility`, `@plugin`, `@config`, and prefixes — and generates a tailwind-merge configuration that matches it exactly. Custom utilities even get conflict inference: a `btn` utility that sets padding will correctly override an earlier `p-4`.
1212

0 commit comments

Comments
 (0)