From 2885d4177aae813d52fc0f65bbeb665a554bcedc Mon Sep 17 00:00:00 2001 From: Tobias Wilken Date: Tue, 6 Jan 2026 09:05:50 +0100 Subject: [PATCH] docs: restructure documentation for better navigation - Rewrite README.md with clear navigation for three purposes: 1. Understanding the worlddriven idea (links to philosophy docs) 2. Architecture overview (links to new ARCHITECTURE.md) 3. Repository management (REPOSITORIES.md functionality) - Add ARCHITECTURE.md with: - System overview diagram - Component descriptions (core, webapp, documentation) - GitHub Apps explanation - Data flow diagrams (PR voting, migration, org sync) - Voting algorithm documentation - Update github-apps/README.md: - Link to architecture docs - Document backend implementation endpoints - Update worlddriven-migrate.json manifest: - Add installation event (fires on initial app install) - Keep installation_repositories event (fires on repo additions) --- ARCHITECTURE.md | 265 +++++++++++++++++++++++++++ README.md | 184 +++++++++---------- github-apps/README.md | 11 ++ github-apps/worlddriven-migrate.json | 1 + 4 files changed, 367 insertions(+), 94 deletions(-) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..a5a5be6 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,265 @@ +# Worlddriven Architecture + +This document describes the high-level architecture of worlddriven. For implementation details, see the individual repository documentation. + +## System Overview + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ GitHub │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ User Repos │ │ worlddriven │ │ GitHub Apps │ │ +│ │ with WD app │ │ org repos │ │ (2 apps) │ │ +│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ +└─────────┼─────────────────┼─────────────────┼───────────────────────┘ + │ webhooks │ │ installation + ▼ ▼ ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ Worlddriven Core │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Webhook │ │ Voting │ │ Migration │ │ +│ │ Handler │ │ Engine │ │ Handler │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ │ +│ ┌──────▼──────┐ │ +│ │ MongoDB │ │ +│ └─────────────┘ │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ Worlddriven Webapp │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Dashboard │ │ Repository │ │ OAuth │ │ +│ │ │ │ Management │ │ Flow │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +## Components + +### Core (Backend) + +**Repository**: [worlddriven/core](https://github.com/worlddriven/core) + +The core backend handles all voting logic and GitHub integration: + +| Component | Responsibility | +|-----------|----------------| +| **Webhook Handler** | Receives GitHub events (PR opened, review submitted, etc.) | +| **Voting Engine** | Calculates merge coefficients based on time and reviews | +| **Status Updates** | Posts commit statuses showing merge timeline | +| **Auto-merge** | Merges PRs when voting threshold reached | +| **Migration Handler** | Processes repository transfers via migrate app | + +**Key Technologies**: Node.js, Express, MongoDB + +### Webapp (Frontend) + +**Repository**: [worlddriven/webapp](https://github.com/worlddriven/webapp) + +The webapp provides the user interface: + +| Component | Responsibility | +|-----------|----------------| +| **Dashboard** | Shows repositories and their PR status | +| **Repository Management** | Enable/disable worlddriven, configure settings | +| **OAuth Flow** | GitHub authentication | + +**Key Technologies**: React, Vite + +### Documentation (This Repository) + +**Repository**: [worlddriven/documentation](https://github.com/worlddriven/documentation) + +This repository serves dual purposes: + +1. **Documentation** - Project philosophy, architecture, guides +2. **Organization Management** - REPOSITORIES.md defines org structure + +| Component | Responsibility | +|-----------|----------------| +| **REPOSITORIES.md** | Source of truth for org repositories | +| **Automation Scripts** | Drift detection, sync, parsing | +| **GitHub Actions** | Automated enforcement of desired state | +| **GitHub App Manifests** | App configuration documentation | + +**Key Technologies**: Node.js, GitHub Actions + +## GitHub Apps + +Worlddriven uses two GitHub Apps, following the principle of least privilege: + +### WorldDriven (Main App) + +**Purpose**: PR voting and auto-merge + +**Permissions**: +- `checks: write` - Create/update check runs +- `contents: write` - Merge pull requests +- `issues: write` - Comment on PRs +- `metadata: read` - Basic repository info +- `pull_requests: write` - Update PR status +- `statuses: write` - Post commit statuses +- `workflows: write` - Trigger workflow runs + +**Events**: +- `pull_request` - PR opened, closed, synchronized +- `pull_request_review` - Review submitted +- `push` - Code pushed + +### WorldDriven Migrate + +**Purpose**: One-time repository transfers to worlddriven org + +**Permissions**: +- `administration: write` - Transfer repositories +- `metadata: read` - Basic repository info + +**Events**: +- `installation` - App installed (with repos) +- `installation_repositories` - Repos added to existing installation + +See [github-apps/](github-apps/) for manifest files. + +## Data Flow + +### PR Voting Flow + +``` +1. User opens PR on repo with WorldDriven app installed + │ +2. GitHub sends pull_request webhook to Core + │ +3. Core calculates initial voting coefficient + │ - Base merge time (configurable, default 10 days) + │ - Per-commit time adjustment + │ +4. Core posts commit status: "Merge at [date]" + │ +5. Reviewer submits review (approve/request changes) + │ +6. GitHub sends pull_request_review webhook to Core + │ +7. Core recalculates coefficient + │ - Fetch reviewer's contribution history + │ - Calculate vote weight (commits / total commits) + │ - Approve: reduces time, Request Changes: increases time + │ +8. Core updates commit status with new merge date + │ +9. When coefficient >= 1.0, Core merges the PR +``` + +### Repository Migration Flow + +``` +1. User adds entry to REPOSITORIES.md with Origin field + │ +2. PR is created, reviewed, and merged via worlddriven voting + │ +3. User installs WorldDriven Migrate app on their repo + │ +4. GitHub sends installation webhook to Core + │ +5. Migration Handler checks for approved migration PR + │ +6. If approved, transfers repository to worlddriven org + │ +7. Comments on PR and triggers CI re-run +``` + +### Organization Sync Flow + +``` +1. REPOSITORIES.md is modified + │ +2. PR created and merged via worlddriven voting + │ +3. GitHub Actions triggers sync workflow + │ +4. Scripts parse REPOSITORIES.md (desired state) + │ +5. Scripts fetch GitHub API (actual state) + │ +6. Drift detection compares states + │ +7. Sync applies changes to match desired state + │ +8. Protected repos (documentation, core, webapp) skip destructive changes +``` + +## Voting Algorithm + +The voting coefficient determines when a PR merges: + +``` +coefficient = time_factor + vote_factor + +time_factor = hours_since_opened / base_merge_hours + +vote_factor = Σ (vote_value × voter_weight) + where: + vote_value = +1 for approve, -1 for request changes + voter_weight = voter_commits / total_repo_commits + +PR merges when: coefficient >= 1.0 +``` + +### Example + +- Base merge time: 240 hours (10 days) +- PR open for 120 hours (5 days) +- Reviewer A (10% of commits) approves: +0.1 +- Reviewer B (5% of commits) requests changes: -0.05 + +``` +coefficient = (120/240) + 0.1 - 0.05 + = 0.5 + 0.05 + = 0.55 + +PR needs coefficient >= 1.0, so it will wait longer or need more approvals. +``` + +## Deployment + +### Production URLs + +| Service | URL | +|---------|-----| +| Main site | https://www.worlddriven.org | +| API | https://www.worlddriven.org/api | +| Webapp | https://worlddriven-webapp.tooangel.com | + +### Infrastructure + +- **Hosting**: Dokku on dedicated server +- **Database**: MongoDB +- **CI/CD**: GitHub Actions + +## Security Considerations + +### Vote Manipulation Prevention + +- Vote weight based on historical commits (not easily faked) +- All votes are public (GitHub reviews) +- Transparent calculation shown in status + +### Repository Protection + +- Critical repos (documentation, core, webapp) have additional protections +- Sync automation won't delete protected repos +- Branch protection rules enforced + +### App Permissions + +- Minimal permissions per app (least privilege) +- Separate app for admin operations (migration) +- All webhook payloads verified + +## Related Documentation + +- [AUTOMATION.md](AUTOMATION.md) - Detailed automation guide +- [REPOSITORIES.md](REPOSITORIES.md) - Repository configuration format +- [scripts/README.md](scripts/README.md) - Script API reference +- [github-apps/README.md](github-apps/README.md) - GitHub App details diff --git a/README.md b/README.md index f2e8aa2..76398d2 100644 --- a/README.md +++ b/README.md @@ -1,140 +1,136 @@ -# Worlddriven: Democratic Governance for Open Source +# Worlddriven Documentation -**Worlddriven is democratic governance for open source software. It transforms code contributions into voting power, giving every contributor both the ability and responsibility to steer project direction. By replacing maintainer bottlenecks with community-driven decision making, worlddriven ensures projects remain alive, responsive, and truly collaborative.** +**Worlddriven is democratic governance for open source software.** It transforms code contributions into voting power, giving every contributor both the ability and responsibility to steer project direction. -## The Democracy Problem in Open Source +## Quick Navigation -Open source software powers the modern world, yet its governance remains fundamentally undemocratic. This creates critical vulnerabilities that threaten the sustainability and integrity of projects we all depend on. +| I want to... | Go to | +|--------------|-------| +| Understand the worlddriven idea | [Philosophy](#the-worlddriven-idea) | +| See how the system works | [Architecture](ARCHITECTURE.md) | +| Add a repository to worlddriven org | [Repository Management](#repository-management) | +| Contribute to worlddriven | [Contributing](CONTRIBUTING.md) | +| Learn about the automation | [Automation](AUTOMATION.md) | -### Maintainer Bottlenecks -- **58% of maintainers** have abandoned or considered abandoning projects due to burnout -- Over **three-quarters receive no compensation** while projects die when they become overwhelmed - -### Ignored Contributors -Research reveals a "wasteland of good patches that were completely ignored"—valuable improvements receive no response, leading contributors to abandon participation and creating barriers to democratic involvement. - -### Corporate Takeovers -Projects like **MongoDB and Redis** changed licenses to prevent exploitation, creating **governance tensions** between community interests and corporate control. License changes can effectively privatize community work. - -### Fork Wars -Famous conflicts like **GCC/EGCS**, **Emacs/XEmacs**, and **BSD fragmentation** split communities and waste resources due to maintainer disagreements over project direction. +--- -## What is Worlddriven? +## The Worlddriven Idea -Worlddriven revolutionizes open source governance by implementing democratic decision-making that scales with contribution. +Open source software powers the modern world, yet its governance remains fundamentally undemocratic. Maintainer burnout, ignored contributions, corporate takeovers, and fork wars threaten projects we all depend on. -### Power Through Participation -Your first commit gives you a voice in the project's future. Continued contributions build your influence, creating a direct democracy where those who do the work make the decisions. +**Worlddriven solves this through democratic decision-making:** -### Shared Responsibility -Contributors don't just submit code—they become stewards of the project's future. With voting power comes accountability for the project's direction, quality, and community health. +- **Power Through Participation** - Your first commit gives you a voice. Continued contributions build influence. +- **Time-based Auto-merge** - PRs merge after a configurable period (default: 10 days) +- **Community Voting** - Approvals speed up merges, change requests slow or block them +- **Weighted Votes** - Vote power is proportional to historical contributions +- **No Single Points of Failure** - The community collectively stewards the project -### Time-based Auto-merge -Pull requests automatically merge after a configurable time period (default: 10 days), but community votes can accelerate or block merges: -- **Positive reviews** from contributors reduce merge time -- **Change requests** increase merge time or block merging entirely -- **Vote weight** is proportional to the reviewer's historical contributions -- **Transparent calculations** show exactly how decisions are made +### Learn More -### Eliminates Single Points of Failure -No more projects dying because one maintainer burns out. The community collectively shoulders both the burden and benefits of project stewardship. +- [Philosophy](PHILOSOPHY.md) - Democratic software development principles +- [Responsibility Model](RESPONSIBILITY.md) - How contributor power and accountability scale +- [Real-World Examples](EXAMPLES.md) - Case studies of governance failures worlddriven prevents -## Organization Management +--- -This repository practices what it preaches: **the worlddriven organization itself is managed democratically through pull requests**. Infrastructure decisions follow the same democratic process as code. +## Architecture -### How It Works -- **[REPOSITORIES.md](REPOSITORIES.md)** defines all repositories in our organization -- Proposed changes create pull requests that show exactly what will change -- After democratic review and merge, automation applies changes to GitHub -- All infrastructure decisions are transparent, reversible, and community-driven - -### Democratic Infrastructure -Our automation enforces: -- Standard configurations for democratic governance (squash-only merges, branch protection) -- Protected critical repositories (documentation, core, webapp) -- Transparent sync reports showing all changes +Worlddriven consists of three main components: -**Learn more**: [AUTOMATION.md](AUTOMATION.md) - Complete guide to our infrastructure automation +| Component | Purpose | Repository | +|-----------|---------|------------| +| **Core** | Backend API, voting engine, webhook handling | [worlddriven/core](https://github.com/worlddriven/core) | +| **Webapp** | User interface for managing repositories | [worlddriven/webapp](https://github.com/worlddriven/webapp) | +| **Documentation** | This repo - org governance and docs | [worlddriven/documentation](https://github.com/worlddriven/documentation) | -**Current repositories**: [View on GitHub](https://github.com/orgs/worlddriven/repositories) +### GitHub Apps -## Real-World Examples Where Worlddriven Would Help +Worlddriven uses two GitHub Apps following the principle of least privilege: -**Redis Creator's Departure**: Salvatore Sanfilippo stepped down in 2020, saying "I'm asked more and more to maintain the project more. This is not what I want to do." Worlddriven distributes maintenance burden across the contributor community. +| App | Purpose | Permissions | +|-----|---------|-------------| +| [WorldDriven](https://github.com/apps/worlddriven) | PR voting and auto-merge | checks, contents, pull_requests, statuses | +| [WorldDriven Migrate](https://github.com/apps/worlddriven-migrate) | Repository transfers | administration | -**Ignored Patches**: Many projects systematically ignore good contributions, leading to contributor abandonment. Worlddriven's automatic merge system ensures every contribution gets proper consideration. +See [github-apps/](github-apps/) for manifest files and technical details. -**MongoDB License Change**: When MongoDB changed to SSPL to prevent cloud vendor exploitation, it created uncertainty. Worlddriven's democratic process would let the community collectively decide license changes. +### How It Works -**GCC/EGCS Fork**: This split eventually reunited when EGCS had better community support. Worlddriven's voting would have revealed this preference earlier, preventing the fork entirely. +``` +1. User installs WorldDriven app on their repository +2. PRs trigger webhooks to the Core backend +3. Core calculates voting coefficients based on: + - Time since PR opened + - Contributor reviews (approve/request changes) + - Reviewer's historical contribution weight +4. Status checks show current merge timeline +5. PR auto-merges when coefficient threshold reached +``` -## The Responsibility Model +For detailed architecture, see [ARCHITECTURE.md](ARCHITECTURE.md). -### Entry Level: First Contribution = First Vote = First Responsibility -Making your first commit immediately grants voting rights and begins your stewardship role in the project's future. You're no longer just a user—you're an owner. +--- -### Growing Influence: More Contributions = Greater Stewardship -Your voting power scales with your investment in the project. Long-term contributors naturally gain more influence, but newcomers can quickly earn significant voice through quality contributions. +## Repository Management -### Collective Ownership -Everyone who contributes owns and is responsible for the outcome. This creates a culture of investment rather than extraction, where contributors think long-term because they control the project's destiny. +This documentation repository serves a special purpose: **it defines and manages all repositories in the worlddriven organization**. -### Democratic Leadership, Not Dictatorship -Veteran contributors become democratic leaders who guide through influence and example, not absolute authority. Their expertise carries weight, but the community makes collective decisions. +### How It Works -## How Worlddriven Changes the Game +1. **[REPOSITORIES.md](REPOSITORIES.md)** is the source of truth for org repositories +2. Changes to REPOSITORIES.md create PRs that show exactly what will change +3. After democratic review and merge, automation syncs changes to GitHub +4. All infrastructure decisions are transparent, reversible, and community-driven -**From Spectator to Stakeholder**: Your first contribution makes you an immediate stakeholder with both power and responsibility for project success. +### What You Can Do -**Prevents Corporate Capture**: Collective decision-making means no single entity can unilaterally change licenses, direction, or governance. +| Action | How | +|--------|-----| +| **Add a repository** | Add entry to REPOSITORIES.md, create PR | +| **Migrate a repository** | Add with `Origin` field, install migrate app | +| **Update settings** | Modify entry in REPOSITORIES.md | +| **Archive a repository** | Set `Archived: true` in entry | -**Reduces Fork Necessity**: Disagreements resolve through democratic process rather than community fragmentation, focusing energy on collaborative improvement. +### Automation -**Sustainable Participation**: Distributing power and responsibility creates sustainable models that don't depend on individual heroics or burnout-prone maintainership. +The automation enforces: +- Standard configurations (squash-only merges, branch protection) +- Protected critical repositories (documentation, core, webapp) +- Drift detection between desired and actual state -## The Vision: Three Phases +See [AUTOMATION.md](AUTOMATION.md) for the complete automation guide. -### Phase 1 (Current): Democratic Pull Request Merging -- Solves immediate maintainer bottleneck problems -- Proves democratic governance concept works at scale -- Establishes contributor responsibility culture -- Currently deployed at [www.worlddriven.org](https://www.worlddriven.org) +--- -### Phase 2: Transparent Service Management -- Entire services managed via pull requests -- Infrastructure as Code meets democracy -- Community-driven operational decisions with shared accountability -- Server configurations, deployments, and policies decided collectively +## Getting Started -### Phase 3: Self-Governing Software Ecosystem -- Minimal human intervention required -- Fully automated, transparent infrastructure -- True digital democracy where contributors collectively own all outcomes -- Software that governs itself through democratic contributor consensus +### For Users -## Why Now? +Visit [www.worlddriven.org](https://www.worlddriven.org) to enable worlddriven for your repositories. -**The Crisis is Real**: Open source faces widespread maintainer burnout, corporate capture, and a democratic deficit in software running the world's infrastructure. +### For Contributors -**The Infrastructure Exists**: GitHub and GitLab provide the technical foundation. The challenge is governance—which worlddriven solves. +See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute to worlddriven itself. -**Community Readiness**: Growing awareness of governance problems creates demand for solutions. Contributors want meaningful participation, not just code submission privileges. +### For Developers -**Proven Principles**: Democratic governance works in other contexts. Worlddriven adapts these principles for software, creating accountability through transparency and shared ownership. +- [Core repository](https://github.com/worlddriven/core) - Backend implementation +- [Webapp repository](https://github.com/worlddriven/webapp) - Frontend implementation +- [scripts/](scripts/) - Automation scripts reference -## Get Started +--- -Visit [www.worlddriven.org](https://www.worlddriven.org) to enable worlddriven for your repositories. Join the growing movement toward democratic, transparent, and sustainable open source governance. +## The Vision -**Ready to take responsibility for the software you help create?** +| Phase | Focus | Status | +|-------|-------|--------| +| **Phase 1** | Democratic PR merging | Current | +| **Phase 2** | Transparent service management | Planned | +| **Phase 3** | Self-governing software ecosystem | Future | --- -*Learn more about the principles behind worlddriven:* -- [Responsibility Model](RESPONSIBILITY.md) - How contributor power and accountability scale together -- [Real-World Examples](EXAMPLES.md) - Detailed case studies of governance failures worlddriven prevents -- [Philosophy](PHILOSOPHY.md) - Democratic software development principles -- [Automation](AUTOMATION.md) - How this organization manages itself democratically +## License -*Technical implementation details are available in the [core repository](../core/README.md).* \ No newline at end of file +AGPL-3.0 - See [LICENSE](LICENSE) diff --git a/github-apps/README.md b/github-apps/README.md index 0b262e4..73ce88d 100644 --- a/github-apps/README.md +++ b/github-apps/README.md @@ -2,6 +2,8 @@ This directory contains the manifest files for WorldDriven's GitHub Apps. These manifests define the permissions, events, and configuration for each app. +For how these apps fit into the overall system, see [ARCHITECTURE.md](../ARCHITECTURE.md). + ## Apps Overview | App | Purpose | Permissions | @@ -77,6 +79,15 @@ GitHub Apps cannot be updated via API. To change permissions or settings: **Note**: When permissions are added, existing installations must approve the new permissions. +## Backend Implementation + +The webhook handlers for these apps are implemented in the [core repository](https://github.com/worlddriven/core): + +| App | Webhook Endpoint | Handler | +|-----|------------------|---------| +| WorldDriven | `/api/webhooks/github` | `webhookHandler.js` | +| WorldDriven Migrate | `/api/webhooks/migrate` | `migrationHandler.js` | + ## References - [GitHub App Manifest Flow](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) diff --git a/github-apps/worlddriven-migrate.json b/github-apps/worlddriven-migrate.json index 56863a6..be4e2a4 100644 --- a/github-apps/worlddriven-migrate.json +++ b/github-apps/worlddriven-migrate.json @@ -7,6 +7,7 @@ "description": "One-time repository migration to the worlddriven organization.\n\nThis app enables automated transfer of your repository to the worlddriven org after your migration PR has been approved by the community.\n\nHow It Works:\n1. Create a PR adding your repository to REPOSITORIES.md\n2. Wait for community approval through worlddriven voting\n3. Install this app on your repository\n4. Your repository is automatically transferred to the worlddriven org\n5. The PR auto-merges once the transfer completes\n\nThis app only requires Administration permission to perform the one-time transfer. You can uninstall it after migration is complete.\n\nNote: This is a separate app from the main WorldDriven app to keep permissions minimal. The main app handles PR voting and auto-merge; this app only handles repository transfers.", "public": true, "default_events": [ + "installation", "installation_repositories" ], "default_permissions": {