AGENT SKILL

ams-semantic-versioning-pro

暂无简介

License 许可
MIT
所属仓库
TanNhatCMS/jarvis
最近更新
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.3 get 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.0 won't take 2.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

  1. 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.
  2. 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.
  3. Automate the mechanics. Changesets (human-written, per-PR: patch/minor/major + description) or semantic-release (from conventional commits). Humans classify; machines bump and publish.
  4. Deprecate before removing. Minor release: add the new way, deprecate the old with warnings and migration docs. Next major: remove. Never surprise-break.
  5. Publish pre-releases for majors. -rc.1 weeks before the major; invite consumers to test; fix the fallout before the major lands. Majors are the highest-stakes releases — soak them.
  6. 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.2 where 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

TanNhatCMS
TanNhatCMS/jarvis

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.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

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.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

★ 0
TanNhatCMS
TanNhatCMS/jarvis

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

★ 0
TanNhatCMS
TanNhatCMS/jarvis

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

★ 0
TanNhatCMS
TanNhatCMS/jarvis

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).

★ 0