Skip to content

Commit 6cf8792

Browse files
JamieMasonJamieMason
committed
docs(site): extend the version group docs
1 parent 2490744 commit 6cf8792

File tree

11 files changed

+551
-15
lines changed

11 files changed

+551
-15
lines changed

‎site/src/content/docs/status/differs-to-highest-or-lowest-semver-minor.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ description: Same-minor dependency version differs from preferred highest or low
1414

1515
The instance is updated to match the preferred MAJOR.MINOR target. The range selection follows this priority:
1616

17-
1. If instance has a [With Range](SEMVER_GROUP_WITH_RANGE) semver group with a safe preferred range → use preferred range
18-
2. If instance has no semver group and on-disk range is safe → preserve on-disk range
19-
3. Otherwise → force `~` (Same Minor policy wins over unsafe ranges)
17+
1. If instance has a [With Range](SEMVER_GROUP_WITH_RANGE) semver group with a preferred range which will not allow a version outside of the MAJOR.MINOR range to be installed, then use the preferred range
18+
2. If instance has no semver group and on-disk range does not allow a version outside of the MAJOR.MINOR range to be installed, then preserve the on-disk range
19+
3. Otherwise use `~` (Same Minor policy wins over unsafe ranges)
2020

2121
Safe ranges are `""` (Exact) and `~` (Patch).

‎site/src/content/docs/version-groups/banned.mdx‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@ import Packages from "@partials/group-config/packages.mdx";
1111
import { Badge } from "@astrojs/starlight/components";
1212
import Details from "@site/components/details.astro";
1313

14-
Find and remove dependencies which you've decided should never be used.
14+
Prevent dependencies you've decided should never be used. This helps teams enforce architectural decisions—for example, preventing accidental use of legacy packages, conflicting libraries, or packages that violate your security or licensing policy.
15+
16+
Use this when you want to actively prevent a dependency from appearing anywhere in your monorepo, or only in specific packages. When syncpack finds a banned dependency, it flags it as an issue that must be removed.
1517

1618
## Configuration
1719

@@ -49,3 +51,15 @@ This property activates this behaviour for a given Version Group.
4951
### packages <Badge text="Optional" variant="note" />
5052

5153
<Packages />
54+
55+
## Status Codes
56+
57+
These are all the issues that a {frontmatter.title} Version Group can find:
58+
59+
### Fixable
60+
61+
- [IsBanned](/status/is-banned)
62+
63+
### Suspect
64+
65+
- [RefuseToBanLocal](/status/refuse-to-ban-local)

‎site/src/content/docs/version-groups/highest-semver.mdx‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Highest Semver
3-
description: Keep all dependencies synchronized to the highest semver version found across your monorepo
3+
description: Keep all dependencies synchronised to the highest semver version found across your monorepo
44
---
55

66
import { Badge } from "@astrojs/starlight/components";
@@ -10,7 +10,7 @@ import DependencyTypes from "@partials/group-config/dependency-types.mdx";
1010
import SpecifierTypes from "@partials/group-config/specifier-types.mdx";
1111
import Label from "@partials/group-config/label.mdx";
1212

13-
Fix mismatched versions in this group by choosing the highest/newest semver version in use.
13+
Require all dependencies in this group to use the highest semver version found of all the instances where it is already installed in your monorepo. When versions differ, syncpack will align them to the highest one installed.
1414

1515
## Configuration
1616

@@ -33,3 +33,21 @@ Fix mismatched versions in this group by choosing the highest/newest semver vers
3333
### packages <Badge text="Optional" variant="note" />
3434

