diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..b39bcd3b --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,114 @@ +# Clone the repository + +git clone cd +nextgen-databases + +# Using Nix (recommended for reproducibility) + +nix develop + +# Or using toolbox/distrobox + +toolbox create nextgen-databases-dev toolbox enter nextgen-databases-dev +\# Install dependencies manually + +# Verify setup + +just check \# or: cargo check / mix compile / etc. just test \# Run test +suite + + + ### Repository Structure + + `nextgen-databases` is a **coordination repo** — it does not hold database + implementations. Each database and query language has its own repo (see `REGISTRY.adoc`). + +nextgen-databases/ ├── README.adoc / EXPLAINME.adoc / TOPOLOGY.adoc / +ROADMAP.adoc \# Portfolio docs ├── REGISTRY.adoc \# Authoritative map: +database/language → its own repo ├── CLAUDE.md / AGENTS.md / +0-AI-MANIFEST.a2ml \# Agent guardrails ├── docs/ \# Coordination docs +(incl. migration runbooks) ├── tests/ \# CROSS-database integration +tests only ├── .machine_readable/ \# Canonical SCM metadata ├── .github/ +\# CI/CD, issue templates, governance ├── .well-known/ LICENSES/ └── +flake.nix / Justfile / stapeln.toml / opsm.toml \# Shared env & +orchestration + + + #### What belongs here vs. in a database repo + + - ✅ **Here**: portfolio docs, the registry, cross-database integration tests, shared + infrastructure/orchestration, governance and machine-readable metadata. + - ❌ **Not here — use the database's own repo**: per-database source code, schemas, + migrations, storage engines, query-language implementations, per-database design docs, + whitepapers, benchmarks, and datasets. See `REGISTRY.adoc` for the destination repo. + + A CI guard (`.github/workflows/placement-guard.yml`) and a local pre-write hook + (`.claude/hooks/block-db-writes.sh`) enforce this. + + --- + + ## How to Contribute + + ### Reporting Bugs + + **Before reporting**: + 1. Search existing issues + 2. Check if it's already fixed in `main` + 3. Determine which perimeter the bug affects + + **When reporting**: + + Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + + - Clear, descriptive title + - Environment details (OS, versions, toolchain) + - Steps to reproduce + - Expected vs actual behaviour + - Logs, screenshots, or minimal reproduction + + ### Suggesting Features + + **Before suggesting**: + 1. Check the [roadmap](ROADMAP.md) if available + 2. Search existing issues and discussions + 3. Consider which perimeter the feature belongs to + + **When suggesting**: + + Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + + - Problem statement (what pain point does this solve?) + - Proposed solution + - Alternatives considered + - Which perimeter this affects + + ### Your First Contribution + + Look for issues labelled: + + - [`good first issue`](https://github.com/hyperpolymath/nextgen-databases/labels/good%20first%20issue) — Simple Perimeter 3 tasks + - [`help wanted`](https://github.com/hyperpolymath/nextgen-databases/labels/help%20wanted) — Community help needed + - [`documentation`](https://github.com/hyperpolymath/nextgen-databases/labels/documentation) — Docs improvements + - [`perimeter-3`](https://github.com/hyperpolymath/nextgen-databases/labels/perimeter-3) — Community sandbox scope + + --- + + ## Development Workflow + + ### Branch Naming + +docs/short-description \# Documentation (P3) test/what-added \# Test +additions (P3) feat/short-description \# New features (P2) +fix/issue-number-description \# Bug fixes (P2) refactor/what-changed \# +Code improvements (P2) security/what-fixed \# Security fixes (P1-2) + + + ### Commit Messages + + We follow [Conventional Commits](https://www.conventionalcommits.org/): + +(): + +\[optional body\] + +\[optional footer\] diff --git a/.githooks/validate-a2ml.sh b/.github/hooks/validate-a2ml.sh similarity index 100% rename from .githooks/validate-a2ml.sh rename to .github/hooks/validate-a2ml.sh diff --git a/.githooks/validate-k9.sh b/.github/hooks/validate-k9.sh similarity index 100% rename from .githooks/validate-k9.sh rename to .github/hooks/validate-k9.sh diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml index 69e551ae..9b439a63 100644 --- a/.github/workflows/dogfood-gate.yml +++ b/.github/workflows/dogfood-gate.yml @@ -44,12 +44,12 @@ jobs: # In-repo validator. hyperpolymath/a2ml-validate-action does not exist — # `gh api repos/...` returns 404 and the job failed at "Set up job" with # "Unable to resolve action ..., repository not found", so it never ran. - # .githooks/validate-a2ml.sh is the canonical RSR implementation (identical + # .github/hooks/validate-a2ml.sh is the canonical RSR implementation (identical # to the copy in rsr-template-repo) and takes the same INPUT_* interface. env: INPUT_PATH: '.' INPUT_STRICT: 'false' - run: bash .githooks/validate-a2ml.sh + run: bash .github/hooks/validate-a2ml.sh - name: Write summary run: | @@ -98,7 +98,7 @@ jobs: env: INPUT_PATH: '.' INPUT_STRICT: 'false' - run: bash .githooks/validate-k9.sh + run: bash .github/hooks/validate-k9.sh - name: Write summary run: | diff --git a/.github/workflows/placement-guard.yml b/.github/workflows/placement-guard.yml index 84584aae..5813c156 100644 --- a/.github/workflows/placement-guard.yml +++ b/.github/workflows/placement-guard.yml @@ -55,12 +55,12 @@ jobs: # Allowed coordination paths (regex, anchored at repo root). ALLOW='^(README|EXPLAINME|TOPOLOGY|ROADMAP|TOOLING-STATUS|REGISTRY|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|MAINTAINERS|NOTICE|LICENSE|PROOF-NEEDS|TEST-NEEDS|QUICKSTART-[A-Z]+|0-AI-MANIFEST|CLAUDE|GEMINI|AGENTS|llm-warmup-[a-z]+)\.[A-Za-z0-9]+$' - # `.githooks` added 2026-07-27. It is repo infrastructure, not database + # `.github/hooks` added 2026-07-27. It is repo infrastructure, not database # content — git resolves core.hooksPath relative to the worktree root, # so it must live there, exactly like .github/ and .claude/ which were # already allowed. # - # This became load-bearing when #59 landed .githooks/validate-a2ml.sh and + # This became load-bearing when #59 landed .github/hooks/validate-a2ml.sh and # validate-k9.sh: those files are tracked on main today, so the next PR # touching either one is flagged "Misplaced content" and fails the guard. # diff --git a/CLAUDE.md b/CLAUDE.md index e64db0e7..92f0787f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,7 +29,7 @@ own repo. 3. **Cross-database** integration tests (`tests/`) and shared infrastructure (`flake.nix`, `Justfile`, `stapeln.toml`, `opsm.toml`). 4. **Governance & metadata**: `.github/`, `.machine_readable/`, `.well-known/`, - `LICENSES/`, `CONTRIBUTING.adoc`, `SECURITY.adoc`, `0-AI-MANIFEST.a2ml`. + `LICENSES/`, `.github/CONTRIBUTING.md`, `SECURITY.adoc`, `0-AI-MANIFEST.a2ml`. ### Where database content goes diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 4aad651b..00000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,120 +0,0 @@ -== Clone the repository - -git clone https://github.com/hyperpolymath/nextgen-databases.git cd -nextgen-databases - -== Using Nix (recommended for reproducibility) - -nix develop - -== Or using toolbox/distrobox - -toolbox create nextgen-databases-dev toolbox enter nextgen-databases-dev -# Install dependencies manually - -== Verify setup - -just check # or: cargo check / mix compile / etc. just test # Run test -suite - -.... - -### Repository Structure - -`nextgen-databases` is a **coordination repo** — it does not hold database -implementations. Each database and query language has its own repo (see `REGISTRY.adoc`). -.... - -nextgen-databases/ ├── README.adoc / EXPLAINME.adoc / TOPOLOGY.adoc / -ROADMAP.adoc # Portfolio docs ├── REGISTRY.adoc # Authoritative map: -database/language -> its own repo ├── CLAUDE.md / AGENTS.md / -0-AI-MANIFEST.a2ml # Agent guardrails ├── docs/ # Coordination docs -(incl. migration runbooks) ├── tests/ # CROSS-database integration tests -only ├── .machine_readable/ # Canonical SCM metadata ├── .github/ # -CI/CD, issue templates, governance ├── .well-known/ LICENSES/ └── -flake.nix / Justfile / stapeln.toml / opsm.toml # Shared env & -orchestration - -.... - -#### What belongs here vs. in a database repo - -- ✅ **Here**: portfolio docs, the registry, cross-database integration tests, shared - infrastructure/orchestration, governance and machine-readable metadata. -- ❌ **Not here — use the database's own repo**: per-database source code, schemas, - migrations, storage engines, query-language implementations, per-database design docs, - whitepapers, benchmarks, and datasets. See `REGISTRY.adoc` for the destination repo. - -A CI guard (`.github/workflows/placement-guard.yml`) and a local pre-write hook -(`.claude/hooks/block-db-writes.sh`) enforce this. - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/nextgen-databases/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/nextgen-databases/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/nextgen-databases/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/nextgen-databases/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -.... - -docs/short-description # Documentation (P3) test/what-added # Test -additions (P3) feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) refactor/what-changed # -Code improvements (P2) security/what-fixed # Security fixes (P1-2) - -.... - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -.... - -(): - -{empty}[optional body] - -{empty}[optional footer] diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index 358753a7..68c3d519 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -31,7 +31,7 @@ Output: `{{BUILD_OUTPUT_PATH}}` [source,bash] ---- -guix build -f guix.scm +guix build -f build/guix.scm ---- === Nix diff --git a/REGISTRY.adoc b/REGISTRY.adoc index 7e392b08..52e92f9e 100644 --- a/REGISTRY.adoc +++ b/REGISTRY.adoc @@ -83,7 +83,7 @@ were removed once each extraction completed (2026-07-27 and 2026-08-03). * Cross-database integration tests (`tests/`) * Shared infra & environment (`flake.nix`, `guix.scm`, `Justfile`, `stapeln.toml`, `opsm.toml`) * Governance & metadata (`.github/`, `.machine_readable/`, `.well-known/`, `LICENSES/`, - `CONTRIBUTING.adoc`, `SECURITY.adoc`, `0-AI-MANIFEST.a2ml`) + `.github/CONTRIBUTING.md`, `SECURITY.adoc`, `0-AI-MANIFEST.a2ml`) [NOTE] ==== diff --git a/SECURITY.adoc b/SECURITY.adoc index 33dc64f0..486a83fa 100644 --- a/SECURITY.adoc +++ b/SECURITY.adoc @@ -395,7 +395,7 @@ When using Nextgen Databases, we recommend: * https://github.com/hyperpolymath/nextgen-databases/security/advisories[Security Advisories] * link:CHANGELOG.md[Changelog] -* link:CONTRIBUTING.adoc[Contributing Guidelines] +* link:.github/CONTRIBUTING.md[Contributing Guidelines] * https://cve.mitre.org/[CVE Database] * https://www.first.org/cvss/calculator/3.1[CVSS Calculator] diff --git a/docs/accessibility/README.adoc b/docs/accessibility/README.adoc index 2839c3d2..73669471 100644 --- a/docs/accessibility/README.adoc +++ b/docs/accessibility/README.adoc @@ -243,7 +243,7 @@ Burble is committed to: * Supporting screen readers and other assistive technologies * Continuous improvement based on user feedback -We welcome contributions to improve accessibility. See our link:../CONTRIBUTING.adoc[Contributing Guide] for details. +We welcome contributions to improve accessibility. See our link:../../.github/CONTRIBUTING.md[Contributing Guide] for details. == Related Documents diff --git a/guix.scm b/guix.scm deleted file mode 100644 index a87f90ab..00000000 --- a/guix.scm +++ /dev/null @@ -1,21 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Guix development environment. -;; Usage: guix shell -D -f guix.scm - -(use-modules (guix packages) - (guix build-system gnu) - (guix licenses) - (gnu packages base) - (gnu packages bash) -) - -(package - (name "nextgen-databases") - (version "0.1.0") - (source #f) - (build-system gnu-build-system) - (inputs (list coreutils bash )) - (synopsis "nextgen-databases") - (description "nextgen-databases — part of the hyperpolymath ecosystem.") - (home-page "https://github.com/hyperpolymath/nextgen-databases") - (license ((@@ (guix licenses) license) "MPL-2.0" "https://github.com/hyperpolymath/palimpsest-license")))