# SemVer Bumping Rules for Garden Skills: The Complete Contributor Guide

> Learn SemVer bumping rules for Garden Skills. Discover when to use patch, minor, or major version bumps for typo fixes, workflow changes, and breaking updates in this contributor guide.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: best-practices
- Published: 2026-09-01

---

**Garden Skills enforces strict Semantic Versioning where typo fixes require patch bumps, workflow changes require minor bumps, and breaking changes like renamed skills require major bumps.**

Each skill in the Garden Skills repository operates as an independent package with its own [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) file that declares the current version. When contributing changes, understanding the specific SemVer bumping rules ensures your releases align with the automated validation in the `release-skill` GitHub Action.

## SemVer Categories and Bump Rules

The contribution guidelines in [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) define exactly which changes trigger each version component increment.

### Patch Bumps (x.y.z → x.y.(z+1))

**Patch** bumps cover backward-compatible, non-functional edits that do not alter execution flow. Apply a patch increment when you fix typos, add new optional references, or make micro-edits to [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md). These changes maintain full compatibility with existing consumers.

### Minor Bumps (x.y.z → x.(y+1).0)

**Minor** bumps signal added functionality or restructuring that does not break existing implementations. Trigger a minor version increment when you modify workflows in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md), restructure the `references/` directory, or introduce new required steps. Consumers receive new capabilities without forced migration.

### Major Bumps (x.y.z → (x+1).0.0)

**Major** bumps denote breaking changes requiring downstream users to adjust their code. Increment the major version when you rename a skill, remove files, or modify front-matter fields in ways that break dependent tooling. These releases explicitly signal incompatibility with previous versions.

## Automated Release Validation

The repository's CI pipeline automatically validates every release through the `release-skill` GitHub Action. When you push a tag, the action compares the tag version against the version declared in the skill's [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json). If the versions drift—for example, a tag requesting `1.1.0` while the manifest remains at `1.0.0`—the CI fails and blocks the release. This enforcement mechanism prevents version mismatches and ensures the [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) always reflects the released state.

## Manual Version Bumping Examples

When preparing a release manually, update the `version` field in your skill's [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) and create a matching git tag.

Bump a **patch** version for typo fixes:

```bash
jq '.version = "1.0.1"' skills/web-design-engineer/manifest.json > tmp.json && mv tmp.json skills/web-design-engineer/manifest.json
git commit -am "chore(web-design-engineer): bump patch to 1.0.1"
git tag web-design-engineer-v1.0.1
git push origin main web-design-engineer-v1.0.1

```

Bump a **minor** version for workflow changes:

```bash
jq '.version = "1.1.0"' skills/web-design-engineer/manifest.json > tmp.json && mv tmp.json skills/web-design-engineer/manifest.json
git commit -am "feat(web-design-engineer): bump minor to 1.1.0"
git tag web-design-engineer-v1.1.0
git push origin main web-design-engineer-v1.1.0

```

Bump a **major** version for breaking changes:

```bash
jq '.version = "2.0.0"' skills/web-design-engineer/manifest.json > tmp.json && mv tmp.json skills/web-design-engineer/manifest.json
git commit -am "refactor(web-design-engineer): bump major to 2.0.0"
git tag web-design-engineer-v2.0.0
git push origin main web-design-engineer-v2.0.0

```

## Helper Scripts and Automation

Most contributors use the interactive `npm run release` script instead of manual edits. This script automatically detects the required bump type based on your changes and executes the commit and tag operations while respecting the classification rules from [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md). Alternative npm scripts defined in [`package.json`](https://github.com/ConardLi/garden-skills/blob/main/package.json) include `release:dry` for testing workflows without creating tags, and `readme:sync` for updating documentation.

After any release, the `scripts/release/update-readme.mjs` script automatically updates the "Download" links in the main README to reflect the new versions.

## Key Files in the Versioning System

- **[`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md)** — Contains the full versioning policy, release workflow description, and troubleshooting guide for CI failures.
- **[`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json)** (per-skill) — Stores the current version for each skill; serves as the source of truth for the `release-skill` validation.
- **`scripts/release/update-readme.mjs`** — Auto-updates download links in the main README after successful version bumps.
- **[`package.json`](https://github.com/ConardLi/garden-skills/blob/main/package.json)** — Defines the npm scripts (`release`, `release:dry`, `readme:sync`) that automate SemVer enforcement.

## Summary

- Garden Skills treats every skill as an independent package with isolated versioning tracked in individual [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) files.
- **Patch** bumps cover typo fixes, optional reference additions, and micro-edits to documentation.
- **Minor** bumps cover workflow changes in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md), `references/` restructuring, and new required steps.
- **Major** bumps cover breaking changes including skill renames, file removals, and breaking front-matter modifications.
- The `release-skill` GitHub Action enforces strict alignment between git tags and [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) versions, failing CI on any mismatch.

## Frequently Asked Questions

### What happens if my git tag version doesn't match the manifest.json version?

The `release-skill` GitHub Action will fail the CI pipeline and block the release from publishing. You must correct either the tag or the [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) version so they align exactly before pushing again, as documented in the troubleshooting section of [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md).

### Can I manually edit the version in manifest.json?

Yes, you can manually update the version field using tools like `jq` or a text editor, but most contributors prefer the `npm run release` script which handles version detection and bumping automatically based on your change classification.

### How do I know if my change requires a major version bump?

Any modification that breaks existing consumer implementations—such as renaming the skill directory, removing required files, or modifying front-matter fields that downstream tools depend on—requires a major bump according to the [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) guidelines.

### Does Garden Skills use a single version for the entire repository?

No. Each skill maintains its own independent version in its respective [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) file, allowing individual skills to evolve at different rates without affecting the global repository state or forcing monolithic version increments.