3535
<Packages />
36+
37+
## Status Codes
38+
39+
These are all the issues that a {frontmatter.title} Version Group can find:
40+
41+
### Valid
42+
43+
- [IsHighestOrLowestSemver](/status/is-highest-or-lowest-semver)
44+
- [SatisfiesHighestOrLowestSemver](/status/satisfies-highest-or-lowest-semver)
45+
46+
### Fixable
47+
48+
- [DiffersToHighestOrLowestSemver](/status/differs-to-highest-or-lowest-semver)
49+
50+
### Conflict
51+
52+
- [MatchConflictsWithHighestOrLowestSemver](/status/match-conflicts-with-highest-or-lowest-semver)
53+
- [MismatchConflictsWithHighestOrLowestSemver](/status/mismatch-conflicts-with-highest-or-lowest-semver)

‎site/src/content/docs/version-groups/ignored.mdx‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@ import SpecifierTypes from "@partials/group-config/specifier-types.mdx";
1111
import Label from "@partials/group-config/label.mdx";
1212
import Details from "@site/components/details.astro";
1313

14-
Have syncpack ignore the versions of these dependencies completely.
14+
Have syncpack ignore these dependencies completely.
15+
16+
Defining version groups for dependencies you know you can easily fix, followed by a catch-all Ignored Version Group as the last member of your `versionGroups` array is a good way to incrementally adopt syncpack.
1517

1618
## Configuration
1719

@@ -49,3 +51,11 @@ This property activates this behaviour for a given Version Group.
4951
### packages <Badge text="Optional" variant="note" />
5052

5153
<Packages />
54+
55+
## Status Codes
56+
57+
These are all the issues that a {frontmatter.title} Version Group can find:
58+
59+
### Valid
60+
61+
- [IsIgnored](/status/is-ignored)

‎site/src/content/docs/version-groups/lowest-semver.mdx‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Lowest Semver
3-
description: Keep all dependencies synchronized to the lowest semver version found across your monorepo
3+
description: Keep all dependencies synchronised to the lowest semver version found across your monorepo
44
---
55

66
import { Badge } from "@astrojs/starlight/components";
@@ -10,7 +10,7 @@ import DependencyTypes from "@partials/group-config/dependency-types.mdx";
1010
import SpecifierTypes from "@partials/group-config/specifier-types.mdx";
1111
import Label from "@partials/group-config/label.mdx";
1212

13-
Fix mismatched versions in this group by choosing the lowest/oldest semver version in use.
13+
Require all dependencies in this group to use the lowest semver version found of all the instances where it is already installed in your monorepo. When versions differ, syncpack will align them to the lowest one installed.
1414

1515
## Examples
1616

@@ -50,3 +50,21 @@ Must be set to `lowestSemver`.
5050
### packages <Badge text="Optional" variant="note" />
5151

5252
<Packages />
53+
54+
## Status Codes
55+
56+
These are all the issues that a {frontmatter.title} Version Group can find:
57+
58+
### Valid
59+
60+
- [IsHighestOrLowestSemver](/status/is-highest-or-lowest-semver)
61+
- [SatisfiesHighestOrLowestSemver](/status/satisfies-highest-or-lowest-semver)
62+
63+
### Fixable
64+
65+
- [DiffersToHighestOrLowestSemver](/status/differs-to-highest-or-lowest-semver)
66+
67+
### Conflict
68+
69+
- [MatchConflictsWithHighestOrLowestSemver](/status/match-conflicts-with-highest-or-lowest-semver)
70+
- [MismatchConflictsWithHighestOrLowestSemver](/status/mismatch-conflicts-with-highest-or-lowest-semver)

‎site/src/content/docs/version-groups/pinned.mdx‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,21 @@ The version specifier you would like to use, this can be anything supported by a
4949
### packages <Badge text="Optional" variant="note" />
5050

5151
<Packages />
52+
53+
## Status Codes
54+
55+
These are all the issues that a {frontmatter.title} Version Group can find:
56+
57+
### Valid
58+
59+
- [IsIdenticalToPin](/status/is-identical-to-pin)
60+
61+
### Fixable
62+
63+
- [DiffersToPin](/status/differs-to-pin)
64+
- [PinOverridesSemverRange](/status/pin-overrides-semver-range)
65+
- [PinOverridesSemverRangeMismatch](/status/pin-overrides-semver-range-mismatch)
66+
67+
### Suspect
68+
69+
- [RefuseToPinLocal](/status/refuse-to-pin-local)

