From 1ae83fe1f60c61db86ab04511f281a23002c768e Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Sat, 28 Feb 2026 12:26:19 +0100 Subject: [PATCH] docs: prepare repository for open-source release MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove internal planning documents (moved to archgate/internal) - Update CONTRIBUTING.md with ADR governance section — contributors must read Architecture Decision Records before writing code - Add ADR quick-reference table and CLI commands for browsing ADRs - Add step to contribution workflow: read relevant ADRs first - Fix CODE_OF_CONDUCT.md enforcement contact placeholder - Update agent memory to remove plans/ path reference - Emphasize Conventional Commits and validation gate in guidelines Co-Authored-By: Claude Opus 4.6 --- .../agent-memory/archgate-developer/MEMORY.md | 2 +- CODE_OF_CONDUCT.md | 2 +- CONTRIBUTING.md | 50 +++++++++++++++---- 3 files changed, 42 insertions(+), 12 deletions(-) diff --git a/.claude/agent-memory/archgate-developer/MEMORY.md b/.claude/agent-memory/archgate-developer/MEMORY.md index 2b0e8bd1..544229d8 100644 --- a/.claude/agent-memory/archgate-developer/MEMORY.md +++ b/.claude/agent-memory/archgate-developer/MEMORY.md @@ -12,7 +12,7 @@ Skipping steps 2 or 3 is a workflow violation. The user should NEVER have to inv ## Version References -- **Minimum version** (`>=1.2.21`): Enforced in `src/cli.ts`, documented in CLAUDE.md "Technology Stack" and `plans/03-technical-plan.md`. This is the user-facing requirement. +- **Minimum version** (`>=1.2.21`): Enforced in `src/cli.ts`, documented in CLAUDE.md "Technology Stack". This is the user-facing requirement. - **Pinned version** (`1.3.8`): Set in `.prototools`, referenced in ADR risk sections (ARCH-005, ARCH-006) and CLAUDE.md "Toolchain" section. This is the dev toolchain version. - These are intentionally different. When upgrading the pinned version, update `.prototools` + ADR risk sections + CLAUDE.md toolchain. Do NOT change the minimum unless a new Bun API is required. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index cdcf7584..06675302 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -36,7 +36,7 @@ This Code of Conduct applies within all community spaces, and also applies when ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [INSERT CONTACT METHOD]. All complaints will be reviewed and investigated promptly and fairly. +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [hello@archgate.dev](mailto:hello@archgate.dev). All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1382759b..e2a5615b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,34 @@ Thank you for your interest in contributing to Archgate CLI! We welcome all kind > **Note:** Development is supported on macOS, Linux, and Windows. -## 🚀 Quick Start +## Architecture Decision Records (ADRs) + +Archgate dogfoods itself — the CLI is governed by its own ADRs in `.archgate/adrs/`. **Before writing any code, read the ADRs that apply to the area you're changing.** + +### Quick reference + +| ADR | Scope | Summary | +| --------------------------------------------------------- | -------- | -------------------------------------------------------------------- | +| [ARCH-001](/.archgate/adrs/ARCH-001-command-structure.md) | Commands | `register*Command(program)` pattern, no business logic in commands | +| [ARCH-002](/.archgate/adrs/ARCH-002-error-handling.md) | Errors | Exit codes (0/1/2), `logError()` for stderr | +| [ARCH-003](/.archgate/adrs/ARCH-003-output-formatting.md) | Output | `styleText` from `node:util`, `--json` flag, no emoji | +| [ARCH-004](/.archgate/adrs/ARCH-004-no-barrel-files.md) | Imports | Direct imports only, no `index.ts` barrel re-exports | +| [ARCH-005](/.archgate/adrs/ARCH-005-testing-standards.md) | Tests | Bun test runner, fixtures in `tests/fixtures/`, 80 % coverage target | +| [ARCH-006](/.archgate/adrs/ARCH-006-dependency-policy.md) | Deps | Minimal dependencies, prefer Bun built-ins | + +To browse ADRs locally after cloning: + +```bash +# List all ADRs +bun run src/cli.ts adr list + +# Show a specific ADR +bun run src/cli.ts adr show ARCH-001 +``` + +ADR compliance is enforced automatically — `bun run validate` includes an ADR check step that verifies your changes against every rule. **Pull requests that violate an ADR will not pass CI.** + +## Quick Start ### Prerequisites @@ -41,7 +68,7 @@ bun install bun run cli ``` -## 🛠️ Development +## Development ### Available Scripts @@ -108,7 +135,7 @@ tests/ # Mirrors src/ structure .archgate/adrs/ # Self-governance ADRs ``` -## 🔄 Contribution Workflow +## Contribution Workflow 1. **Fork the repository** on GitHub 2. **Create a feature branch** from `main`: @@ -117,34 +144,37 @@ tests/ # Mirrors src/ structure git checkout -b feature/your-feature-name ``` -3. **Make your changes** and commit them: +3. **Read the ADRs** relevant to the area you're changing (see table above) + +4. **Make your changes** and commit them using [Conventional Commits](https://www.conventionalcommits.org/): ```bash git add . git commit -m "feat: your feature description" ``` -4. **Run the full validation suite**: +5. **Run the full validation suite** (includes ADR compliance checks): ```bash bun run validate ``` -5. **Push to your fork**: +6. **Push to your fork**: ```bash git push origin feature/your-feature-name ``` -6. **Submit a pull request** to the main repository +7. **Submit a pull request** to the main repository -## 📝 Guidelines +## Guidelines +- **Read the ADRs first** — all code changes must comply with the project's Architecture Decision Records - Follow the existing code style and conventions -- Write clear, descriptive commit messages +- Write clear, descriptive commit messages using [Conventional Commits](https://www.conventionalcommits.org/) - Add tests for new functionality when applicable - Update documentation as needed -- Ensure all checks pass before submitting +- Ensure `bun run validate` passes before submitting ---