diff --git a/.agents/skills/docslime-fill/SKILL.md b/.agents/skills/docslime-fill/SKILL.md index 6a44b63..80ec81d 100644 --- a/.agents/skills/docslime-fill/SKILL.md +++ b/.agents/skills/docslime-fill/SKILL.md @@ -50,6 +50,9 @@ and production learning. Revisit earlier docs when observation changes what the - Keep requirements testable and solution-neutral, architecture grounded in real domain boundaries, and testing mapped to Given/When/Then behavior. - Keep publishing grounded in actual artifacts, gates, promotion, verification, and rollback. +- Present Semantic Versioning and Conventional Commits as optional publishing practices. Read + the existing workflow first; never impose enforcement, rewrite history, or change release + automation without explicit team agreement. - Keep observability tied to user outcomes as well as system health; never invent telemetry. ## Steps diff --git a/docmd.config.json b/docmd.config.json index 7f8ddbe..0922260 100644 --- a/docmd.config.json +++ b/docmd.config.json @@ -2,13 +2,6 @@ "title": "DocSlime", "url": "https://www.docslime.dev", "favicon": "/assets/favicon.svg", - "logo": { - "light": "/assets/images/docslime-wordmark.svg", - "dark": "/assets/images/docslime-wordmark-dark.svg", - "alt": "DocSlime", - "href": "/", - "height": "2.5rem" - }, "src": "docs", "out": "site", "engine": "js", @@ -22,6 +15,7 @@ "theme": { "name": "default", "appearance": "system", + "customCss": ["/assets/styles/docslime.css"], "codeHighlight": true }, "minify": true, diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md index 020293b..0f5c861 100644 --- a/docs/REQUIREMENTS.md +++ b/docs/REQUIREMENTS.md @@ -31,6 +31,7 @@ discovery, delivery, publication, and production learning. | FR-19 | Observability guidance shall connect production system health and user-outcome signals to requirements and discovery while covering telemetry, SLOs, alerts, ownership, and privacy. | Close the product-learning loop | | FR-20 | Documentation guidance and first-party docs shall render flowcharts as Mermaid diagrams rather than ASCII art. | Keep diagrams readable and renderable | | FR-21 | The scaffold and bundled skills shall describe the docs tree as a project-specific starting template, permit intentional omission of irrelevant product, strategy, or design docs, and preserve experience documentation for developer and agent consumers when useful. | Fit the docs to the project | +| FR-22 | Publishing guidance shall present Semantic Versioning and Conventional Commits as optional practices, preserve effective existing workflows, and prohibit adding enforcement or rewriting history without explicit team agreement. | Suggest release conventions without imposing workflow | ## Non-functional requirements diff --git a/docs/assets/images/docslime-wordmark-dark.svg b/docs/assets/images/docslime-wordmark-dark.svg index f5e2c64..9abd786 100644 --- a/docs/assets/images/docslime-wordmark-dark.svg +++ b/docs/assets/images/docslime-wordmark-dark.svg @@ -1,4 +1,4 @@ - + DocSlime A glossy blue slime mascot beside the DocSlime wordmark. diff --git a/docs/assets/images/docslime-wordmark.png b/docs/assets/images/docslime-wordmark.png index 6caf078..73ab4b8 100644 Binary files a/docs/assets/images/docslime-wordmark.png and b/docs/assets/images/docslime-wordmark.png differ diff --git a/docs/assets/images/docslime-wordmark.svg b/docs/assets/images/docslime-wordmark.svg index ad0ae9b..1c0b51c 100644 --- a/docs/assets/images/docslime-wordmark.svg +++ b/docs/assets/images/docslime-wordmark.svg @@ -1,4 +1,4 @@ - + DocSlime A glossy blue slime mascot beside the DocSlime wordmark. diff --git a/docs/assets/styles/docslime.css b/docs/assets/styles/docslime.css new file mode 100644 index 0000000..643a5c1 --- /dev/null +++ b/docs/assets/styles/docslime.css @@ -0,0 +1,46 @@ +.sidebar-header h1 a { + align-items: center; + display: inline-flex; + gap: 0.625rem; +} + +.sidebar-header h1 a::before { + background: url("../favicon.svg") center / contain no-repeat; + content: ""; + flex: 0 0 2rem; + height: 2rem; + width: 2rem; +} + +.docslime-hero-wordmark { + display: block; + height: auto; + margin: 0 auto 1rem; + width: min(21.375rem, 78vw); +} + +.docslime-hero-wordmark-dark, +html[data-theme="dark"] .docslime-hero-wordmark-light { + display: none; +} + +html[data-theme="dark"] .docslime-hero-wordmark-dark { + display: block; +} + +@media (prefers-color-scheme: dark) { + html:not([data-theme="light"]) .docslime-hero-wordmark-light { + display: none; + } + + html:not([data-theme="light"]) .docslime-hero-wordmark-dark { + display: block; + } +} + +@media (max-width: 640px) { + .docslime-hero-wordmark { + margin-bottom: 0.75rem; + width: min(17rem, 82vw); + } +} diff --git a/docs/engineering/PUBLISHING.md b/docs/engineering/PUBLISHING.md index c4fb68a..318488c 100644 --- a/docs/engineering/PUBLISHING.md +++ b/docs/engineering/PUBLISHING.md @@ -18,6 +18,21 @@ artifact and user-facing behavior are verified. | Agent skills | GitHub repository via `npx skills add DecisionNerd/DocSlime` | Repository revision/release | | Documentation site | Static `site/` output and configured host | Source commit/deployment | +## Recommended conventions, not mandates + +DocSlime recommends considering two complementary standards when they fit a project's release +model: + +- **Semantic Versioning** communicates compatibility through `MAJOR.MINOR.PATCH`. DocSlime + uses SemVer for CLI releases because the CLI has a public command and template contract. +- **Conventional Commits** use `type(scope): description` to make change intent readable by + people and release tooling. `fix` commonly corresponds to a patch, `feat` to a minor change, + and a declared breaking change to a major change when SemVer applies. + +These are suggestions, not requirements. A project should document and preserve an existing +convention that already works. DocSlime guidance must not introduce commit linting, rewrite +history, or change version automation without explicit team agreement. + ## Continuous integration `.github/workflows/ci.yml` validates the CLI, site, agent skills, and branch policy. Only @@ -73,6 +88,8 @@ host rather than inferred from generated files alone. ## Official references +- [Semantic Versioning 2.0.0](https://semver.org/) +- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) - [cargo-dist documentation](https://opensource.axo.dev/cargo-dist/) - [docmd Quick Start](https://docs.docmd.io/getting-started/quick-start/) - [docmd Deployment Overview](https://docs.docmd.io/deployment/) diff --git a/docs/engineering/TESTING.md b/docs/engineering/TESTING.md index 2e3e72e..8bb656d 100644 --- a/docs/engineering/TESTING.md +++ b/docs/engineering/TESTING.md @@ -25,6 +25,7 @@ verified together through the CLI, so the black-box tests double as integration | Self-explaining templates | Given a scaffolded tree, When inspected, Then every template carries `` guidance | `tests/cli.rs::every_template_carries_llm_guidance` | | Mermaid flowcharts / FR-20 | Given a scaffolded tree, When diagram guidance and examples are inspected, Then flowcharts use Mermaid and reject ASCII-art guidance | `tests/cli.rs::flowcharts_use_mermaid_in_generated_docs` | | Adaptable scaffold / FR-21 | Given a scaffolded tree and bundled skills, When scope guidance is inspected, Then it treats the tree as a starting template and names backend API developer and agent experience as a valid tailored use | `tests/cli.rs::scaffold_and_skills_explain_project_specific_scope` | +| Optional release conventions / FR-22 | Given a scaffolded tree and publishing skill guidance, When release conventions are inspected, Then Semantic Versioning and Conventional Commits are suggestions and enforcement requires explicit agreement | `tests/cli.rs::suggested_release_conventions_are_optional` | | Non-destructive by default / FR-2 | Given an edited file, When `init` re-runs, Then the file is left untouched | `tests/cli.rs::init_skips_existing_files` | | Force overwrite / FR-2 | Given an edited file, When `init --force`, Then the template is restored | `tests/cli.rs::init_force_overwrites` | | Legacy path safety / FR-17 | Given a filled legacy numbered file, When current `init` or `list` runs, Then the new counterpart is treated as satisfied without duplicating or moving user work | `tests/cli.rs::init_recognizes_legacy_paths`, `list_recognizes_legacy_paths` | diff --git a/docs/index.md b/docs/index.md index bb71849..8abde1c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,6 +5,9 @@ image: /assets/images/docslime-hero.png --- ::: hero glow:true +![DocSlime](/assets/images/docslime-wordmark.svg){.docslime-hero-wordmark .docslime-hero-wordmark-light} +![DocSlime](/assets/images/docslime-wordmark-dark.svg){.docslime-hero-wordmark .docslime-hero-wordmark-dark} + # Turn your repo into living docs. DocSlime makes repo knowledge stick. It connects product intent and continuous discovery to diff --git a/docs/lifecycle.md b/docs/lifecycle.md index f6ad732..2d7bbcd 100644 --- a/docs/lifecycle.md +++ b/docs/lifecycle.md @@ -120,6 +120,11 @@ Fill `engineering/PUBLISHING.md` with the real promotion path: artifacts, versio gates, deployment verification, and rollback. DocSlime itself promotes `staging` → `main` for the site and uses tag-driven releases for the CLI. +As optional defaults, consider Semantic Versioning when public compatibility needs a clear +`MAJOR.MINOR.PATCH` contract and Conventional Commits when structured change intent would help +reviews, changelogs, or release automation. Preserve an effective existing workflow; do not +add enforcement or rewrite history without explicit team agreement. + ### 7. Learn from production Fill `engineering/OBSERVABILITY.md` to connect system health and user-outcome signals back to diff --git a/templates/README.md b/templates/README.md index d21d2b5..a0ddc4a 100644 --- a/templates/README.md +++ b/templates/README.md @@ -58,3 +58,6 @@ Supporting detail lives in subfolders: in `docs/` so design and coding agents can load them without duplicate root files. - **Close the loop.** Observability should measure both system health and the user outcomes named in product, experience, and requirements docs. +- **Choose release conventions intentionally.** Consider Semantic Versioning and Conventional + Commits when they clarify compatibility and change intent, but preserve a team's effective + existing workflow and add enforcement only with explicit agreement. diff --git a/templates/engineering/PUBLISHING.md b/templates/engineering/PUBLISHING.md index 19b5af5..87ab4c9 100644 --- a/templates/engineering/PUBLISHING.md +++ b/templates/engineering/PUBLISHING.md @@ -19,6 +19,22 @@ that do not apply. --> |---|---|---|---| | _Artifact_ | _Registry, environment, store, or host_ | _Tag, digest, release, or commit_ | _Role/team_ | +## Suggested versioning and change history + + + +- Consider **Semantic Versioning** (`MAJOR.MINOR.PATCH`) when an artifact has a public API or + compatibility contract: incompatible changes may justify `MAJOR`, backward-compatible + features `MINOR`, and backward-compatible fixes `PATCH`. +- Consider **Conventional Commits** (`type(scope): description`) when human- and + machine-readable change history would improve reviews, changelogs, or release automation. +- Keep the workflow the team already uses when it serves them better. Document the chosen + convention and any exceptions; these suggestions do not require enforcement. + ## Build and continuous delivery