‎site/src/content/docs/version-groups/same-minor.mdx‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Same Minor
3-
description: Keep dependencies synchronized within the same minor version range across your monorepo
3+
description: Keep dependencies synchronised within the same minor version range across your monorepo
44
---
55

66
import { Badge } from "@astrojs/starlight/components";
@@ -82,3 +82,25 @@ Setting a `preferVersion` loosens this requirement, but beware of dependencies w
8282
### packages <Badge text="Optional" variant="note" />
8383

8484
<Packages />
85+
86+
## Status Codes
87+
88+
These are all the issues that a {frontmatter.title} Version Group can find:
89+
90+
### Valid
91+
92+
- [IsNonSemverButIdentical](/status/is-non-semver-but-identical)
93+
- [SatisfiesSameMinorGroup](/status/satisfies-same-minor-group)
94+
95+
### Fixable
96+
97+
- [DiffersToHighestOrLowestSemverMinor](/status/differs-to-highest-or-lowest-semver-minor)
98+
- [SameMinorOverridesSemverRange](/status/same-minor-overrides-semver-range)
99+
- [SameMinorOverridesSemverRangeMismatch](/status/same-minor-overrides-semver-range-mismatch)
100+
- [SemverRangeMismatch](/status/semver-range-mismatch)
101+
102+
### Unfixable
103+
104+
- [SameMinorHasMajorMismatch](/status/same-minor-has-major-mismatch)
105+
- [SameMinorMismatch](/status/same-minor-mismatch)
106+
- [NonSemverMismatch](/status/non-semver-mismatch)

‎site/src/content/docs/version-groups/same-range.mdx‎

Lines changed: 44 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Same Range
3-
description: Keep dependencies synchronized to identical version ranges across your monorepo
3+
description: Ensure all semver ranges for a dependency overlap across your monorepo
44
---
55

66
import { Badge } from "@astrojs/starlight/components";
@@ -11,7 +11,33 @@ import SpecifierTypes from "@partials/group-config/specifier-types.mdx";
1111
import Label from "@partials/group-config/label.mdx";
1212
import Details from "@site/components/details.astro";
1313

14-
Relax syncpack to ensure that all versions have semver ranges which all satisfy each other, instead of having to be identical.
14+
Checks that every instance of a dependency uses a semver range that **overlaps** with every other instance in the group. Ranges don't need to be identical — they just need to share at least one version in common (ie. they _intersect_).
15+
16+
This is the loosest version group policy. It does **not** enforce identical versions — the default [Highest Semver](/version-groups/highest-semver) group does that. It does **not** enforce same minor versions — use [`sameMinor`](/version-groups/same-minor) for that.
17+
18+
:::caution
19+
`sameRange` only works with semver **ranges** like `^1.2.3`, `>=1.0.0`, or `~2.0.0`. Exact pinned versions like `1.0.0` and `1.0.1` are non-overlapping ranges — they will be flagged as mismatches because no single version satisfies both. If you want to enforce that exact versions share the same minor number, use [`sameMinor`](/version-groups/same-minor) instead.
20+
:::
21+
22+
#### When to use this
23+
24+
- **Peer dependencies** where different packages legitimately need different ranges, as long as a compatible version can be resolved
25+
- **Typed dependencies** (`foo` and `@types/foo`) that may move on different release cadences but must coexist
26+
27+
#### Examples
28+
29+
**Overlapping ranges** — at least one version satisfies both:
30+
31+
- `>=1.0.0` and `<=2.0.0` ✅ (versions 1.0.0–2.0.0 satisfy both)
32+
- `>=1.0.0` and `^1.2.3` ✅ (versions 1.2.3–1.x.x satisfy both)
33+
- `^1.0.0` and `~1.4.2` ✅ (versions 1.4.2–1.4.x satisfy both)
34+
35+
**Non-overlapping ranges** — no version exists in both:
36+
37+
- `>=1.0.0` and `<1.0.0` ✗
38+
- `~1.0.0` and `1.4.2` ✗ (`~1.0.0` covers 1.0.x, the exact version 1.4.2 is outside it)
39+
40+
Mismatches in a Same Range group are **unfixable** — syncpack cannot auto-fix them because it doesn't know which range should change. You'll need to resolve these manually.
1541

