From 92c59a156445de45d261336323b77bc40281292a Mon Sep 17 00:00:00 2001 From: fastrevmd-lab <82611597+fastrevmd-lab@users.noreply.github.com> Date: Tue, 6 Oct 2026 21:14:23 -0400 Subject: [PATCH 1/6] standardize organization presentation --- CONTRIBUTING.md | 2 ++ README-TEMPLATE.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++ STYLE_GUIDE.md | 42 +++++++++++++++++++++++++++++++ profile/README.md | 16 +++++++++--- 4 files changed, 119 insertions(+), 3 deletions(-) create mode 100644 README-TEMPLATE.md create mode 100644 STYLE_GUIDE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 867b0aa..8f61191 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,6 +21,8 @@ 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 [repository style guide](STYLE_GUIDE.md) and + [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..961d67f --- /dev/null +++ b/STYLE_GUIDE.md @@ -0,0 +1,42 @@ +# mechub repository style guide + +Use this guide when creating or updating a mechub repository README, subtitle, +or GitHub repository metadata. It keeps the organization recognizable without +overstating maturity or vendor relationships. + +## README opening + +- The first H1 must equal the exact repository name. Preserve names such as + `rustjunosmcp`; do not insert a dash to make `rust-junosmcp`. +- Use the subtitle `sovereign AI operations for network and security teams` in + every repository README. +- Use one status label only: `Planned`, `Alpha`, `Beta`, or `Stable`. +- Do not use `In production` for a maintainer's homelab. Write `running in the + maintainer's lab` when that is the evidence available. +- Include the canonical disclaimer exactly once in each README, replacing + `{Vendor}` with the relevant vendor name: + + > This is an independent, community project. It is not affiliated with, endorsed by, or supported by {Vendor}. + +## Naming + +Use these fuller forms everywhere, including headings, prose, and metadata: + +- `HPE Juniper Mist` +- `Junos SRX` + +## Repository metadata + +- Append `— a mechub project` to every GitHub repository description. The + description is maintained in GitHub; this suffix is the organization + standard. +- Keep repository descriptions concise and factual. Do not imply vendor + endorsement, production readiness, or capabilities that are not available. + +## Pull requests + +- Keep the PR focused on one change and state the verification performed. +- Apply this guide to README edits in the same PR when practical. +- Preserve the project rule: deterministic code decides, the model explains, + and a human approves. + diff --git a/profile/README.md b/profile/README.md index e19ead0..785704c 100644 --- a/profile/README.md +++ b/profile/README.md @@ -34,9 +34,19 @@ 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 | -| **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) | +| **Data** | [`ssdf`](https://github.com/mechubsec/ssdf) — Sovereign Security Data Fabric with a Python core | +| **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) for shared MCP orchestration and deterministic change-control foundations. +- **MCP servers:** Try [`rustopnsmcp`](https://github.com/mechubsec/rustopnsmcp) or [`rustunifimcp`](https://github.com/mechubsec/rustunifimcp) as runnable vendor-facing examples. +- **Data:** Explore [`ssdf`](https://github.com/mechubsec/ssdf) for the Sovereign Security Data Fabric and its Python core. +- **Skills & tools:** Use [`fwskillsshare`](https://github.com/mechubsec/fwskillsshare), [`firewallintentconverter`](https://github.com/mechubsec/firewallintentconverter), [`fwconfigsanitizer`](https://github.com/mechubsec/fwconfigsanitizer), or [`srxsync`](https://github.com/mechubsec/srxsync) for focused operator utilities. + +For a newcomer, `mecmcp` is the recommended first repository because it +explains the shared foundation used by the rest of the ecosystem; choose a +runnable server instead when the goal is to try an integration immediately. ## Principles From 5ccea83dd91708cf4fc56a84d15dc4b58eecfd7b Mon Sep 17 00:00:00 2001 From: fastrevmd-lab <82611597+fastrevmd-lab@users.noreply.github.com> Date: Tue, 6 Oct 2026 21:33:45 -0400 Subject: [PATCH 2/6] Add community issue and pull request defaults --- .github/ISSUE_TEMPLATE/bug_report.yml | 34 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 +++++ .github/ISSUE_TEMPLATE/feature_request.yml | 34 ++++++++++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 17 +++++++++++ profile/README.md | 4 +++ 5 files changed, 97 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..502e32b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,34 @@ +name: Bug report +description: Report a reproducible problem in a mechub project. +title: "[Bug]: " +labels: ["bug"] +body: + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Tell us what went wrong and include relevant context. + validations: + required: true + - type: input + id: version + attributes: + label: Version + description: Which project version or commit are you using? + placeholder: e.g. 1.2.3 or abc1234 + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: List the smallest set of steps that reproduces the problem. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected result + description: What did you expect to happen? + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..9bbc4a9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security issue + url: https://github.com/mechubsec/.github/blob/main/SECURITY.md + about: Report vulnerabilities privately; please do not open a public issue. + - name: Questions and community discussion + url: https://github.com/orgs/mechubsec/discussions + about: Ask questions, share ideas, and connect with the mechub community. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..1b96d50 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,34 @@ +name: Feature request +description: Suggest an improvement for a mechub project. +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: What problem would this solve? + description: Describe the user or operator problem. + validations: + required: true + - type: textarea + id: proposal + attributes: + label: What do you propose? + description: Describe the behavior or outcome you would like. + validations: + required: true + - type: input + id: version + attributes: + label: Version + description: Which project version or commit are you using? + placeholder: e.g. 1.2.3 or abc1234 + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected result + description: What should happen after this feature is implemented? + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..7f6aec8 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,17 @@ +## Summary + + + +## Linked issue + +Closes # + +## Tests run + + + +## Checklist + +- [ ] Security changes use class-level public text. +- [ ] No secrets, credentials, customer data, or lab data are included. +- [ ] CHANGELOG.md is updated when applicable. diff --git a/profile/README.md b/profile/README.md index 785704c..788e317 100644 --- a/profile/README.md +++ b/profile/README.md @@ -48,6 +48,10 @@ For a newcomer, `mecmcp` is the recommended first repository because it explains the shared foundation used by the rest of the ecosystem; choose a runnable server instead when the goal is to try an integration immediately. +### Get in touch / testers wanted + +Questions, ideas, and testing feedback are welcome in the [mechub Discussions](https://github.com/orgs/mechubsec/discussions); report vulnerabilities privately via [SECURITY.md](https://github.com/mechubsec/.github/blob/main/SECURITY.md). + ## Principles - **Self-hosted by default.** Your realm, your models, your rules. From 831efe7d44e5f1113ae44d0ab204a5765ba0a042 Mon Sep 17 00:00:00 2001 From: Lancelot <82611597+fastrevmd-lab@users.noreply.github.com> Date: Wed, 7 Oct 2026 14:39:56 -0400 Subject: [PATCH 3/6] Fix community guide formatting --- STYLE_GUIDE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 961d67f..851cd40 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -39,4 +39,3 @@ Use these fuller forms everywhere, including headings, prose, and metadata: - Apply this guide to README edits in the same PR when practical. - Preserve the project rule: deterministic code decides, the model explains, and a human approves. - From ec9ce0fd3aaf6c77686cd2b504358a2dfc1a332e Mon Sep 17 00:00:00 2001 From: Lancelot <82611597+fastrevmd-lab@users.noreply.github.com> Date: Fri, 9 Oct 2026 11:54:20 -0400 Subject: [PATCH 4/6] Harden community report hygiene guidance --- .github/ISSUE_TEMPLATE/bug_report.yml | 15 +++++++++++++-- .github/ISSUE_TEMPLATE/feature_request.yml | 15 --------------- README-TEMPLATE.md | 4 ++-- 3 files changed, 15 insertions(+), 19 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 502e32b..02a3bfa 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -3,11 +3,22 @@ description: Report a reproducible problem in a mechub project. title: "[Bug]: " labels: ["bug"] body: + - type: markdown + attributes: + value: | + **Do not paste real device data.** Redact hostnames, IP addresses, serial numbers, usernames, credentials, keys, SNMP communities, and free-text descriptions from configs, logs, and error output before posting. Security problems go through [SECURITY.md](https://github.com/mechubsec/.github/blob/main/SECURITY.md), not public issues. + - type: checkboxes + id: redaction + attributes: + label: Data hygiene + options: + - label: I have removed real hostnames, IPs, serials, credentials, and other device data from this report. + required: true - type: textarea id: what-happened attributes: label: What happened? - description: Tell us what went wrong and include relevant context. + description: Tell us what went wrong and include relevant context after removing real device data. validations: required: true - type: input @@ -22,7 +33,7 @@ body: id: steps attributes: label: Steps to reproduce - description: List the smallest set of steps that reproduces the problem. + description: List the smallest set of steps that reproduces the problem, without real device data. validations: required: true - type: textarea diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 1b96d50..a4643d0 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -17,18 +17,3 @@ body: description: Describe the behavior or outcome you would like. validations: required: true - - type: input - id: version - attributes: - label: Version - description: Which project version or commit are you using? - placeholder: e.g. 1.2.3 or abc1234 - validations: - required: true - - type: textarea - id: expected - attributes: - label: Expected result - description: What should happen after this feature is implemented? - validations: - required: true diff --git a/README-TEMPLATE.md b/README-TEMPLATE.md index d604f38..3ecf4f1 100644 --- a/README-TEMPLATE.md +++ b/README-TEMPLATE.md @@ -29,7 +29,7 @@ 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. | +| Alpha | `status-alpha-orange` | 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. | @@ -38,7 +38,7 @@ 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: Alpha](https://img.shields.io/badge/status-alpha-orange) ![Status: Beta](https://img.shields.io/badge/status-beta-yellow) ![Status: Stable](https://img.shields.io/badge/status-stable-brightgreen) ``` From 1399c2dff6b1391fb168aa09a991488833f7b27d Mon Sep 17 00:00:00 2001 From: Lancelot <82611597+fastrevmd-lab@users.noreply.github.com> Date: Fri, 9 Oct 2026 13:58:46 -0400 Subject: [PATCH 5/6] Harden community template guidance --- .github/ISSUE_TEMPLATE/bug_report.yml | 15 +++++++++++++-- .github/ISSUE_TEMPLATE/feature_request.yml | 2 -- README-TEMPLATE.md | 4 ++-- 3 files changed, 15 insertions(+), 6 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 502e32b..6ee6137 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -3,11 +3,22 @@ description: Report a reproducible problem in a mechub project. title: "[Bug]: " labels: ["bug"] body: + - type: markdown + attributes: + value: | + **Do not paste real device data.** Redact hostnames, IP addresses, serial numbers, usernames, credentials, keys, SNMP communities, and free-text descriptions from configs, logs, and error output before posting. Security problems go through [SECURITY.md](https://github.com/mechubsec/.github/blob/main/SECURITY.md), not public issues. + - type: checkboxes + id: redaction + attributes: + label: Data hygiene + options: + - label: I have removed real hostnames, IPs, serials, credentials, and other device data from this report. + required: true - type: textarea id: what-happened attributes: label: What happened? - description: Tell us what went wrong and include relevant context. + description: Tell us what went wrong, omitting real device data from any error output or context. validations: required: true - type: input @@ -22,7 +33,7 @@ body: id: steps attributes: label: Steps to reproduce - description: List the smallest set of steps that reproduces the problem. + description: List the smallest set of steps that reproduces the problem, without real device data. validations: required: true - type: textarea diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 1b96d50..4a568c8 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -23,8 +23,6 @@ body: label: Version description: Which project version or commit are you using? placeholder: e.g. 1.2.3 or abc1234 - validations: - required: true - type: textarea id: expected attributes: diff --git a/README-TEMPLATE.md b/README-TEMPLATE.md index d604f38..3ecf4f1 100644 --- a/README-TEMPLATE.md +++ b/README-TEMPLATE.md @@ -29,7 +29,7 @@ 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. | +| Alpha | `status-alpha-orange` | 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. | @@ -38,7 +38,7 @@ 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: Alpha](https://img.shields.io/badge/status-alpha-orange) ![Status: Beta](https://img.shields.io/badge/status-beta-yellow) ![Status: Stable](https://img.shields.io/badge/status-stable-brightgreen) ``` From a9e7326da741a22899c94d3bf1134b0488beeb88 Mon Sep 17 00:00:00 2001 From: Lancelot <82611597+fastrevmd-lab@users.noreply.github.com> Date: Fri, 9 Oct 2026 15:05:04 -0400 Subject: [PATCH 6/6] Harden public issue intake guidance --- .github/ISSUE_TEMPLATE/bug_report.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 02a3bfa..49b6f02 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -18,7 +18,7 @@ body: id: what-happened attributes: label: What happened? - description: Tell us what went wrong and include relevant context after removing real device data. + description: Tell us what went wrong and include relevant context only after redacting hostnames, IPs, serials, credentials, and other real device data. validations: required: true - type: input @@ -33,7 +33,7 @@ body: id: steps attributes: label: Steps to reproduce - description: List the smallest set of steps that reproduces the problem, without real device data. + description: List the smallest set of steps that reproduces the problem, after redacting hostnames, IPs, serials, credentials, and other real device data. validations: required: true - type: textarea