diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index b1be32a..36629a9 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,102 +1,69 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Changelog - -All notable changes to Project Wharf will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -== [Unreleased] - -=== Added -- Initial project structure -- Rust workspace with wharf-core, wharf-cli, and yacht-agent crates -- DNS zone templates (simple, shared, standard, maximalist) -- Nickel configuration schemas for security policies -- Database policy engine with AST-based SQL filtering (sqlparser 0.39) -- CMS adapters for WordPress, Drupal, Joomla, Moodle -- Shell scripts for zone rendering, auditing, and deployment -- Comprehensive Justfile with 50+ recipes -- RSR (Rhodium Standard Repository) compliance documentation - -=== Local Deployment Proof (2026-02-14) -- *Local compose stack*: `deploy/compose.yaml` with 3-service podman compose (MariaDB, yacht-agent proxy, OpenLiteSpeed+WordPress). Full end-to-end proof. -- *Containerfile bug fixes*: `Containerfile.agent` fixed Wolfi package names (musl→glibc), main `Containerfile` fixed yacht-agent runtime stage (static→wolfi-base to avoid glibc segfault) -- *WordPress adapter fix*: `wharf-adapter.php` now fetches both `/stats` and `/status` endpoints, mapping nested JSON to flat format the widget expects -- *OLS container*: `deploy/Containerfile.ols-local` wrapping litespeedtech/openlitespeed:1.8.5-lsphp83 with WordPress-required PHP extensions -- *Automated setup*: `deploy/local-test.sh` downloads WordPress, fetches real salt keys, generates wp-config.php with `DB_HOST=agent:3306`, copies adapter plugin, builds and starts stack -- *SQL injection verification*: `deploy/verify-sqli.sh` proves 6/6 attacks blocked (SELECT passes, INSERT wp_users/DROP/ALTER/TRUNCATE/UNION all blocked), with live agent stats - -=== V1.0 Shipping Preparation (2026-02-14) -- *Signature scheme feature flag*: Ed448 now opt-in via `SignatureScheme::Hybrid`; default is `MlDsa87Only` (FIPS 204 peer-reviewed). Configurable via `--signature-scheme` CLI arg and TOML config. -- *SQL injection smoke tests*: 19 integration tests proving AST-based proxy blocks real WordPress attack patterns (user creation, options manipulation, content defacement, DDL, stacked injection) -- *Deployment package*: `deploy/setup.sh` first-run script + `deploy/DEPLOY.adoc` step-by-step guide with podman/selur-compose orchestration -- *Hack-me challenge*: `docs/HACK-ME-CHALLENGE.adoc` with rules of engagement, attack surface table, and technical details for security researchers -- *WordPress adapter plugin*: `adapters/wordpress-wharf/` — GPL-2.0-or-later PHP plugin providing dashboard widget (query stats, firewall mode, signature scheme) and admin bar indicator -- *systemd unit*: `infra/systemd/yacht-agent.service` with DynamicUser, ProtectSystem=strict, MemoryDenyWriteExecute, and CAP_BPF -- *Tooling enrollment*: Bot directives for gitbot-fleet (8 bots), panic-attacker security scan workflow, AI manifest updated -- *K9 contractiles*: Nickel configuration templates (Kennel/Yard/Hunt levels) for deployment automation - -=== Production Hardening (2026-02-14) -- *Persistent hybrid keypairs*: Wharf CLI (`~/.wharf/keys/wharf.key`) and Yacht Agent (`/etc/wharf/keys/yacht.key`) now persist Ed448 + ML-DSA-87 keypairs across restarts with proper file permissions (0600 private, 0644 public) -- *Keypair serialization*: Custom binary format with `WHRF` magic, versioning, and optional password encryption via HKDF-SHAKE512 + XChaCha20-Poly1305 -- *eBPF XDP firewall*: Full kernel-level packet filtering with XDP programs and userspace loader (`crates/wharf-ebpf/`) -- *Certificate management*: Complete Nebula certificate lifecycle — CA creation, cert signing, IP allocation, and revocation (`nebula.rs`) -- *Prometheus metrics*: Real-time counters for queries (allowed/blocked/audited), mooring sessions, integrity checks, and moored status at `GET /metrics` -- *Statistics endpoint*: `GET /stats` now returns actual counters instead of placeholder zeros -- *File integrity verification*: Yacht Agent mooring verify phase now checks BLAKE3 manifests against on-disk files when `site_root` is configured -- *HTTP client resilience*: Mooring client configured with 30s timeout, 10s connect timeout, and connection pooling (2 idle per host) -- *Configuration*: Added `key_store_dir` (CLI + agent) and `site_root` (agent) config options - -=== Security -- Implemented AST-based SQL query analysis (not regex) -- Added HTTP header airlock configuration -- Defined filesystem immutability policies -- Configured Nebula mesh network policies -- Added FIDO2/WebAuthn authentication framework - -=== Known Issues -- `ed448-goldilocks` v0.14.0-pre.10 is unaudited — needs third-party audit before production deployment - -== [0.1.0] - 2025-11-26 - -=== Added -- Initial release of Project Wharf -- Core architecture: Wharf (offline controller) + Yacht (runtime enforcer) -- Database "Virtual Sharding" concept -- Zero Trust networking via Nebula -- Support for WordPress, Drupal, Joomla, Moodle - -=== Documentation -- README.adoc with full architecture overview -- SECURITY.md with vulnerability reporting process -- CONTRIBUTING.adoc with TPCF contribution framework -- GOVERNANCE.adoc with decision-making process - ---- - -== Version History Summary - -| Version | Date | Highlights | -|---------|------|------------| -| Unreleased | 2026-02-14 | Local E2E deployment proof, Containerfile fixes, WordPress adapter stats fix, compose stack, SQLi verification | -| 0.1.0 | 2025-11-26 | Initial release | - -== Upgrade Guide - -=== Upgrading to 0.1.0 - -This is the initial release. No upgrade path required. - -== Deprecation Notices - -*None at this time.* - -== Security Advisories - -*None at this time.* - ---- - -[Unreleased]: https://gitlab.com/hyperpolymath/wharf/-/compare/v0.1.0...HEAD -[0.1.0]: https://gitlab.com/hyperpolymath/wharf/-/releases/v0.1.0 +== Changelog + +All notable changes to `+project-wharf+` will be documented in this +file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(snapshot): implement create_snapshot / restore over StateConfig +contract +* feat(core+bin): adopt WP-edition source — mooring client, integrity +updates, config layer +* feat(deploy): containerization + WP-specific deploy + config examples +* feat(adapters): add WordPress integration adapter +* feat(workspace): add xtask + fuzz + ClusterFuzzLite from WP-edition +fork +* feat: Add remote integrity verification and eBPF XDP loader +* feat: Release v1.0.0 - Production-ready Sovereign Web Hypervisor +* feat: Implement v1.0 core functionality - sync, integrity, and fleet +management +* feat: Add Rust eBPF firewall, Wolfi containers, and expanded CLI +* feat: Add RSR (Rhodium Standard Repository) compliance + +==== Fixed + +* fix(licence): #3 Tranche 1 — clear scaffold-placeholder leak +(project-wharf) (#28) +* fix(ci): sync hypatia-scan.yml to canonical (#26) +* fix(ci): rsr-antipattern.yml duplicate heredoc (#25) +* fix: Restore original README content +* fix: Make containers buildable and add smoke test + +==== Documentation + +* docs(flake): annotate KEEP+DEP rationale (standards#102) (#30) +* docs(readme): add SPDX header and/or standard badges +* docs: Update roadmap for v1.0+ with detailed version plans + +==== CI + +* ci(antipattern): fix top-level dir + benchmark/lsp filename matching +(#20) +* ci(antipattern): TS check reads .claude/CLAUDE.md exemption table +(#19) +* ci(antipattern): broaden TS allowlist (cli, mod.ts, lsp-server, +_vscode_, deno-*) (#18) +* ci(antipattern): allowlist legit TS bridge/adapter paths (#17) + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 300909d..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,61 +0,0 @@ - - -# Changelog - -All notable changes to `project-wharf` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(snapshot): implement create_snapshot / restore over StateConfig contract -- feat(core+bin): adopt WP-edition source — mooring client, integrity updates, config layer -- feat(deploy): containerization + WP-specific deploy + config examples -- feat(adapters): add WordPress integration adapter -- feat(workspace): add xtask + fuzz + ClusterFuzzLite from WP-edition fork -- feat: Add remote integrity verification and eBPF XDP loader -- feat: Release v1.0.0 - Production-ready Sovereign Web Hypervisor -- feat: Implement v1.0 core functionality - sync, integrity, and fleet management -- feat: Add Rust eBPF firewall, Wolfi containers, and expanded CLI -- feat: Add RSR (Rhodium Standard Repository) compliance - -### Fixed - -- fix(licence): #3 Tranche 1 — clear scaffold-placeholder leak (project-wharf) (#28) -- fix(ci): sync hypatia-scan.yml to canonical (#26) -- fix(ci): rsr-antipattern.yml duplicate heredoc (#25) -- fix: Restore original README content -- fix: Make containers buildable and add smoke test - -### Documentation - -- docs(flake): annotate KEEP+DEP rationale (standards#102) (#30) -- docs(readme): add SPDX header and/or standard badges -- docs: Update roadmap for v1.0+ with detailed version plans - -### CI - -- ci(antipattern): fix top-level dir + benchmark/lsp filename matching (#20) -- ci(antipattern): TS check reads .claude/CLAUDE.md exemption table (#19) -- ci(antipattern): broaden TS allowlist (cli, mod.ts, lsp-server, *vscode*, deno-*) (#18) -- ci(antipattern): allowlist legit TS bridge/adapter paths (#17) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc index 008e3ed..ff3f3db 100644 --- a/CODE_OF_CONDUCT.adoc +++ b/CODE_OF_CONDUCT.adoc @@ -1,95 +1,339 @@ -= Contributor Covenant Code of Conduct -:toc: +== Code of Conduct -== Our Pledge +=== Our Pledge -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, caste, color, religion, or sexual -identity and orientation. +We as members, contributors, and leaders pledge to make participation in +Squisher Corpus a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. -== Our Standards +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. -Examples of behavior that contributes to a positive environment: +''''' -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes -* Focusing on what is best for the overall community +=== Our Standards -Examples of unacceptable behavior: +==== Expected Behaviour -* The use of sexualized language or imagery, and sexual attention or advances -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information without explicit permission -* Other conduct which could reasonably be considered inappropriate +The following behaviours contribute to a positive environment: -== Enforcement Responsibilities +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers -Community leaders are responsible for clarifying and enforcing our standards -of acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes -== Scope +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way -== Enforcement +==== Unacceptable Behaviour -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at: +The following behaviours are considered harassment and are unacceptable: -* **Email**: conduct@hyperpolymath.net +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions -All complaints will be reviewed and investigated promptly and fairly. +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions -== Enforcement Guidelines +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting -=== 1. Correction +==== Grey Areas -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. +Some situations require judgement. When uncertain: -**Consequence**: A private, written warning, providing clarity around the -nature of the violation and an explanation of why the behavior was +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |j.d.a.jewell@open.ac.uk |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *48 hours* +. The maintainers will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a maintainers member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The maintainers will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. -=== 2. Warning +*Duration*: Immediate -**Community Impact**: A violation through a single incident or series of +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of actions. -**Consequence**: A warning with consequences for continued behavior. -No interaction with the people involved for a specified period of time. +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* j.d.a.jewell@open.ac.uk with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different maintainers member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' -=== 3. Temporary Ban +=== Questions? -**Community Impact**: A serious violation of community standards. +If you have questions about this Code of Conduct: -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. +* Open a +https://github.com/hyperpolymath/squisher-corpus/discussions[Discussion] +(for general questions) +* Email j.d.a.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly -=== 4. Permanent Ban +''''' -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior. +=== Summary -**Consequence**: A permanent ban from any sort of public interaction within -the community. +*Be kind. Be respectful. Be collaborative.* -== Attribution +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. -This Code of Conduct is adapted from the https://www.contributor-covenant.org[Contributor Covenant], -version 2.1. +''''' -Community Impact Guidelines were inspired by -https://github.com/mozilla/diversity[Mozilla's code of conduct enforcement ladder]. +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 8267cd4..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Squisher Corpus a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | j.d.a.jewell@open.ac.uk | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **48 hours** -2. The maintainers will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a maintainers member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The maintainers will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** j.d.a.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different maintainers member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/squisher-corpus/discussions) (for general questions) -- Email j.d.a.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 40dc980..16f545b 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,246 +1,109 @@ -= Contributing to Project Wharf -:toc: left -:icons: font +== Clone the repository -Thank you for your interest in contributing to Project Wharf! This document -outlines our contribution process and the Tri-Perimeter Contribution Framework (TPCF). +git clone https://github.com/hyperpolymath/squisher-corpus.git cd +squisher-corpus -== Tri-Perimeter Contribution Framework (TPCF) +== Using Nix (recommended for reproducibility) -Contributions are organized into three perimeters based on trust level and -expertise required. - -=== Perimeter 3: Community (Open) - -**Who**: Anyone can contribute at this level - -**What you can do**: - -* Report bugs via GitLab Issues -* Suggest features via Discussions -* Improve documentation (typos, clarity) -* Add examples and tutorials -* Translate documentation -* Answer questions in Discussions - -**Process**: - -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Submit a Merge Request -5. Address review feedback - -=== Perimeter 2: Expert Contributors - -**Who**: Contributors who have demonstrated expertise and reliability - -**Eligibility** (meet 2+ criteria): - -* 5+ accepted Perimeter 3 contributions -* Domain expertise (security, Rust, DNS, CMS) -* Vouched by a Core maintainer - -**What you can do**: - -* Review Perimeter 3 contributions -* Implement non-critical features -* Write integration tests -* Create adapters for new CMS platforms -* Improve Nickel configurations - -**Process**: - -1. Request Perimeter 2 access via Issue -2. Core maintainer reviews contribution history -3. If approved, added to `@expert-contributors` group -4. Can now approve Perimeter 3 MRs - -=== Perimeter 1: Core Maintainers - -**Who**: Trusted maintainers with deep project knowledge - -**Eligibility**: - -* Significant Perimeter 2 contributions -* Demonstrated security awareness -* Long-term commitment to the project -* Unanimous approval by existing Core - -**What you can do**: - -* Merge to protected branches -* Release new versions -* Modify security-critical code -* Change architecture decisions -* Manage CI/CD pipelines - -**Process**: - -1. Nominated by existing Core maintainer -2. 2-week community comment period -3. Unanimous Core approval required -4. Added to `@core-maintainers` group - -== Development Setup - -[source,bash] ----- -# Clone the repository -git clone https://gitlab.com/hyperpolymath/wharf.git -cd wharf - -# Using Nix (recommended) nix develop -# Or manually install dependencies -# See README.adoc for requirements - -# Initialize -just init - -# Run tests -just test - -# Run lints -just lint ----- - -== Commit Guidelines - -=== Commit Message Format - -We use Conventional Commits: - -[source] ----- -(): - - - -