1642
## Configuration
1743

@@ -49,3 +75,19 @@ Choose the "sameRange" policy to apply this behaviour to a Version Group.
4975
### packages <Badge text="Optional" variant="note" />
5076

5177
<Packages />
78+
79+
## Status Codes
80+
81+
These are all the issues that a {frontmatter.title} Version Group can find:
82+
83+
### Valid
84+
85+
- [SatisfiesSameRangeGroup](/status/satisfies-same-range-group)
86+
87+
### Fixable
88+
89+
- [SemverRangeMismatch](/status/semver-range-mismatch)
90+
91+
### Unfixable
92+
93+
- [SameRangeMismatch](/status/same-range-mismatch)

‎site/src/content/docs/version-groups/snapped-to.mdx‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Snapped To
3-
description: Synchronize dependency versions to match those defined in a specific source package
3+
description: Synchronise dependency versions to match those defined in a specific source package
44
---
55

66
import { Badge } from "@astrojs/starlight/components";
@@ -11,7 +11,9 @@ import SpecifierTypes from "@partials/group-config/specifier-types.mdx";
1111
import Label from "@partials/group-config/label.mdx";
1212
import Details from "@site/components/details.astro";
1313

14-
Pin the version of all dependencies in this group to follow the versions used by the other packages named within the `snapTo` array.
14+
Synchronise versions by following a source package. Every dependency in this group will use the same version as defined in the packages you've designated via the `snapTo` array.
15+
16+
This is useful when certain packages within your monorepo are the source of truth for dependency versions. For example, if your main application package has been carefully tested with specific versions, you want all other packages to follow those same versions to ensure consistency and reduce the variables in your system.
1517

1618
## Configuration
1719

@@ -50,3 +52,26 @@ Pin the version of all dependencies in this group to follow the versions used by
5052
### packages <Badge text="Optional" variant="note" />
5153

5254
<Packages />
55+
56+
## Status Codes
57+
58+
These are all the issues that a {frontmatter.title} Version Group can find:
59+
60+
### Valid
61+
62+
- [IsIdenticalToSnapTarget](/status/is-identical-to-snap-target)
63+
- [SatisfiesSnapTarget](/status/satisfies-snap-target)
64+
65+
### Fixable
66+
67+
- [DiffersToSnapTarget](/status/differs-to-snap-target)
68+
69+
### Suspect
70+
71+
- [RefuseToSnapLocal](/status/refuse-to-snap-local)
72+
- [DependsOnMissingSnapTarget](/status/depends-on-missing-snap-target)
73+
74+
### Conflict
75+
76+
- [MatchConflictsWithSnapTarget](/status/match-conflicts-with-snap-target)
77+
- [MismatchConflictsWithSnapTarget](/status/mismatch-conflicts-with-snap-target)

‎skills/front-loading/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ Then explain the trade-offs if needed.
4949
Readers have a question in mind. Answer it in the first sentence.
5050

5151
**Bad (makes reader wait):**
52-
"Syncpack is a CLI tool built in Rust. It uses a configuration file in JSON format. The configuration file specifies rules for how to synchronize dependencies. These rules can be customized per workspace..."
52+
"Syncpack is a CLI tool built in Rust. It uses a configuration file in JSON format. The configuration file specifies rules for how to synchronise dependencies. These rules can be customized per workspace..."
5353

5454
Reader's question: "How do I configure Syncpack?" Buried in paragraph 3.
5555

0 commit comments

Comments
 (0)