ams-semantic-versioning-pro
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 0
- Forks
- 1
03 SKILL.md 正文
Semantic Versioning Pro
Overview
Semantic versioning — MAJOR.MINOR.PATCH — is a contract with your consumers: given a version number, they know what kind of change to expect. MAJOR = breaking, MINOR = backward-compatible features, PATCH = backward-compatible fixes. The discipline isn't in the numbers — it's in honestly classifying changes and respecting what each bump promises.
The through-line: the version number is a promise — break it and you break trust, not just builds.
When to use
- Versioning a library, SDK, API, or package.
- Deciding whether a change is major, minor, or patch.
- Setting up automated versioning (changesets, semantic-release).
- Defining deprecation and breaking-change policies.
- Reviewing version bumps in releases.
Core concepts
- The contract. MAJOR: incompatible API changes. MINOR: new functionality, backward compatible.
PATCH: bug fixes, backward compatible. Consumers on
^1.2.3get minors and patches automatically — every bump is a promise about what won't break them. - What counts as breaking. Removing/renaming public APIs, changing signatures or return shapes, altering behavior consumers depend on, dropping supported platforms/versions, changing default behavior. When in doubt, it's breaking — consumers depend on more than you think.
- Public API surface, defined. Semver applies to the declared public API — document what's public (exported symbols, documented endpoints) vs internal. Undocumented internals changing isn't breaking; but if consumers use it, expect anger anyway. Be explicit.
- Zero-major special case.
0.x.y: anything may change; the API is unstable by declaration. Don't linger in 0.x for widely-used software — it's a signal, and prolonged 0.x erodes the signal's meaning. 1.0.0 declares stability intent. - Pre-releases and build metadata.
1.0.0-rc.1,2.0.0-beta.3— for soaking breaking changes before the major lands. Pre-releases don't satisfy normal ranges (^1.0.0won't take2.0.0-rc.1), which is exactly the safety you want. - Deprecation policy. Never break without warning: deprecate in a minor (with warnings/logs pointing to the migration), remove in the next major. Give consumers at least one full minor series to migrate — breaking-change timelines are a trust instrument.
Practical workflow
- Define the public API. Document what's covered by semver (and what isn't). For libraries: exported functions/types; for HTTP APIs: endpoints, fields, status codes, auth behavior.
- Classify every change. In each PR: breaking? → major; new compatible feature? → minor; fix only? → patch. Make classification part of review — it's a design decision, not bookkeeping.
- Automate the mechanics. Changesets (human-written, per-PR: patch/minor/major + description) or semantic-release (from conventional commits). Humans classify; machines bump and publish.
- Deprecate before removing. Minor release: add the new way, deprecate the old with warnings and migration docs. Next major: remove. Never surprise-break.
- Publish pre-releases for majors.
-rc.1weeks before the major; invite consumers to test; fix the fallout before the major lands. Majors are the highest-stakes releases — soak them. - Enforce in CI. Breaking-change detection (API diff tools:
cargo semver-checks,revapi,japicmp, public-API snapshots), and changelog entries matching the bump level.
Classification guide:
MAJOR (breaking):
- Remove/rename public function, class, endpoint, or field
- Change parameter types/order, return shapes
- Change default behavior consumers may rely on
- Drop support for a runtime/platform version
- Tighten validation (previously-accepted input now rejected)
MINOR (new, compatible):
- Add new function/endpoint/field (optional)
- Add new optional parameter
- Deprecate (without removing) existing API
- Performance improvements with identical behavior
PATCH (fix, compatible):
- Fix incorrect behavior to match documented contract
- Security fix with no API change
- Docs, internal refactoring, dependency updates
Common pitfalls
- Breaking in a minor. "It's a small change" — but it removed a field someone parsed. If any reasonable consumer could break, it's major. Err toward major.
- 0.x forever. A widely-depended
0.14.2where every minor breaks consumers — the version number lies about stability. Ship 1.0 when the API is used in production by others. - Patch bumps with behavior change. "Fixing" behavior consumers depended on (even if the old behavior was buggy) — that's a breaking change wearing a patch costume. Hyrum's law: all observable behaviors will be depended on.
- No deprecation path. Removing APIs in the same release they're deprecated — or without deprecation at all. The deprecation period is the migration budget you give consumers.
- Version ranges misunderstood. Publishing a breaking change as minor breaks every consumer
on
^ranges simultaneously — a distributed outage of trust. This is why classification matters. - Forgetting the ecosystem. Bumping major without checking downstream (plugins, adapters, docs, examples) — the release isn't done until the ecosystem story is coherent.
- Manual versioning drift. Humans forgetting to bump, or bumping inconsistently. Automate (changesets/semantic-release); let humans do the classification they uniquely can.
04 同仓库更多 Skills
web-scrape
Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.
design-taste-frontend
tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.
test-driven-development
Use when implementing any feature or bugfix, before writing implementation code
systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
requesting-code-review
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
brainstorming
You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).