From 9368c5435a0a84c991dfd6a3f7228e2ae1b7a591 Mon Sep 17 00:00:00 2001 From: fastrevmd-lab <82611597+fastrevmd-lab@users.noreply.github.com> Date: Wed, 7 Oct 2026 14:15:10 -0400 Subject: [PATCH] standardize repository presentation --- CONTRIBUTING.md | 1 + README-TEMPLATE.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++ STYLE_GUIDE.md | 49 ++++++++++++++++++++++++++++++++++++ profile/README.md | 15 +++++++++-- 4 files changed, 125 insertions(+), 2 deletions(-) create mode 100644 README-TEMPLATE.md create mode 100644 STYLE_GUIDE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 867b0aa..90812fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,6 +21,7 @@ inspectable, and honest are very welcome. - Match the surrounding code's style; explain the "why" in the description. - Include tests where the project has them, and note how you verified the change. - Label maturity honestly: if something is partial or unverified, say so. +- For README changes, follow the [README opening template](README-TEMPLATE.md). ## Ground rules - Deterministic decides, the model explains, a human approves — don't add an diff --git a/README-TEMPLATE.md b/README-TEMPLATE.md new file mode 100644 index 0000000..d604f38 --- /dev/null +++ b/README-TEMPLATE.md @@ -0,0 +1,62 @@ +# README opening template + +Use this opening for every mechub repository. Keep the first screen useful to +an operator: state the value, show the maturity, explain the project, and give +the shortest safe path to a first local run. + +```markdown +# + + + +![Status: ](https://img.shields.io/badge/status--) + +a mechub project — sovereign AI operations for network and security teams + + + +## Quick start + + +``` + +## Status vocabulary + +Use exactly one of these maturity labels in the status badge: + +| Status | Badge | Use when | +| --- | --- | --- | +| Planned | `status-planned-lightgrey` | The project is proposed or not yet usable. | +| Alpha | `status-alpha-blue` | An early usable version exists; interfaces and behaviour may change. | +| Beta | `status-beta-yellow` | The project is usable for evaluation; interfaces are stabilising. | +| Stable | `status-stable-brightgreen` | The supported path is established and maintained. | + +Use the matching Shields.io status segment in the opening badge; do not create +additional maturity labels or colors: + +```markdown +![Status: Planned](https://img.shields.io/badge/status-planned-lightgrey) +![Status: Alpha](https://img.shields.io/badge/status-alpha-blue) +![Status: Beta](https://img.shields.io/badge/status-beta-yellow) +![Status: Stable](https://img.shields.io/badge/status-stable-brightgreen) +``` + +Do not use `In production` to describe a maintainer's own homelab or lab +deployment. Say `running in the maintainer's lab` in prose instead. Reserve +production claims for deployments and evidence that the project can actually +support. + +## README maintenance rules + +- Keep the value statement to one sentence and put it before the badge. +- Keep the canonical subtitle exactly as shown in the template. +- Put release history and release narrative in `CHANGELOG.md`. +- Put lab notes, experiments, and deployment observations in `docs/`. +- Tool-count badges must match the release they describe. If a count is from + the unreleased branch, label it `unreleased` rather than presenting it as a + released capability. Reconcile the count whenever a release changes the + available tools. +- Keep the quick start deterministic and offline-capable where the project + permits; do not imply that model output performs an unreviewed change. diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md new file mode 100644 index 0000000..8f243d4 --- /dev/null +++ b/STYLE_GUIDE.md @@ -0,0 +1,49 @@ +# mechub style guide + +This guide is the shared standard for mechub repository documentation and +metadata. Apply it consistently while keeping each repository's technical +description specific and honest. + +## README opening + +Every README starts with an H1 containing the exact repository name. Do not +insert or remove dashes, including in names such as `rustjunosmcp`. + +Use the canonical subtitle: + +> sovereign AI operations for network and security teams + +Use one status badge with exactly one of these labels: **Planned**, **Alpha**, +**Beta**, or **Stable**. Do not use “In production” for a maintainer's +homelab; describe that state as “running in the maintainer's lab”. + +Keep the opening focused on the project's value, audience, maturity, and +shortest safe local path. Quick starts should be deterministic and +offline-capable where the project permits, and must not imply that model +output performs an unreviewed change. + +## Vendor and project naming + +Use the fuller product names **HPE Juniper Mist** and **Junos SRX** wherever +those products are referenced. + +Append this description suffix to repository descriptions: + +> — a mechub project + +## Affiliation disclaimer + +Each README contains this disclaimer exactly once, replacing `{Vendor}` with +the relevant vendor name: + +> This is an independent, community project. It is not affiliated with, +> endorsed by, or supported by {Vendor}. + +## Review checklist + +- The H1 exactly matches the repository name. +- The canonical subtitle and one approved status label are present. +- Vendor names use the fuller forms above. +- The affiliation disclaimer appears exactly once. +- Claims describe evidence-backed behavior and do not overstate lab usage. +- The repository description ends with “— a mechub project”. diff --git a/profile/README.md b/profile/README.md index e19ead0..f874e88 100644 --- a/profile/README.md +++ b/profile/README.md @@ -34,9 +34,20 @@ the hub is where every vendor's MCP server meets, on hardware you own. |---|---| | **Foundation** | [`mecmcp`](https://github.com/mechubsec/mecmcp) · [`rustnetconf`](https://github.com/mechubsec/rustnetconf) · [`rustez`](https://github.com/mechubsec/rustez) | | **MCP servers** | [`rustjunosmcp`](https://github.com/mechubsec/rustjunosmcp) · [`rustpanosmcp`](https://github.com/mechubsec/rustpanosmcp) · [`rustsdcmcp`](https://github.com/mechubsec/rustsdcmcp) · [`rustmistmcp`](https://github.com/mechubsec/rustmistmcp) · [`rustproxmoxmcp`](https://github.com/mechubsec/rustproxmoxmcp) · [`rustunifimcp`](https://github.com/mechubsec/rustunifimcp) · [`rustfortimcp`](https://github.com/mechubsec/rustfortimcp) · [`rustopnsmcp`](https://github.com/mechubsec/rustopnsmcp) | -| **Data** | [`ssdf`](https://github.com/mechubsec/ssdf) — sovereign security data fabric | +| **Data** | [`ssdf`](https://github.com/mechubsec/ssdf) — Sovereign Security Data Fabric; the only repository with a Python core | | **Evaluation** | [`mechubbench`](https://github.com/mechubsec/mechubbench) — tool-call benchmark corpus and runner for network-automation agents | -| **Skills & tools** | [`fwskillsshare`](https://github.com/mechubsec/fwskillsshare) · [`firewallintentconverter`](https://github.com/mechubsec/firewallintentconverter) · [`fwconfigsantizer`](https://github.com/mechubsec/fwconfigsantizer) · [`srxsync`](https://github.com/mechubsec/srxsync) | +| **Skills & tools** | [`fwskillsshare`](https://github.com/mechubsec/fwskillsshare) · [`firewallintentconverter`](https://github.com/mechubsec/firewallintentconverter) · [`fwconfigsanitizer`](https://github.com/mechubsec/fwconfigsanitizer) · [`srxsync`](https://github.com/mechubsec/srxsync) | + +## Start here + +- **Foundation:** Start with [`mecmcp`](https://github.com/mechubsec/mecmcp), the shared foundation for connecting the ecosystem to management planes. +- **MCP servers:** Use a vendor server such as [`rustunifimcp`](https://github.com/mechubsec/rustunifimcp) to explore a runnable example that fronts a management plane. +- **Data:** [`ssdf`](https://github.com/mechubsec/ssdf) provides the Sovereign Security Data Fabric and its Python core. +- **Evaluation:** [`mechubbench`](https://github.com/mechubsec/mechubbench) contains benchmark cases and a runner for network-automation tool calls. +- **Skills & tools:** [`fwskillsshare`](https://github.com/mechubsec/fwskillsshare) shares reusable skills, while the companion tools convert, sanitize, and synchronize firewall data. + +For a newcomer, `mecmcp` is the recommended first repository because it explains +the common foundation; `rustunifimcp` is the shortest runnable server example. ## Principles