diff --git a/.github/ISSUE_TEMPLATE/first_contribution.md b/.github/ISSUE_TEMPLATE/first_contribution.md index 4f7949c..82e8fa6 100644 --- a/.github/ISSUE_TEMPLATE/first_contribution.md +++ b/.github/ISSUE_TEMPLATE/first_contribution.md @@ -17,7 +17,7 @@ Where is the relevant code/content? Link files or sections. ## Definition of Done - [ ] Concrete acceptance criteria are listed -- [ ] Required checks to run are listed (`validate.sh`, repo tests, etc.) +- [ ] Required checks to run are listed (docs preview, Jekyll build, CI data-drift check, etc.) - [ ] Scope fits a first contribution (<1 day focused work) ## Constraints diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index dee6070..7e88bdb 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -16,8 +16,9 @@ -- [ ] `../validate.sh` passes from workspace root -- [ ] `bundle exec jekyll build --strict_front_matter --future` passes +- [ ] Docs-only change previewed and self-reviewed +- [ ] `bundle exec jekyll build --strict_front_matter --future` passes for content/layout/config changes +- [ ] CI data-drift checks considered for `_posts/` or `_logs/` changes - [ ] New tests added (if applicable) - [ ] Manual testing performed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f225007..7d86488 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,89 +1,118 @@ # Contributing to public-process -Thank you for your interest in contributing to this project. +Thank you for helping improve `public-process`. -## Overview +This repository is the essay site for the organvm system. If you came here +looking for essays, you are in the right place. -Public Process is the essay publication platform for the organvm system. It is a Jekyll blog that hosts essays about building in public, creative systems, autonomous infrastructure, and the philosophy behind the eight-organ model. Essays are written in Markdown with YAML frontmatter. +## Quick Orientation -**Stack:** Jekyll blog, Ruby, Markdown essays +- Complete dated essay corpus: `_posts/YYYY-MM-DD-slug.md` +- Curated long-form essay collection: `essays/meta-system/` and + `essays/subsidiary/` +- Site pages: `index.md`, `about.md`, `reading.md`, `dashboard.md` +- Generated indexes and feeds: `data/` +- Jekyll configuration: `_config.yml`, `_layouts/`, `_includes/` -## Prerequisites +For most writing and editing work, start in `_posts/` or `essays/`. -- Git -- Ruby 3.3.x (see `.ruby-version`) -- Bundler 4.0.3 (see `Gemfile.lock`) -- A GitHub account +## Terms Used Here -## Development Setup +| Term | Plain meaning | +|------|---------------| +| `public-process` | This repository: the public essay and methodology site. | +| Organ V / Logos | The part of organvm responsible for essays, public process, and explanation. | +| organvm | The broader eight-organ project this site documents. | +| Essay | A Markdown file with a short YAML metadata block at the top. | +| Frontmatter | The YAML metadata block between `---` lines at the top of an essay. | +| Stranger Test | A check that a first-time reader can understand the purpose, status, and next step without private context. | +| PR | Pull request: the GitHub review request for your proposed change. | + +## Good First Contributions + +- Fix a typo, broken link, confusing sentence, or stale cross-reference. +- Clarify an essay introduction or section heading. +- Improve onboarding docs such as this file. +- Add missing metadata only when the expected value is clear from nearby files. +- Draft a new essay only when there is an issue or maintainer note defining the scope. + +Keep first changes small and easy to review. A useful one-paragraph correction is +better than a broad rewrite that mixes many decisions. + +## Setup + +For docs-only edits, GitHub's web editor is enough. For local preview or changes +to essays, layouts, includes, or configuration, use the Jekyll setup: ```bash -# Clone your fork git clone https://github.com/YOUR_USERNAME/public-process.git cd public-process - -# Ensure Homebrew Ruby/Bundler are first on PATH (macOS/Homebrew) -export PATH="/opt/homebrew/opt/ruby/bin:$PATH" - -# Install Ruby dependencies -gem install bundler:4.0.3 bundle install - -# Serve locally bundle exec jekyll serve - -# Site available at http://localhost:4000 ``` -## How to Contribute +The local site is available at `http://localhost:4000/public-process/`. + +This repo targets Ruby 3.3.x. If Bundler is missing, install the version from +`Gemfile.lock`: -### Reporting Issues +```bash +gem install bundler:4.0.3 +``` -- Use GitHub Issues for bug reports and feature requests -- Use the provided issue templates when available -- Include clear reproduction steps for bugs -- For documentation issues, specify which file and section +## Making a Change -### Making Changes +1. Fork the repository on GitHub. +2. Create a branch for the change: -1. **Fork** the repository on GitHub -2. **Clone** your fork locally -3. **Create a branch** for your change: ```bash - git checkout -b feat/your-feature-name + git checkout -b docs/clarify-contributor-guide ``` -4. **Make your changes** following the code style guidelines below -5. **Test** your changes: - ```bash - bundle exec jekyll build --strict_front_matter - ``` -6. **Commit** with a clear, imperative-mood message: + +3. Make the smallest useful edit. +4. Run the check that matches the change. +5. Commit with a short, imperative message: + ```bash - git commit -m "add validation for edge case in parser" + git commit -m "clarify contributor guide" ``` -7. **Push** your branch and open a Pull Request -### Code Style +6. Open a pull request and link the related issue when there is one. + +## Checks to Run + +Use the lowest check that actually covers your change: + +| Change type | Local check | +|-------------|-------------| +| Root docs such as `README.md`, `CONTRIBUTING.md`, or `docs/*.md` | Preview the Markdown and self-review links. | +| Essays, logs, layouts, includes, or `_config.yml` | `bundle exec jekyll build --strict_front_matter --future` | +| `_posts/` or `_logs/` content that changes generated indexes | Run the Jekyll build, then expect CI to verify frontmatter, links, and `data/` drift. | + +CI also runs the shared `essay-pipeline` and `editorial-standards` repositories +for frontmatter validation, internal link checks, and generated data drift. If +CI reports drift in `data/`, regenerate the data artifacts or ask for maintainer +help in the PR. -Essays use Markdown with YAML frontmatter (title, date, categories, tags, excerpt). Follow the existing essay style: clear prose, specific examples, honest reflection. Filenames follow Jekyll convention: YYYY-MM-DD-slug.md in _posts/. +## Writing Style -### Commit Messages +Essays should be clear, specific, and honest about process. Prefer concrete +examples over abstract claims. Keep filenames in the Jekyll format +`YYYY-MM-DD-slug.md` when adding a dated post. -- Use imperative mood: "add feature" not "added feature" -- Keep the title under 72 characters -- Reference issue numbers when applicable: "fix auth bug (#42)" -- Keep commits atomic and focused on a single change +When editing existing essays, preserve the author's voice. Improve clarity +without flattening the argument. -## Pull Request Process +## Pull Request Expectations -1. Fill out the PR template with a description of your changes -2. Reference any related issues -3. Ensure all CI checks pass -4. Request review from a maintainer -5. Address review feedback promptly +- Explain what changed and why. +- Link the issue or feedback session when applicable. +- Summarize the checks you ran. +- Keep each PR focused on one correction, essay, or documentation improvement. +- Do not commit secrets, credentials, API keys, tokens, or private data. -PRs should be focused — one feature or fix per PR. Large changes should be -discussed in an issue first. +Large changes are welcome, but they should start as an issue so scope and +review expectations are clear before the work begins. ## Code of Conduct @@ -92,8 +121,7 @@ Be respectful, constructive, and honest. This project is part of the and building in public. We follow the [Contributor Covenant](https://www.contributor-covenant.org/). -## Questions? +## Questions -Open an issue on this repository or start a discussion if discussions are -enabled. For system-wide questions, see +Open an issue on this repository. For system-wide questions, see [orchestration-start-here](https://github.com/organvm-iv-taxis/orchestration-start-here). diff --git a/README.md b/README.md index ba3a4ba..ca42ca6 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,10 @@ > Building in public: the methodology, cross-validation cycle, and lessons learned from coordinating ~79 repositories across 8 GitHub organizations using AI agents as an ensemble of specialized reviewers. +This repository is ORGAN-V's public essay site. The complete dated essay corpus +lives in `_posts/`, curated long-form essays live in `essays/`, and contributor +guidance starts in [`CONTRIBUTING.md`](CONTRIBUTING.md). + [Introduction](#introduction) | [The Eight-Organ Model](#the-eight-organ-model) | [Methodology](#methodology) | [The Cross-Validation Cycle](#the-cross-validation-cycle) | [Per-Agent Findings](#per-agent-findings) | [Synthesis](#synthesis) | [Simulating Organizational Scale](#simulating-organizational-scale-in-solo-practice) | [Lessons Learned](#lessons-learned) | [Cross-References](#cross-references) --- diff --git a/_pipeline b/_pipeline new file mode 160000 index 0000000..762919a --- /dev/null +++ b/_pipeline @@ -0,0 +1 @@ +Subproject commit 762919a03a6705a94a8c29425f55007b8861a538 diff --git a/_standards b/_standards new file mode 160000 index 0000000..f07e865 --- /dev/null +++ b/_standards @@ -0,0 +1 @@ +Subproject commit f07e8653cf56e6a1012e833aa24a7d05a6f53884 diff --git a/data/cross-references.json b/data/cross-references.json index c2b0679..87b3de7 100644 --- a/data/cross-references.json +++ b/data/cross-references.json @@ -1,6 +1,6 @@ { "version": "1.1", - "updated": "2026-05-29", + "updated": "2026-07-06", "total": 65, "entries": { "2026-02-10-building-in-public.md": { diff --git a/data/essays-index.json b/data/essays-index.json index ea8fca9..a083402 100644 --- a/data/essays-index.json +++ b/data/essays-index.json @@ -1,6 +1,6 @@ { "version": "1.1", - "updated": "2026-05-29", + "updated": "2026-07-06", "generated_by": "essay-pipeline indexer v0.3.0", "total_essays": 65, "total_words": 175691, diff --git a/data/logs-index.json b/data/logs-index.json index 0de870c..ffdff41 100644 --- a/data/logs-index.json +++ b/data/logs-index.json @@ -1,6 +1,6 @@ { "version": "1.0", - "updated": "2026-05-29", + "updated": "2026-07-06", "generated_by": "essay-pipeline indexer v0.3.0", "total_logs": 458, "total_words": 145314, diff --git a/data/publication-calendar.json b/data/publication-calendar.json index 5218a5f..9ce8374 100644 --- a/data/publication-calendar.json +++ b/data/publication-calendar.json @@ -1,6 +1,6 @@ { "version": "1.2", - "updated": "2026-05-29", + "updated": "2026-07-06", "total_essays": 65, "essays": { "2026-02-10": 5, @@ -34,466 +34,5 @@ "2026-05-25": 1, "2026-05-28": 1, "2026-05-29": 1 - }, - "total_logs": 458, - "logs": { - "2016-11-06": 1, - "2016-11-28": 1, - "2016-11-29": 1, - "2016-11-30": 1, - "2016-12-02": 1, - "2016-12-04": 1, - "2016-12-07": 1, - "2016-12-09": 1, - "2016-12-11": 1, - "2016-12-17": 1, - "2016-12-23": 1, - "2016-12-26": 1, - "2016-12-27": 1, - "2016-12-28": 1, - "2016-12-29": 1, - "2016-12-30": 1, - "2017-01-04": 1, - "2017-01-11": 1, - "2017-02-07": 1, - "2017-03-07": 1, - "2017-04-17": 1, - "2017-04-18": 1, - "2017-04-20": 1, - "2017-04-21": 1, - "2017-07-20": 1, - "2022-12-05": 1, - "2022-12-06": 1, - "2022-12-07": 1, - "2022-12-10": 1, - "2022-12-11": 1, - "2022-12-16": 1, - "2022-12-17": 1, - "2022-12-18": 1, - "2022-12-21": 1, - "2022-12-22": 1, - "2022-12-28": 1, - "2023-01-08": 1, - "2023-01-09": 1, - "2023-01-11": 1, - "2023-01-12": 1, - "2023-01-14": 1, - "2023-01-25": 1, - "2023-01-27": 1, - "2023-02-04": 1, - "2023-02-10": 1, - "2023-02-11": 1, - "2023-02-16": 1, - "2023-02-17": 1, - "2023-02-18": 1, - "2023-02-21": 1, - "2023-02-26": 1, - "2023-02-27": 1, - "2023-03-05": 1, - "2023-03-07": 1, - "2023-03-08": 1, - "2023-03-09": 1, - "2023-03-10": 1, - "2023-03-11": 1, - "2023-03-15": 1, - "2023-03-16": 1, - "2023-03-18": 1, - "2023-03-19": 1, - "2023-03-21": 1, - "2023-03-24": 1, - "2023-03-25": 1, - "2023-03-26": 1, - "2023-03-27": 1, - "2023-03-29": 1, - "2023-03-30": 1, - "2023-03-31": 1, - "2023-04-01": 1, - "2023-04-04": 1, - "2023-04-05": 1, - "2023-04-07": 1, - "2023-04-08": 1, - "2023-04-12": 1, - "2023-04-13": 1, - "2023-04-14": 1, - "2023-04-15": 1, - "2023-04-20": 1, - "2023-04-21": 1, - "2023-04-22": 1, - "2023-04-23": 1, - "2023-04-24": 1, - "2023-05-01": 1, - "2023-05-08": 1, - "2023-05-09": 1, - "2023-05-31": 1, - "2023-06-01": 1, - "2023-06-06": 1, - "2023-06-08": 1, - "2023-06-09": 1, - "2023-06-10": 1, - "2023-06-15": 1, - "2023-06-16": 1, - "2023-07-09": 1, - "2023-07-10": 1, - "2023-08-20": 1, - "2023-08-21": 1, - "2023-08-22": 1, - "2023-08-29": 1, - "2023-08-30": 1, - "2023-09-19": 1, - "2023-09-20": 1, - "2023-09-25": 1, - "2023-09-26": 1, - "2023-10-16": 1, - "2023-11-04": 1, - "2023-11-05": 1, - "2023-11-07": 1, - "2023-11-08": 1, - "2023-11-09": 1, - "2023-11-12": 1, - "2023-11-13": 1, - "2023-11-14": 1, - "2023-11-22": 1, - "2023-11-23": 1, - "2023-12-21": 1, - "2023-12-23": 1, - "2023-12-24": 1, - "2023-12-25": 1, - "2024-01-07": 1, - "2024-01-20": 1, - "2024-02-13": 1, - "2024-02-14": 1, - "2024-02-15": 1, - "2024-02-24": 1, - "2024-03-11": 1, - "2024-03-13": 1, - "2024-03-14": 1, - "2024-03-19": 1, - "2024-03-21": 1, - "2024-03-30": 1, - "2024-03-31": 1, - "2024-04-01": 1, - "2024-04-04": 1, - "2024-04-05": 1, - "2024-04-06": 1, - "2024-04-23": 1, - "2024-04-24": 1, - "2024-04-26": 1, - "2024-04-27": 1, - "2024-04-28": 1, - "2024-04-29": 1, - "2024-04-30": 1, - "2024-05-01": 1, - "2024-05-02": 1, - "2024-05-04": 1, - "2024-05-05": 1, - "2024-05-18": 1, - "2024-05-19": 1, - "2024-05-20": 1, - "2024-05-21": 1, - "2024-06-10": 1, - "2024-06-11": 1, - "2024-06-17": 1, - "2024-06-29": 1, - "2024-06-30": 1, - "2024-07-19": 1, - "2024-07-20": 1, - "2024-07-25": 1, - "2024-07-28": 1, - "2024-08-04": 1, - "2024-08-06": 1, - "2024-08-07": 1, - "2024-09-05": 1, - "2024-09-07": 1, - "2024-09-08": 1, - "2024-09-09": 1, - "2024-09-10": 1, - "2024-09-11": 1, - "2024-09-12": 1, - "2024-09-13": 1, - "2024-09-14": 1, - "2024-09-15": 1, - "2024-09-16": 1, - "2024-09-17": 1, - "2024-09-18": 1, - "2024-10-04": 1, - "2024-10-05": 1, - "2024-10-07": 1, - "2024-10-12": 1, - "2024-11-12": 1, - "2024-11-13": 1, - "2024-11-14": 1, - "2024-11-15": 1, - "2024-11-16": 1, - "2024-11-17": 1, - "2024-11-18": 1, - "2024-11-19": 1, - "2024-11-20": 1, - "2024-11-29": 1, - "2024-11-30": 1, - "2024-12-03": 1, - "2024-12-05": 1, - "2024-12-07": 1, - "2024-12-08": 1, - "2024-12-12": 1, - "2024-12-20": 1, - "2024-12-21": 1, - "2024-12-22": 1, - "2024-12-23": 1, - "2024-12-26": 1, - "2024-12-27": 1, - "2025-01-02": 1, - "2025-01-03": 1, - "2025-01-07": 1, - "2025-01-11": 1, - "2025-01-12": 1, - "2025-01-13": 1, - "2025-01-23": 1, - "2025-01-27": 1, - "2025-01-29": 1, - "2025-01-30": 1, - "2025-02-01": 1, - "2025-02-02": 1, - "2025-02-06": 1, - "2025-02-20": 1, - "2025-02-21": 1, - "2025-03-01": 1, - "2025-03-02": 1, - "2025-03-05": 1, - "2025-03-07": 1, - "2025-03-08": 1, - "2025-03-10": 1, - "2025-03-11": 1, - "2025-03-12": 1, - "2025-03-13": 1, - "2025-03-14": 1, - "2025-03-15": 1, - "2025-03-16": 1, - "2025-03-17": 1, - "2025-03-18": 1, - "2025-03-19": 1, - "2025-03-21": 1, - "2025-03-22": 1, - "2025-03-24": 1, - "2025-03-25": 1, - "2025-03-27": 1, - "2025-03-28": 1, - "2025-03-30": 1, - "2025-03-31": 1, - "2025-04-01": 1, - "2025-04-02": 1, - "2025-04-03": 1, - "2025-04-04": 1, - "2025-04-05": 1, - "2025-04-06": 1, - "2025-04-07": 1, - "2025-04-10": 1, - "2025-04-12": 1, - "2025-04-13": 1, - "2025-04-15": 1, - "2025-04-16": 1, - "2025-04-17": 1, - "2025-04-18": 1, - "2025-04-19": 1, - "2025-04-20": 1, - "2025-04-21": 1, - "2025-04-22": 1, - "2025-04-23": 1, - "2025-04-27": 1, - "2025-04-30": 1, - "2025-05-01": 1, - "2025-05-03": 1, - "2025-05-04": 1, - "2025-05-05": 1, - "2025-05-06": 1, - "2025-05-07": 1, - "2025-05-09": 1, - "2025-05-10": 1, - "2025-05-11": 1, - "2025-05-12": 1, - "2025-05-27": 1, - "2025-05-28": 1, - "2025-05-29": 1, - "2025-06-01": 1, - "2025-06-02": 1, - "2025-06-03": 1, - "2025-06-05": 1, - "2025-06-07": 1, - "2025-06-08": 1, - "2025-06-09": 1, - "2025-06-16": 1, - "2025-06-18": 1, - "2025-06-21": 1, - "2025-06-23": 1, - "2025-06-24": 1, - "2025-06-26": 1, - "2025-07-01": 1, - "2025-07-02": 1, - "2025-07-03": 1, - "2025-07-04": 1, - "2025-07-09": 1, - "2025-07-11": 1, - "2025-07-17": 1, - "2025-07-18": 1, - "2025-07-22": 1, - "2025-07-23": 1, - "2025-07-24": 1, - "2025-07-25": 1, - "2025-07-26": 1, - "2025-07-27": 1, - "2025-07-28": 1, - "2025-07-29": 1, - "2025-07-30": 1, - "2025-07-31": 1, - "2025-08-01": 1, - "2025-08-02": 1, - "2025-08-03": 1, - "2025-08-04": 1, - "2025-08-05": 1, - "2025-08-09": 1, - "2025-08-10": 1, - "2025-08-11": 1, - "2025-08-12": 1, - "2025-08-13": 1, - "2025-08-14": 1, - "2025-08-18": 1, - "2025-08-22": 1, - "2025-08-24": 1, - "2025-08-26": 1, - "2025-08-27": 1, - "2025-08-28": 1, - "2025-08-29": 1, - "2025-09-05": 1, - "2025-09-06": 1, - "2025-09-08": 1, - "2025-09-09": 1, - "2025-09-17": 1, - "2025-09-18": 1, - "2025-09-20": 1, - "2025-09-25": 1, - "2025-09-26": 1, - "2025-09-30": 1, - "2025-10-08": 1, - "2025-10-14": 1, - "2025-10-15": 1, - "2025-10-16": 1, - "2025-10-17": 1, - "2025-10-18": 1, - "2025-10-20": 1, - "2025-10-22": 1, - "2025-10-23": 1, - "2025-10-24": 1, - "2025-10-25": 1, - "2025-10-26": 1, - "2025-10-27": 1, - "2025-10-28": 1, - "2025-10-29": 1, - "2025-10-30": 1, - "2025-10-31": 1, - "2025-11-01": 1, - "2025-11-02": 1, - "2025-11-03": 1, - "2025-11-04": 1, - "2025-11-05": 1, - "2025-11-06": 1, - "2025-11-07": 1, - "2025-11-08": 1, - "2025-11-09": 1, - "2025-11-10": 1, - "2025-11-11": 1, - "2025-11-12": 1, - "2025-11-13": 1, - "2025-11-16": 1, - "2025-11-17": 1, - "2025-11-18": 1, - "2025-11-19": 1, - "2025-11-20": 1, - "2025-11-21": 1, - "2025-11-22": 1, - "2025-11-23": 1, - "2025-11-24": 1, - "2025-12-08": 1, - "2025-12-09": 1, - "2025-12-10": 1, - "2025-12-11": 1, - "2025-12-12": 1, - "2025-12-13": 1, - "2025-12-14": 1, - "2025-12-15": 1, - "2025-12-16": 1, - "2025-12-17": 1, - "2025-12-18": 1, - "2025-12-19": 1, - "2025-12-20": 1, - "2025-12-21": 1, - "2025-12-22": 1, - "2025-12-23": 1, - "2025-12-24": 1, - "2025-12-25": 1, - "2025-12-26": 1, - "2025-12-28": 1, - "2025-12-29": 1, - "2025-12-30": 1, - "2025-12-31": 1, - "2026-01-01": 1, - "2026-01-02": 1, - "2026-01-03": 1, - "2026-01-05": 1, - "2026-01-07": 1, - "2026-01-08": 1, - "2026-01-09": 1, - "2026-01-11": 1, - "2026-01-12": 1, - "2026-01-13": 1, - "2026-01-15": 1, - "2026-01-16": 1, - "2026-01-17": 1, - "2026-01-18": 1, - "2026-01-19": 1, - "2026-01-20": 1, - "2026-01-21": 1, - "2026-01-22": 1, - "2026-01-23": 1, - "2026-01-24": 1, - "2026-01-25": 1, - "2026-01-26": 1, - "2026-01-27": 1, - "2026-01-28": 1, - "2026-01-29": 1, - "2026-01-30": 1, - "2026-01-31": 1, - "2026-02-01": 1, - "2026-02-02": 1, - "2026-02-05": 1, - "2026-02-06": 1, - "2026-02-07": 1, - "2026-02-08": 1, - "2026-02-09": 1, - "2026-02-10": 1, - "2026-02-11": 1, - "2026-02-12": 1, - "2026-02-13": 1, - "2026-02-14": 1, - "2026-02-15": 1, - "2026-02-16": 1, - "2026-02-17": 1, - "2026-02-18": 1, - "2026-02-19": 1, - "2026-02-20": 1, - "2026-02-21": 1, - "2026-02-22": 1, - "2026-02-23": 1, - "2026-02-24": 1, - "2026-02-25": 1, - "2026-02-26": 1, - "2026-02-27": 1, - "2026-02-28": 1, - "2026-03-01": 1, - "2026-03-02": 1, - "2026-03-03": 1, - "2026-03-04": 1, - "2026-03-05": 1, - "2026-03-06": 1, - "2026-03-07": 1, - "2026-03-08": 1 } } diff --git a/docs/contributor-runway.md b/docs/contributor-runway.md index 67c8b50..685bf05 100644 --- a/docs/contributor-runway.md +++ b/docs/contributor-runway.md @@ -1,19 +1,39 @@ # Contributor Runway -This guide defines how first-time contributors can land meaningful changes quickly. +This guide defines how first-time contributors can land meaningful changes +quickly in `public-process`. ## Fast Start -1. Clone with submodules and run bootstrap: +### Content Map -```bash -git clone --recurse-submodules -cd organvm-v-logos -./tools/bootstrap_dev.sh -``` +- `_posts/` is the complete dated essay corpus. +- `essays/` is the curated long-form essay collection. +- Root Markdown files such as `index.md` and `about.md` are site pages. +- `data/` contains generated indexes and should not be edited by hand unless an + issue explicitly asks for it. -2. Pick a scoped issue labeled `good first issue`. -3. Run `./validate.sh` before opening a PR. +### First Steps + +1. Pick a scoped issue labeled `good first issue`, `documentation`, or + `research`. +2. For local preview, install dependencies and run Jekyll: + + ```bash + git clone https://github.com/YOUR_USERNAME/public-process.git + cd public-process + bundle install + bundle exec jekyll serve + ``` + +3. Before opening a PR, run the check that matches the change: + + - Docs-only change: preview the Markdown and self-review links. + - Essay, layout, include, or config change: + + ```bash + bundle exec jekyll build --strict_front_matter --future + ``` ## First Contribution Scope @@ -23,6 +43,7 @@ A first contribution should: - Have clear acceptance criteria. - Be testable with existing workflows. - Avoid cross-repo architectural refactors. +- Avoid new organvm vocabulary unless it is defined in the same change. ## Review SLA Targets @@ -33,9 +54,10 @@ A first contribution should: ## Required PR Evidence - What changed and why. -- Validation output summary. +- Validation output summary, or a note that the change was docs-only. - Linked issue with acceptance criteria. ## Escalation -If blocked for >7 days without review, open a `documentation` issue in `organvm-v-logos/.github` with link to the PR and blocker details. +If blocked for more than 7 days without review, comment on the PR with the +current blocker and the smallest maintainer action needed. diff --git a/docs/quality-policy.md b/docs/quality-policy.md index 498d0ca..6dc2a4c 100644 --- a/docs/quality-policy.md +++ b/docs/quality-policy.md @@ -5,32 +5,43 @@ This document defines minimum quality guarantees for changes merged into `public ## Guarantees 1. Content schema integrity: -- Every essay in `_posts/` must pass `essay-pipeline` frontmatter validation. -- Every log in `_logs/` must pass log-schema validation. + - Every essay in `_posts/` must pass `essay-pipeline` frontmatter validation. + - Every log in `_logs/` must pass log-schema validation. 2. Derived artifact integrity: -- Changes to essays/logs require regenerated `data/*.json` artifacts. -- CI fails if data drift is detected. + - Changes to essays/logs require regenerated `data/*.json` artifacts. + - CI fails if data drift is detected. 3. Build integrity: -- Jekyll strict build must pass (`bundle exec jekyll build --strict_front_matter --future`). + - Jekyll strict build must pass (`bundle exec jekyll build --strict_front_matter --future`). 4. Link integrity: -- Internal links in essays/logs must pass automated checks. + - Internal links in essays/logs must pass automated checks. 5. Secret hygiene: -- No secrets, tokens, keys, or credentials may be committed. + - No secrets, tokens, keys, or credentials may be committed. ## Local Verification Contract -Before opening a PR: +There is no repo-local `validate.sh` wrapper in this repository. Use the check +that matches the files changed, and let CI run the full shared pipeline. + +For docs-only changes: + +- Preview the Markdown. +- Self-review internal links. +- Confirm no secrets, credentials, API keys, tokens, or private data were added. + +For Jekyll content, layout, include, or configuration changes: ```bash -./tools/bootstrap_dev.sh -./validate.sh +bundle exec jekyll build --strict_front_matter --future ``` -If `validate.sh` fails, treat it as a release blocker. +For `_posts/` or `_logs/` changes, CI also checks frontmatter, internal links, +and generated `data/` drift using the shared `essay-pipeline` and +`editorial-standards` repositories. If CI reports drift, regenerate the data +artifacts and include them in the PR. ## Exceptions