diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..49b6f02 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,45 @@ +name: Bug report +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 only after redacting hostnames, IPs, serials, credentials, and other real device data. + 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, after redacting hostnames, IPs, serials, credentials, and other real device data. + 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..a4643d0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,19 @@ +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 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/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..3ecf4f1 --- /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-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. | + +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-orange) +![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..851cd40 --- /dev/null +++ b/STYLE_GUIDE.md @@ -0,0 +1,41 @@ +# 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 5ab5c17..f2b4d2b 100644 --- a/profile/README.md +++ b/profile/README.md @@ -59,6 +59,15 @@ the version, not instead of it. No server in the family is tagged `stable` yet; all are running in the maintainer's lab, not production, regardless of version number. +## Start here + +- **Foundation:** Start with [`mecmcp`](https://github.com/mechubsec/mecmcp) for shared MCP orchestration and deterministic change-control foundations. +- **MCP servers:** Try [`rustjunosmcp`](https://github.com/mechubsec/rustjunosmcp) first, or [`rustunifimcp`](https://github.com/mechubsec/rustunifimcp) as a second released vendor-facing example. +- **Data:** Explore [`ssdf`](https://github.com/mechubsec/ssdf) for the sovereign security data fabric. +- **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. + +Get in touch / testers wanted: for questions, ideas, or testing feedback, join 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.