From 997956429605ce9c2fd10636220870635eae005c Mon Sep 17 00:00:00 2001 From: Kyle Tse Date: Mon, 22 Jun 2026 12:47:57 +0100 Subject: [PATCH] docs: adopt doctrine project manifest --- .doctrine/project.json | 113 ++++++++++++++++++++++++++++++++++++ .github/workflows/build.yml | 10 +++- AGENTS.md | 41 +++++++++++++ PROJECT.md | 39 +++++++++++++ 4 files changed, 201 insertions(+), 2 deletions(-) create mode 100644 .doctrine/project.json create mode 100644 AGENTS.md create mode 100644 PROJECT.md diff --git a/.doctrine/project.json b/.doctrine/project.json new file mode 100644 index 0000000..fda65f5 --- /dev/null +++ b/.doctrine/project.json @@ -0,0 +1,113 @@ +{ + "schemaVersion": 1, + "project": { + "repo": "SylphxAI/rook-ceph-fork", + "name": "Rook Ceph Fork", + "lifecycle": "active", + "layer": "integration", + "summary": "Rook Ceph Fork builds a patched Rook/Ceph container image from a pinned upstream Rook version and publishes a GHCR image artifact from main.", + "goals": [ + "Maintain a minimal, auditable patch set on top of a specific upstream Rook version.", + "Build the patched Rook binary into a container image.", + "Publish GHCR image artifacts from main with digest/readback evidence." + ], + "nonGoals": [ + "Become the upstream Rook source of truth.", + "Own cluster rollout policy, Ceph operations, or Kubernetes runtime configuration outside this image artifact.", + "Push release images from pull requests or non-main branches." + ] + }, + "boundaries": { + "owns": [ + { + "name": "rook-fork-patch", + "description": "The Dockerfile and patch.py changes applied to the pinned upstream Rook source during image build." + }, + { + "name": "rook-fork-image-build", + "description": "GitHub Actions build and GHCR image publication for the forked Rook image artifact." + } + ], + "doesNotOwn": [ + "Upstream Rook source control, release policy, or project roadmap.", + "Production cluster rollout manifests, Ceph runtime policy, or incident recovery outside image artifact handoff.", + "Organization-wide infrastructure policy." + ], + "publicSurfaces": [ + { + "type": "container-image", + "name": "Forked Rook/Ceph image", + "location": "ghcr.io/sylphxai/rook-ceph-fork:v1.19.3-mon-bypass" + }, + { + "type": "patch", + "name": "Rook patch script", + "location": "patch.py" + }, + { + "type": "workflow", + "name": "Image build workflow", + "location": ".github/workflows/build.yml" + } + ], + "allowedDependencies": [ + { + "repo": "SylphxAI/doctrine", + "surface": "enterprise engineering doctrine", + "direction": "downward" + }, + { + "repo": "rook/rook", + "surface": "upstream Rook source at the Dockerfile-pinned tag", + "direction": "upstream-source" + } + ], + "forbiddenCouplings": [ + "Do not push GHCR images from pull requests or non-main branches.", + "Do not silently change the upstream Rook version, image tag, or patch purpose.", + "Do not encode cluster-specific rollout policy in the image build repository." + ] + }, + "documentation": { + "adr": { + "path": "docs/adr/", + "status": "planned" + }, + "specs": { + "path": "Dockerfile, patch.py", + "status": "present" + }, + "catalog": { + "path": "PROJECT.md", + "status": "present" + }, + "runbooks": { + "path": "AGENTS.md", + "status": "present" + }, + "generatedReferences": { + "path": "ghcr.io/sylphxai/rook-ceph-fork", + "status": "generated" + } + }, + "delivery": { + "ciModel": "legacy-ci", + "requiredContexts": [ + "build" + ], + "deployPath": "Pull requests build the image without pushing; main branch pushes may publish ghcr.io/sylphxai/rook-ceph-fork:v1.19.3-mon-bypass through .github/workflows/build.yml.", + "productionProof": "GitHub Actions build success, GHCR image digest readback for main publications, and downstream cluster rollout/readback evidence before claiming runtime adoption.", + "recoveryClass": "forward-fix-only" + }, + "adoption": { + "status": "baseline", + "gaps": [ + { + "id": "runtime-rollout-proof", + "description": "The repository can prove image build and publication; production cluster adoption proof lives in the consuming infrastructure rollout.", + "owner": "SylphxAI/rook-ceph-fork", + "target": "before runtime adoption claims" + } + ] + } +} diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index edd0db9..efa00e7 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,5 +1,11 @@ name: Build Forked Rook -on: [push] + +on: + push: + branches: [main] + pull_request: + branches: [main] + jobs: build: runs-on: ubuntu-latest @@ -15,5 +21,5 @@ jobs: - uses: docker/build-push-action@v6 with: context: . - push: true + push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} tags: ghcr.io/sylphxai/rook-ceph-fork:v1.19.3-mon-bypass diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..eca2330 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# Rook Ceph Fork Agent Instructions + +## Scope + +This file is the repo-local operating policy for agents working in +`SylphxAI/rook-ceph-fork`. Organization-wide engineering doctrine is owned by +`SylphxAI/doctrine`; `PROJECT.md` and `.doctrine/project.json` own this +repository's local identity, lifecycle, boundary, and delivery facts. + +This repository owns a small forked Rook/Ceph container build that applies local +patches to upstream Rook and publishes a GHCR image. + +## Read First + +1. `PROJECT.md` and `.doctrine/project.json` for project goals, boundaries, and + delivery proof. +2. `Dockerfile` for the upstream Rook version, build target, image base, and + published tag. +3. `patch.py` before changing fork behavior. +4. `.github/workflows/build.yml` before changing image build or push behavior. + +## Non-Negotiables + +- Keep fork behavior minimal, explicit, and auditable. Every patch must be + visible in `patch.py` or a documented equivalent. +- Do not push GHCR images from pull requests or non-main branches. +- Do not silently change the upstream Rook version, image tag, or patch purpose. +- Runtime use of the image requires cluster rollout/readback evidence outside + this repo. + +## Validation + +Use the narrowest meaningful validation first, then broaden as needed: + +- `python3 -m py_compile patch.py` +- Docker build for the forked image +- GitHub Actions build proof +- GHCR image digest readback for main-branch image publication + +Docs-only boundary changes may be validated by diff review, referenced-file +checks, and the central project manifest audit. diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..9195745 --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,39 @@ +# Rook Ceph Fork Project + +Rook Ceph Fork builds a patched Rook/Ceph container image. The current patch +increases Rook manager cache sync timeout for large clusters and publishes the +forked image to GHCR for controlled infrastructure use. + +## Lifecycle + +- Lifecycle: `active` +- Layer: `integration` +- Doctrine source of truth: [SylphxAI/doctrine](https://github.com/SylphxAI/doctrine) +- Machine manifest: `.doctrine/project.json` + +## Goals + +- Maintain a minimal, auditable patch set on top of a specific upstream Rook + version. +- Build the patched Rook binary into a container image. +- Publish GHCR image artifacts from `main` with digest/readback evidence. + +## Non-Goals + +- Do not become the upstream Rook source of truth. +- Do not own cluster rollout policy, Ceph operations, or Kubernetes runtime + configuration outside this image artifact. +- Do not push release images from pull requests or non-main branches. + +## Boundaries + +This repository owns `Dockerfile`, `patch.py`, and the GHCR image build workflow. +It does not own upstream Rook, production cluster manifests, Ceph runtime policy, +or incident recovery outside the image artifact handoff. + +## Delivery + +Pull requests should build the image without pushing. Main branch pushes may +publish `ghcr.io/sylphxai/rook-ceph-fork:v1.19.3-mon-bypass`. Production proof +for image publication requires GitHub Actions build success and GHCR digest +readback; runtime adoption additionally requires cluster rollout/readback proof.