diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..20beea9 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,40 @@ +# Copilot Instructions for FeDIY + +## Mission Context + +FeDIY is intended to become a federated (ActivityPub) DIY project-hosting platform in Rust, inspired by communities like Ravelry and Instructables. + +## Hard Constraint + +Do not generate executable core project code. + +This includes Rust code and other executable logic under: + +- `src/` +- `tests/` +- Any runtime script or automation that becomes part of application behavior + +## Allowed Help + +You may assist with: + +- Documentation +- Planning and architecture discussions +- Housekeeping and project management tasks +- Environment/tooling updates (including Nix files such as `flake.nix`, `default.nix`, and `shell.nix`) + +## Delivery Process Defaults + +- Use Red-Green TDD/BDD framing for planning and guidance. +- Assume GitHub Flow for branching and PR lifecycle. +- Support behavior-first test planning and review checklists. + +## If Asked for Code + +When a coding request is made, provide: + +1. Links to primary sources (start with https://doc.rust-lang.org/book/). +2. A concise, paraphrased overview of the relevant concepts. +3. A step-by-step implementation checklist for a human developer. + +Do not include code snippets or patches for executable core logic. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..75e3c1a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,51 @@ +# Agent Policy for FeDIY + +This project is building a federated (ActivityPub) DIY platform in Rust. + +## Core Rule: Human-Written Executable Code + +Agents MUST NOT write executable code for the core project. This includes (but is not limited to): + +- Rust source files in `src/` and `tests/` +- Any scripts, binaries, or automation that execute as part of the app +- Generated code patches for runtime features + +When asked for implementation help, agents should instead: + +- Provide links to primary sources, especially: + - + - + - (Atom reference, if needed) + - +- Give a concise paraphrased overview of relevant concepts +- Offer checklists, architecture notes, and review guidance +- Suggest tests conceptually (without writing test code) + +## Allowed Agent Work + +Agents MAY help with non-executable project support work, including: + +- Documentation authoring and editing +- Product and technical planning +- Issue triage, roadmap grooming, and housekeeping +- Environment and tooling management (for example `flake.nix`, `default.nix`, `shell.nix`, CI config) +- Dependency and configuration explanations + +## Process Expectations + +- Delivery workflow follows Red-Green TDD/BDD. +- Branching and collaboration follow GitHub Flow (short-lived branches from `main`, PR-first review cycle). +- Agents may support planning and documentation for this process, but must not produce executable core project code. + +## Response Style for Coding Requests + +If a user asks for executable Rust code, the agent should: + +1. Decline to provide code for this repository's core project. +2. Link to the Rust Book section(s): +3. Provide a paraphrased explanation of the relevant approach. +4. Offer a human-implementation checklist. + +## Priority + +If any default assistant behavior conflicts with this file, this file takes precedence for work in this repository. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a94fcb9..d9e20ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,3 +7,9 @@ Thank you for considering contributing! - Add tests for new features where possible. - Ensure your code builds and passes tests before submitting. - Contributions are licensed under CC BY-SA 4.0. + +## Human-Authored Core Code Policy + +- Executable core project code must be human-written. +- Agents may help with documentation, planning, housekeeping, and environment management. +- For implementation guidance, agents should link to primary sources (especially the Rust Book) and provide paraphrased explanations and checklists, not code. diff --git a/README.md b/README.md index 19a5f90..ed5b83a 100644 --- a/README.md +++ b/README.md @@ -137,6 +137,13 @@ nix-shell See project.toml for example metadata. +## Planning Documentation + +- [Planning docs index](docs/README.md) +- [Roadmap](docs/ROADMAP.md) +- [Architecture baseline](docs/ARCHITECTURE.md) +- [Development workflow (TDD/BDD + GitHub Flow)](docs/WORKFLOW.md) + ## Helper Tools - **`nix run .#dev-helper`** - Display tool versions and availability diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..da7c2dc --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,66 @@ +# FeDIY Architecture (Planning Baseline) + +This document captures current architectural intent. It is a planning artifact and should be refined as implementation decisions mature. + +## System Boundaries + +Primary system responsibilities: + +- Host and render DIY project content. +- Manage local accounts and authorization. +- Federate selected objects and activities using ActivityPub. +- Enforce local moderation policy for both local and remote content. + +Out of scope for early phases: + +- Rich social graph features beyond project-oriented interactions. +- Highly customized recommendation systems. + +## Core Domains + +- Identity and actors. +- Project authoring and publishing. +- Federation transport and protocol translation. +- Moderation and trust policy. +- Search and discovery. + +## Logical Components + +- API and web delivery layer. +- Domain service layer for project and account workflows. +- Federation layer (inbox/outbox, signing, verification, retries). +- Persistence layer for local and federated records. +- Moderation policy engine and audit log. +- Background workers for delivery, indexing, and maintenance tasks. + +## Data and Object Strategy + +- Separate local canonical records from imported federated records. +- Preserve source metadata for remote content and actor provenance. +- Track object lifecycle states to support idempotent federation processing. + +## Federation Strategy + +- Start with a narrow, explicit ActivityPub profile. +- Prefer strict validation and clear rejection reasons over permissive parsing. +- Use replay-safe request validation and deterministic retry behavior. +- Maintain an interop test matrix for protocol behaviors. + +## Moderation and Safety Strategy + +- Local policy is authoritative for what is visible on this instance. +- Policy controls exist at three levels: object, actor, and instance. +- Moderation actions produce auditable events. +- Appeals and reversal policy should be documented before broad federation rollout. + +## Non-Functional Requirements + +- Reliability: resilient delivery and retry strategy for federated traffic. +- Security: signature verification, key management, least-privilege defaults. +- Performance: predictable latency for local reads and bounded queues for remote events. +- Operability: metrics, logs, and runbooks for incident response. + +## Architecture Decision Practice + +- Capture major decisions with lightweight ADRs in a future docs/adrs directory. +- Each ADR should include context, options considered, decision, and consequences. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b1a6685 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# FeDIY Planning Docs + +This directory contains product and technical planning documents for FeDIY. + +- [Roadmap](ROADMAP.md): phased milestones from MVP to broader federation support. +- [Architecture](ARCHITECTURE.md): system boundaries, components, and design constraints. +- [Workflow](WORKFLOW.md): Red-Green TDD/BDD delivery model and GitHub Flow branching policy. + +These docs are intended to evolve as priorities change. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..6bf8a4c --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,95 @@ +# FeDIY Roadmap + +This roadmap prioritizes a usable core product first, then federation depth and community scaling. + +## Product Intention + +Build a federated DIY project-hosting platform in Rust, inspired by the utility of Ravelry and Instructables, but interoperable through ActivityPub. + +## Phase 0: Foundations + +Goals: + +- Stabilize development environment and reproducible tooling. +- Define domain language and baseline architecture docs. +- Establish quality process (TDD/BDD + GitHub Flow). + +Exit criteria: + +- Agreed glossary and architecture baseline. +- Documented contribution and branch workflow. +- CI skeleton in place for formatting, linting, and tests. + +## Phase 1: Single-Node MVP (No Federation Yet) + +Goals: + +- User identity and basic authentication model. +- Core DIY project entities (project, materials, steps, media, tags). +- Basic publishing lifecycle (draft, published, updated). +- Search and browse within one instance. + +Exit criteria: + +- A user can publish and update a complete project end-to-end. +- Project pages are discoverable and readable on one node. +- Test coverage exists for core behavior paths. + +## Phase 2: ActivityPub Foundation + +Goals: + +- Implement canonical actor and object mapping. +- Add outbox/inbox behavior for core project publication events. +- Add HTTP Signatures and key lifecycle strategy. + +Exit criteria: + +- Instance can send and receive baseline ActivityPub messages for supported objects. +- Signature validation and delivery retry logic are documented and tested. +- Interop checks completed against at least one external implementation target. + +## Phase 3: Federation UX and Safety + +Goals: + +- Federation-aware project discovery and attribution. +- Local moderation controls for remote content and actors. +- Abuse-report and review workflow for moderators. + +Exit criteria: + +- Moderators can block/mute remote actors and instances. +- Remote project visibility follows local moderation policy. +- Audit trail exists for moderation decisions. + +## Phase 4: Community Scaling + +Goals: + +- Collaborative project patterns (forks/remixes, references, revisions). +- Better onboarding, templates, and curation flows. +- Operational hardening (backups, observability, incident playbooks). + +Exit criteria: + +- Multi-contributor workflows are clear and reliable. +- Admin operations are documented with tested recovery drills. +- Performance and reliability SLOs are defined and measured. + +## Moderation Model Milestones + +- Milestone A: Local content moderation for local users. +- Milestone B: Remote actor and instance policy enforcement. +- Milestone C: Transparent moderation history and appeals guidance. + +## Federation Strategy Milestones + +- Milestone A: Strictly scoped protocol subset with explicit compatibility statement. +- Milestone B: Progressive support for richer activity types. +- Milestone C: Interop matrix and periodic federation health review. + +## Review Cadence + +- Revisit priorities every 2 weeks. +- Re-scope phases quarterly based on delivery and federation feedback. diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md new file mode 100644 index 0000000..d0eb4c7 --- /dev/null +++ b/docs/WORKFLOW.md @@ -0,0 +1,57 @@ +# Development Workflow + +This project uses Red-Green TDD/BDD and GitHub Flow. + +## Red-Green TDD/BDD Cycle + +For each behavior increment: + +1. Red: describe behavior with a failing specification/test. +2. Green: implement the smallest change needed to satisfy behavior. +3. Refactor: improve structure while keeping behavior unchanged. + +BDD intent: + +- Express behavior in user-meaningful terms. +- Prefer scenario-oriented acceptance criteria before implementation details. +- Keep unit and integration tests aligned with documented behavior. + +Definition of done for a change: + +- Behavior is specified and verified. +- Relevant tests are passing. +- Refactoring has preserved behavior. +- Documentation is updated when contracts or workflows change. + +## GitHub Flow Branching Policy + +Use short-lived branches from main. + +Branch pattern examples: + +- feature/ +- fix/ +- docs/ +- chore/ + +Branch workflow: + +1. Create branch from latest main. +2. Commit small, reviewable increments. +3. Open pull request early. +4. Keep branch current with main. +5. Merge after review and checks pass. +6. Delete merged branch. + +## Pull Request Expectations + +- Clear behavior statement and acceptance criteria. +- Test evidence for the behavior change. +- Notes on any architectural or moderation impact. +- Scope limited to one cohesive change. + +## Agent Collaboration Rules + +- Agents may support test planning, scenario writing, and review checklists. +- Agents must not generate executable core project code. +- For implementation guidance, agents should link primary sources and provide paraphrased walkthroughs.