From af0af79d18d6b11b14140912ba934e3a9f45cd72 Mon Sep 17 00:00:00 2001 From: Renn F Date: Tue, 20 Oct 2026 19:52:37 +0200 Subject: [PATCH] docs(governance): maintainers, governance and support files --- .github/ISSUE_TEMPLATE/bug.yml | 51 +++++++++++++++++++++ .github/ISSUE_TEMPLATE/bug_report.md | 56 ----------------------- .github/ISSUE_TEMPLATE/config.yml | 11 +++-- .github/ISSUE_TEMPLATE/docs.yml | 31 +++++++++++++ .github/ISSUE_TEMPLATE/feature.yml | 35 ++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 34 -------------- GOVERNANCE.md | 29 ++++++++++++ MAINTAINERS.md | 21 +++++++++ SECURITY.md | 17 ++++--- SUPPORT.md | 8 ++++ packages/core/package.json | 1 + packages/express/package.json | 1 + packages/fastify/package.json | 1 + packages/hono/package.json | 1 + packages/nestjs/package.json | 1 + 15 files changed, 195 insertions(+), 103 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug.yml delete mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/docs.yml create mode 100644 .github/ISSUE_TEMPLATE/feature.yml delete mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 GOVERNANCE.md create mode 100644 MAINTAINERS.md create mode 100644 SUPPORT.md diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..dd94d03 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,51 @@ +name: Bug report +description: Guard Core TS does not behave as documented +title: "[BUG] " +labels: [bug] +body: + - type: input + id: value + attributes: + label: Value this delivers + description: One sentence a user could witness once this is fixed. + placeholder: "Requests with whitelisted IPs are no longer rate limited." + validations: + required: true + - type: textarea + id: what + attributes: + label: What happened + description: What you did, what you expected, what you got. Error messages, stack traces and logs go here. + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + placeholder: | + 1. Configure Guard Core TS with '...' + 2. Send a request to '...' + 3. See error + validations: + required: true + - type: input + id: versions + attributes: + label: Versions + description: "@guardcore/core version, adapter package and version, Node.js version, OS." + placeholder: "@guardcore/core 4.4.0, @guardcore/express 4.4.0, Node.js 22, Ubuntu 24.04" + validations: + required: true + - type: textarea + id: config + attributes: + label: Configuration + description: Your config with secrets masked. + render: typescript + placeholder: | + // Minimal setup that reproduces the issue (secrets masked) + - type: textarea + id: context + attributes: + label: Additional context + description: Production or development, consistent or intermittent, workarounds tried. diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 0b0e3ac..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -name: Bug Report -about: Report a bug in @guardcore -title: '[BUG] ' -labels: bug -assignees: '' ---- - -## Bug Description - - - -## Steps To Reproduce - -1. -2. -3. -4. - -## Expected Behavior - - - -## Actual Behavior - - - -``` -Paste error output here -``` - -## Environment - -- **Node.js version**: -- **Package manager**: pnpm / npm / yarn / bun -- **@guardcore/core version**: -- **Adapter package**: @guardcore/express | @guardcore/fastify | @guardcore/nestjs | @guardcore/hono -- **Adapter version**: -- **OS**: -- **Redis version** (if applicable): - -## Configuration - -```typescript -import { SecurityConfigSchema } from '@guardcore/core'; - -const config = SecurityConfigSchema.parse({ - // Your configuration here -}); -``` - -## Additional Context - -- Is this in production or development? -- Does it happen consistently or intermittently? -- Have you found a workaround? diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 54024b6..2a71155 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,8 +1,11 @@ blank_issues_enabled: false contact_links: - - name: Documentation - url: https://github.com/Guard-Core/guard-core-ts - about: Read the documentation and README + - name: Guard Core TS Documentation + url: https://guard-core.github.io/guard-core-ts/ + about: Check the documentation for usage information and tutorials - name: Usage Questions url: https://github.com/Guard-Core/guard-core-ts/discussions - about: Ask usage questions in GitHub Discussions + about: Please ask and answer questions in GitHub Discussions + - name: Discord + url: https://discord.gg/ZW7ZJbjMkK + about: Questions and support in #help, new versions in #releases, development stream in #dev-feed diff --git a/.github/ISSUE_TEMPLATE/docs.yml b/.github/ISSUE_TEMPLATE/docs.yml new file mode 100644 index 0000000..0854339 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs.yml @@ -0,0 +1,31 @@ +name: Documentation +description: Wrong, missing or unclear Guard Core TS documentation +title: "[DOCS] " +labels: [documentation] +body: + - type: input + id: value + attributes: + label: Value this delivers + description: One sentence a reader could witness once this is fixed. + placeholder: "The rate limiting page shows the exact config for a Redis-backed store." + validations: + required: true + - type: input + id: page + attributes: + label: Page + description: URL of the page or section. + validations: + required: true + - type: textarea + id: problem + attributes: + label: What is wrong or missing + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed text + render: markdown diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000..aaf571a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,35 @@ +name: Feature request +description: Suggest an improvement to Guard Core TS +title: "[FEATURE] " +labels: [enhancement] +body: + - type: input + id: value + attributes: + label: Value this delivers + description: One sentence a user could witness once this exists. + placeholder: "A single toggle disables all detection for one route." + validations: + required: true + - type: textarea + id: job + attributes: + label: The job you are trying to get done + description: The outcome you need, not the mechanism you imagine. + validations: + required: true + - type: textarea + id: workaround + attributes: + label: How you work around it today + - type: textarea + id: example + attributes: + label: Example usage + description: Pseudocode of how you would like to use it. + render: typescript + - type: textarea + id: context + attributes: + label: Additional context + description: Similar features in other libraries, constraints, API implications. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index 75d3511..0000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: Feature Request -about: Suggest a feature for @guardcore -title: '[FEATURE] ' -labels: enhancement -assignees: '' ---- - -## Is your feature request related to a problem? - - - -## Describe the solution you'd like - - - -```typescript -// Example API design or usage -import { SecurityConfigSchema } from '@guardcore/core'; - -const config = SecurityConfigSchema.parse({ - // How would this feature be configured? -}); -``` - -## Describe alternatives you've considered - - - -## Additional context - -- Would this benefit the wider community? -- Are there similar implementations in other security libraries? -- Would this require changes to the public API? diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..7221497 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,29 @@ +# Governance + +Guard Core TS is part of the [Guard Core](https://github.com/Guard-Core) ecosystem. I maintain it alone; [MAINTAINERS.md](MAINTAINERS.md) lists who I am and how to check it. + +## Decisions + +I make the final call on every change: features, releases, security fixes and repository access. A proposal starts as an issue, so the reasoning is public before any code is written. + +## How a change lands + +1. Every change is a pull request to `master`. +2. The branch ruleset requires signed commits, linear history, passing status checks and two approvals, one of them from a code owner ([CODEOWNERS](.github/CODEOWNERS)). As the only maintainer I cannot get those approvals, so I merge my own pull requests with admin rights. That skips the approval count only: I never merge with a failing check. +3. A pull request closes an open issue (`Closes #N`), or carries the `no-issue` label when it is a small fix with nothing to discuss. + +## Releases + +Versions follow semantic versioning. The Guard Core engines (Python, TypeScript, Rust, Go, PHP, JVM) share one version number and release together. Releases are cut from tags and recorded in [CHANGELOG.md](CHANGELOG.md). + +## Security + +Vulnerabilities go through [SECURITY.md](SECURITY.md), never through public issues. + +## New maintainers + +Contributors with a record of reviewed and merged work can be invited as maintainers. A new maintainer is added to MAINTAINERS.md and CODEOWNERS in a pull request. + +## Conduct + +The [Code of Conduct](CODE_OF_CONDUCT.md) applies to every space of this project. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..72d007a --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,21 @@ +# Maintainers + +Guard Core TS has one maintainer. + +| Name | GitHub | Email | Role | +|---|---|---|---| +| Renzo Franceschini | [@rennf93](https://github.com/rennf93) | rennf93@guard-core.com | Lead maintainer: reviews and merges every change, publishes every release, handles security reports | + +## Identity + +- GitHub profile [@rennf93](https://github.com/rennf93): name Renzo Franceschini, website guard-core.com. +- [guard-core.com/company](https://guard-core.com/company) names Renzo Franceschini and links to @rennf93. +- The [Guard-Core](https://github.com/Guard-Core) GitHub organization has guard-core.com as a verified domain. +- npm: every `@guardcore/*` package names `Renzo Franceschini ` as author in its `package.json`. + +## Related files + +- Code ownership: [CODEOWNERS](.github/CODEOWNERS) +- How decisions are made: [GOVERNANCE.md](GOVERNANCE.md) +- Security reports: [SECURITY.md](SECURITY.md) +- Getting help: [SUPPORT.md](SUPPORT.md) diff --git a/SECURITY.md b/SECURITY.md index ed1e35d..e81852f 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,13 +2,12 @@ ## Supported Versions -| Package | Version | Supported | -| --- | --- | --- | -| @guardcore/core | 0.x | :white_check_mark: | -| @guardcore/express | 0.x | :white_check_mark: | -| @guardcore/fastify | 0.x | :white_check_mark: | -| @guardcore/nestjs | 0.x | :white_check_mark: | -| @guardcore/hono | 0.x | :white_check_mark: | +All `@guardcore/*` packages share one version. + +| Version | Supported | +| ------- | --------- | +| 4.x | :white_check_mark: bug and security fixes | +| < 4.0 | :x: | ## Reporting a Vulnerability @@ -76,7 +75,7 @@ When deploying applications using @guardcore packages: ## Responsible Disclosure -We follow a responsible disclosure process: +I follow a responsible disclosure process: 1. Reporter submits vulnerability via GitHub Security Advisory 2. Maintainer acknowledges within 48 hours @@ -85,7 +84,7 @@ We follow a responsible disclosure process: 5. Security advisory is published with the fix release 6. Reporter is credited (unless they prefer anonymity) -We kindly ask that you: +I ask that you: - Allow reasonable time for the vulnerability to be fixed before public disclosure - Make a good faith effort to avoid privacy violations, data destruction, or service disruption diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..6a5d030 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,8 @@ +# Support + +- Documentation: [https://guard-core.github.io/guard-core-ts/](https://guard-core.github.io/guard-core-ts/) +- Questions: [GitHub Discussions](https://github.com/Guard-Core/guard-core-ts/discussions) +- Chat: [Discord](https://discord.gg/ZW7ZJbjMkK), #help for questions, #releases for new versions. +- Bugs and feature requests: [issues](https://github.com/Guard-Core/guard-core-ts/issues/new/choose), using the templates. +- Security reports: [SECURITY.md](SECURITY.md), never a public issue. +- The hosted Guard Core app (app.guard-core.com): [saas-issues](https://github.com/Guard-Core/saas-issues). diff --git a/packages/core/package.json b/packages/core/package.json index 21dee83..e765702 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -65,6 +65,7 @@ "optional": true } }, + "author": "Renzo Franceschini ", "license": "MIT", "engines": { "node": ">=18" diff --git a/packages/express/package.json b/packages/express/package.json index 72b94a1..9f6fbe7 100644 --- a/packages/express/package.json +++ b/packages/express/package.json @@ -44,6 +44,7 @@ "optional": true } }, + "author": "Renzo Franceschini ", "license": "MIT", "engines": { "node": ">=18" diff --git a/packages/fastify/package.json b/packages/fastify/package.json index f06b768..3a92424 100644 --- a/packages/fastify/package.json +++ b/packages/fastify/package.json @@ -46,6 +46,7 @@ "optional": true } }, + "author": "Renzo Franceschini ", "license": "MIT", "engines": { "node": ">=20" diff --git a/packages/hono/package.json b/packages/hono/package.json index 2604411..9959721 100644 --- a/packages/hono/package.json +++ b/packages/hono/package.json @@ -37,6 +37,7 @@ "peerDependencies": { "hono": "^4" }, + "author": "Renzo Franceschini ", "license": "MIT", "repository": { "type": "git", diff --git a/packages/nestjs/package.json b/packages/nestjs/package.json index 02d5125..f579e3c 100644 --- a/packages/nestjs/package.json +++ b/packages/nestjs/package.json @@ -47,6 +47,7 @@ "reflect-metadata": "^0.1 || ^0.2", "cors": "^2" }, + "author": "Renzo Franceschini ", "license": "MIT", "engines": { "node": ">=18"