From a21a7e32a9d2af7dda7022d65e83b089ae4941f1 Mon Sep 17 00:00:00 2001 From: Tobias Wilken Date: Sat, 8 Nov 2025 07:59:19 +0100 Subject: [PATCH] docs: document CI automation and condense philosophical content Add comprehensive documentation for the repository's automation system while condensing philosophical documents to reduce verbosity. New Documentation: - AUTOMATION.md: Complete guide to CI/automation functionality - How REPOSITORIES.md controls the organization - Drift detection and sync workflows - Standard configurations enforced - Protected repositories policy - Security model and troubleshooting - CONTRIBUTING.md: Repository management workflow - How to add/update/remove repositories - Development guidelines for automation scripts - Pull request and review guidelines - Understanding worlddriven voting - scripts/README.md: Technical reference for automation scripts - Detailed API documentation - CLI usage examples - Development and testing instructions - Troubleshooting guide Updated Documentation: - README.md: Added "Organization Management" section explaining democratic infrastructure management, condensed philosophical content (20-30% reduction) - REPOSITORIES.md: Enhanced header with automation explanation showing what happens when PRs are created and merged - PHILOSOPHY.md: Condensed from 237 to 159 lines (33% reduction) while retaining all core principles and arguments - EXAMPLES.md: Condensed from 239 to 160 lines (33% reduction) while keeping all major case studies - RESPONSIBILITY.md: Condensed from 176 to 122 lines (31% reduction) while maintaining complete responsibility framework Impact: - Automation system now visible and documented for visitors - CI/sync functionality clearly explained with examples - Philosophical content more concise and readable - Overall documentation reduced while adding practical content - Links fixed (removed reference to non-existent VISION.md) Relates to #6 --- AUTOMATION.md | 352 +++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 308 +++++++++++++++++++++++++++++++++++++++ EXAMPLES.md | 237 ++++++++++-------------------- PHILOSOPHY.md | 154 +++++--------------- README.md | 81 +++++------ REPOSITORIES.md | 19 ++- RESPONSIBILITY.md | 132 +++++------------ scripts/README.md | 359 ++++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 1228 insertions(+), 414 deletions(-) create mode 100644 AUTOMATION.md create mode 100644 CONTRIBUTING.md create mode 100644 scripts/README.md diff --git a/AUTOMATION.md b/AUTOMATION.md new file mode 100644 index 0000000..68c489f --- /dev/null +++ b/AUTOMATION.md @@ -0,0 +1,352 @@ +# Organization Automation + +This repository practices what it preaches: **democratic infrastructure management through pull requests**. The worlddriven organization is managed entirely through code, with REPOSITORIES.md as the source of truth. + +## Purpose + +As described in our vision for [Phase 2: Transparent Service Management](README.md#vision-three-phases), infrastructure decisions should be made democratically, just like code. This automation system enables: + +- **Democratic control**: Any contributor can propose organization changes via pull requests +- **Transparency**: All infrastructure changes are visible in git history +- **Consistency**: Standard configurations are automatically enforced +- **Accountability**: Changes are tied to commits and contributors + +## How It Works + +### Source of Truth + +**[REPOSITORIES.md](REPOSITORIES.md)** defines all repositories in the worlddriven organization. When this file changes, automation ensures GitHub matches the desired state. + +```markdown +## repository-name +- Description: Brief description of the repository +- Topics: topic1, topic2, topic3 +``` + +### Automation Workflow + +**1. Pull Request Phase** (Drift Detection) +- You modify REPOSITORIES.md and create a PR +- GitHub Actions automatically runs drift detection +- A comment appears showing exactly what will change: + - Repositories to be created + - Descriptions/topics to be updated + - Repositories to be deleted (with protected repo warnings) + - Settings to be standardized + +**2. Review Phase** (Democratic Decision) +- Contributors review the proposed changes +- Discussion happens in the PR +- Worlddriven's voting system determines merge timing + +**3. Merge Phase** (Automatic Sync) +- PR merges to main +- Sync workflow executes with APPLY mode +- Changes are applied to GitHub organization: + - Creates new repositories + - Updates existing repositories + - Deletes repositories not in REPOSITORIES.md + - Applies standard configurations + - Sets up branch protection +- Commit comment shows sync results +- Issue created if any failures occur + +## Standard Configurations + +All worlddriven repositories automatically receive these settings to support democratic governance: + +### Repository Settings +- **Merge strategy**: Squash only (1 PR = 1 commit for fair voting) +- **Auto-merge**: Disabled (worlddriven controls merging) +- **Branch cleanup**: Delete branches after merge +- **Update branch**: Disabled + +### Branch Protection Ruleset: "Worlddriven Democratic Governance" +Applied to default branch (usually `main`): +- **Pull request required**: All changes must go through PR workflow +- **No force push**: Prevents history rewriting +- **No branch deletion**: Protects main branch +- **Allowed merge method**: Squash only +- **No bypass actors**: True democracy applies to everyone + +### Repository Initialization +New repositories are created with: +- Public visibility +- Initial README.md file (created via auto_init) +- Issues, Projects, and Wiki enabled +- Standard settings pre-applied +- Branch protection ruleset active + +## Protected Repositories + +Three infrastructure repositories are protected from automatic deletion: + +- **documentation** - This repository (organization management) +- **core** - The worlddriven application server +- **webapp** - The worlddriven web interface + +These repositories can still be updated (descriptions, topics, settings) but won't be deleted if removed from REPOSITORIES.md. This prevents accidental deletion of critical infrastructure. + +## GitHub Actions Workflows + +### 1. Drift Detection (`.github/workflows/drift-detection.yml`) + +**Triggers**: PRs that modify REPOSITORIES.md, scripts, or workflows + +**Purpose**: Show what will happen before changes merge + +**Actions**: +- Parses REPOSITORIES.md +- Fetches current GitHub organization state +- Compares desired vs actual state +- Runs sync in dry-run mode (no changes made) +- Comments on PR with drift report and sync preview +- Updates existing comment instead of creating duplicates + +**Example Output**: +``` +# Drift Detection Report + +Missing (in REPOSITORIES.md but not GitHub): +- new-project + +Extra (in GitHub but not REPOSITORIES.md): +- old-experiment + +Description Drift: +- existing-repo: "Old description" → "Updated description" + +# Dry-Run Sync Preview + +Would create: +- new-project (Description: A new worlddriven project) + +Would delete: +- old-experiment (unprotected repository) +``` + +### 2. Repository Sync (`.github/workflows/sync-repositories.yml`) + +**Triggers**: Push to main branch + +**Purpose**: Apply infrastructure changes to GitHub + +**Permissions**: +- Runs only on worlddriven organization (not forks) +- Requires WORLDDRIVEN_GITHUB_TOKEN secret + +**Actions**: +- Executes sync-repositories.js with --apply flag +- Creates/updates/deletes repositories +- Applies standard configurations +- Posts commit comment with results +- Creates issue if failures occur +- Adds report to workflow summary + +**Example Output**: +``` +✅ APPLY Repository Sync Report + +Summary: 3 total actions +- Create: 1 +- Update descriptions: 1 +- Delete: 1 + +✅ Successfully Applied (3) +- Create new-project +- Update description for existing-repo +- Delete old-experiment +``` + +### 3. Test Suite (`.github/workflows/test.yml`) + +**Triggers**: All PRs + +**Purpose**: Validate automation scripts work correctly + +**Actions**: +- Runs unit tests for parse-repositories.js +- Validates REPOSITORIES.md syntax +- Ensures scripts can execute + +## Scripts Reference + +### `scripts/sync-repositories.js` + +Main synchronization engine that applies changes to GitHub. + +**Usage**: +```bash +# Dry-run (show what would happen) +WORLDDRIVEN_GITHUB_TOKEN=xxx node scripts/sync-repositories.js + +# Apply changes +WORLDDRIVEN_GITHUB_TOKEN=xxx node scripts/sync-repositories.js --apply +``` + +**Capabilities**: +- Create repositories with standard settings +- Update repository descriptions and topics +- Delete repositories (except protected ones) +- Apply/enforce standard repository settings +- Create branch protection rulesets +- Initialize empty repositories + +### `scripts/detect-drift.js` + +Compares desired state (REPOSITORIES.md) with actual state (GitHub). + +**Detects**: +- Missing repositories +- Extra repositories +- Description differences +- Topic differences + +### `scripts/parse-repositories.js` + +Parses REPOSITORIES.md markdown format. + +**Features**: +- Extracts repository definitions +- Validates required fields (name, description) +- Skips code blocks and examples +- Handles optional topics + +### `scripts/fetch-github-state.js` + +Fetches current GitHub organization repository state via API. + +**Returns**: +- Repository names +- Descriptions +- Topics +- Handles pagination + +## Security Model + +### Authentication + +The sync automation uses a GitHub Personal Access Token stored as `WORLDDRIVEN_GITHUB_TOKEN` in repository secrets. + +**Required permissions**: +- `repo` - Full control of repositories +- `admin:org` - Manage organization settings +- `delete_repo` - Delete repositories + +### Permissions + +- **Forks**: Workflows are restricted to worlddriven organization only +- **Tests**: Test workflow runs on all repos including forks (no secrets needed) +- **Secrets**: Organization secrets are not accessible to fork PRs + +### Safety Features + +- **Protected repositories**: Cannot be auto-deleted +- **Dry-run preview**: See changes before merge +- **Atomic operations**: Each action is independent +- **Failure isolation**: One failure doesn't stop other operations +- **Audit trail**: All changes visible in git history and workflow logs + +## Examples + +### Adding a New Repository + +1. Create a PR modifying REPOSITORIES.md: +```markdown +## my-new-project +- Description: An experimental worlddriven integration +- Topics: experiment, integration, worlddriven +``` + +2. Drift detection comments on your PR showing it will create the repository + +3. After PR merges, sync workflow: + - Creates `worlddriven/my-new-project` + - Sets description and topics + - Applies standard settings + - Creates branch protection ruleset + - Initializes with README.md + +### Updating Repository Metadata + +1. Edit description in REPOSITORIES.md: +```markdown +## my-new-project +- Description: Production-ready worlddriven integration (updated!) +- Topics: integration, worlddriven, production +``` + +2. Drift detection shows description and topic changes + +3. After merge, sync workflow updates GitHub metadata + +### Removing a Repository + +1. Remove repository section from REPOSITORIES.md + +2. Drift detection warns: + - If protected: "Would skip - protected repository" + - If unprotected: "Would delete repository-name" + +3. After merge: + - Protected repos: Skipped with warning in logs + - Unprotected repos: Deleted from GitHub + +**Important**: Repository deletion is permanent. Ensure you have backups. + +## Troubleshooting + +### Sync Failures + +If sync fails, an issue is automatically created with: +- Error details +- Which actions failed +- Commit SHA that triggered the failure + +Common failures: +- **403 errors**: Token permissions issue +- **409 errors**: Conflicts (e.g., repository already exists) +- **Rate limits**: Too many API calls (wait and retry) + +### Manual Intervention + +If automation fails and manual fixes are needed: + +1. Fix the issue in GitHub directly +2. Update REPOSITORIES.md to match actual state +3. Next sync will detect no drift + +### Testing Changes + +To test automation changes locally: + +```bash +# Install dependencies +npm install + +# Run tests +npm test + +# Dry-run sync (requires token) +export WORLDDRIVEN_GITHUB_TOKEN=your_token +node scripts/sync-repositories.js +``` + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for details on: +- How to propose organization changes +- Automation script development +- Testing guidelines +- Security considerations + +## Philosophy + +This automation embodies worlddriven's core principle: **those who contribute should govern**. By managing infrastructure through pull requests, we ensure: + +- **Transparency**: All decisions visible in git history +- **Democracy**: Anyone can propose changes +- **Meritocracy**: Contribution weight determines influence +- **Accountability**: Changes are attributed and reversible + +The automation removes gatekeepers while maintaining safety through standard configurations and protected repositories. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4dd32e5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,308 @@ +# Contributing to Worlddriven + +Welcome! We're glad you're interested in contributing to worlddriven. This project practices democratic governance—your contributions give you both voting power and responsibility for the project's direction. + +## Quick Start + +1. **Fork the repository** you want to contribute to +2. **Make your changes** in a feature branch +3. **Submit a pull request** to the main repository +4. **Participate in review** - your vote counts! + +## Repository Management + +The worlddriven organization itself is managed democratically. To propose infrastructure changes: + +### Adding a New Repository + +1. **Edit [REPOSITORIES.md](REPOSITORIES.md)** to add your repository: +```markdown +## my-new-repo +- Description: Brief description of what this repository does +- Topics: topic1, topic2, topic3 +``` + +2. **Create a pull request** with your changes + +3. **Review the drift detection comment** that automatically appears on your PR: + - Shows exactly what will be created + - Displays repository settings that will be applied + - Previews the sync plan + +4. **After democratic review and merge**: + - Automation creates the repository on GitHub + - Standard worlddriven settings are applied + - Branch protection ruleset is configured + - Initial README.md is created + +### Updating Repository Metadata + +To update a repository's description or topics: + +1. **Edit the repository's section** in [REPOSITORIES.md](REPOSITORIES.md) +2. **Submit a pull request** - drift detection will show the changes +3. **After merge**, automation updates GitHub metadata + +### Removing a Repository + +**Warning**: Repository deletion is permanent. Ensure you have backups. + +1. **Remove the repository section** from [REPOSITORIES.md](REPOSITORIES.md) +2. **Submit a pull request** - drift detection will warn about deletion +3. **Protected repositories** (documentation, core, webapp) will not be deleted +4. **After merge**, unprotected repositories are deleted from GitHub + +## Code Contributions + +### For Documentation Repository + +**Areas to contribute:** +- Improve documentation clarity +- Add examples and use cases +- Fix typos and formatting +- Enhance automation scripts +- Add tests for repository parsing + +**Development workflow:** +```bash +# Clone the repository +git clone https://github.com/worlddriven/documentation.git +cd documentation + +# Create a feature branch +git checkout -b feature/your-feature-name + +# Make your changes +# ... + +# Run tests +npm test + +# Commit and push +git add . +git commit -m "feat: add your feature description" +git push origin feature/your-feature-name +``` + +### For Automation Scripts + +Located in `scripts/` directory: +- `parse-repositories.js` - Parse REPOSITORIES.md format +- `detect-drift.js` - Compare desired vs actual state +- `sync-repositories.js` - Apply changes to GitHub +- `fetch-github-state.js` - Fetch current organization state + +**Testing locally:** +```bash +# Install dependencies +npm install + +# Run unit tests +npm test + +# Test drift detection (requires GitHub token) +export WORLDDRIVEN_GITHUB_TOKEN=your_token +node scripts/detect-drift.js + +# Test sync in dry-run mode (safe, makes no changes) +node scripts/sync-repositories.js +``` + +**Adding tests:** +- Unit tests go in `tests/` directory +- Test repository parsing edge cases +- Validate drift detection logic +- Ensure sync plan generation is correct + +## Pull Request Guidelines + +### Creating Good Pull Requests + +**Title**: Use conventional commit format: +- `feat:` - New feature +- `fix:` - Bug fix +- `docs:` - Documentation changes +- `test:` - Add or improve tests +- `refactor:` - Code refactoring +- `chore:` - Maintenance tasks + +**Description**: Include: +- What changes you made +- Why you made them +- How to test them +- Related issues (if any) + +**Example**: +```markdown +## Summary +Add support for repository archival in REPOSITORIES.md + +## Why +Users need ability to mark repositories as archived while keeping +them in the organization for historical reference. + +## Changes +- Add optional `archived: true` field to repository format +- Update parser to handle archived flag +- Add archive action to sync script + +## Testing +- Added unit tests for archived repository parsing +- Tested sync with archived repository in dry-run mode + +Closes #42 +``` + +### Reviewing Pull Requests + +Your review carries weight based on your contribution history: + +**How to review:** +1. **Understand the changes** - Read the code and PR description +2. **Test locally** if significant - Clone the branch and verify it works +3. **Provide constructive feedback** - Suggest improvements clearly +4. **Vote with your review**: + - ✅ **Approve** - Speeds up merge (if you have contribution history) + - 💬 **Comment** - Neutral feedback, doesn't affect timing + - ❌ **Request changes** - Blocks merge until addressed + +**Good review comments:** +- Specific: "Line 42: This could cause X if Y happens" +- Constructive: "Consider using Z instead for better performance" +- Educational: "This pattern might be clearer: [example]" + +**Less helpful:** +- Vague: "I don't like this" +- Non-actionable: "This seems wrong" +- Personal: Attacking the contributor rather than critiquing the code + +## Understanding Worlddriven Voting + +Pull requests automatically merge after a default time period (10 days), but the community can influence this: + +**How votes work:** +- Your voting power = your contribution weight to the project +- **Approvals** from contributors reduce merge time +- **Change requests** increase merge time or block entirely +- **Coefficient** shown in GitHub status indicates net community sentiment +- **Transparent calculation** - everyone sees exactly how decisions are made + +**What this means:** +- Your first contribution immediately gives you voting rights +- More contributions = more influence in project direction +- Veterans guide through influence, not absolute authority +- True democracy where those who build decide + +## Automation Workflow + +Understanding the automation helps you contribute effectively: + +### Drift Detection Workflow +``` +PR created/updated + ↓ +GitHub Actions triggered + ↓ +Parse REPOSITORIES.md (desired state) + ↓ +Fetch GitHub org (actual state) + ↓ +Detect differences + ↓ +Generate drift report + ↓ +Generate sync preview (dry-run) + ↓ +Post/update PR comment +``` + +### Sync Workflow +``` +PR merges to main + ↓ +GitHub Actions triggered + ↓ +Execute sync script (--apply mode) + ↓ +Create repositories + ↓ +Update descriptions/topics + ↓ +Apply standard settings + ↓ +Create branch protection + ↓ +Delete unprotected repos + ↓ +Post commit comment with results + ↓ +Create issue if failures +``` + +## Security & Permissions + +### Token Permissions + +The `WORLDDRIVEN_GITHUB_TOKEN` secret requires: +- `repo` - Full repository control +- `admin:org` - Organization management +- `delete_repo` - Repository deletion + +**Never**: +- Commit tokens to repository +- Share tokens publicly +- Use tokens with broader permissions than needed + +### Safe Contribution + +- **Forks**: Automation doesn't run on forks (no access to secrets) +- **Tests**: Test workflow runs on forks safely +- **Review**: All PRs reviewed before merge to protected main branch +- **Audit trail**: All changes visible in git history + +## Code Style + +### JavaScript +- Use ES modules (`import`/`export`) +- Clear variable names +- Add JSDoc comments for functions +- Follow existing code patterns +- Run tests before committing + +### Markdown +- Use clear headings +- Include code examples +- Link to related documentation +- Keep line length reasonable +- Use lists for better readability + +### Commit Messages +- Clear, concise, descriptive +- Use conventional commit format +- Reference issues when relevant +- Explain why, not just what + +## Getting Help + +- **Questions**: Open an issue with the `question` label +- **Bugs**: Open an issue with the `bug` label +- **Features**: Open an issue with the `enhancement` label +- **Discussion**: Use GitHub Discussions for broader topics + +## Philosophy + +Contributing to worlddriven means: + +**Gaining Power**: Your contributions grant voting rights and influence + +**Accepting Responsibility**: You become accountable for project direction + +**Building Together**: Collective ownership through democratic process + +**Practicing Democracy**: Infrastructure management mirrors code governance + +## Thank You + +Your contributions make worlddriven possible. By participating, you're not just submitting code—you're helping build a more democratic, sustainable model for open source governance. + +Welcome to the community! 🌍 diff --git a/EXAMPLES.md b/EXAMPLES.md index 9a87f06..8e6b159 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -4,237 +4,156 @@ This document examines actual governance failures in open source projects and de ## Maintainer Burnout and Project Abandonment -### Case Study: Redis Founder's Departure +### Redis Founder's Departure -**The Crisis**: In June 2020, Salvatore Sanfilippo, Redis founder and lead maintainer, announced his departure from the project he had led for over a decade. +**The Crisis**: In June 2020, Salvatore Sanfilippo announced his departure from Redis after over a decade: "I'm asked more and more to express myself less and to maintain the project more. This is not what I want to do." -**His Words**: "I'm asked more and more to express myself less and to maintain the project more. And this is indeed exactly what Redis needs right now. But this is not what I want to do." - -**The Problem**: -- Single point of failure in project leadership -- Maintainer burnout from overwhelming responsibilities -- Community dependency on one person's continued interest -- Risk of project stagnation or abandonment +**The Problem**: Single point of failure, maintainer burnout, community dependency on one person's interest, risk of stagnation. **How Worlddriven Would Help**: -- **Distributed maintenance burden** across all contributors proportional to their involvement -- **Democratic decision-making** removes pressure on individual maintainer to make all choices -- **Community ownership** means project continues regardless of any individual's involvement -- **Reduced emotional burden** as maintainer becomes facilitator, not sole decision-maker -- **Sustainable participation** model that doesn't depend on individual heroics +- Distributed maintenance burden across all contributors +- Democratic decision-making removes pressure on individual maintainer +- Community ownership ensures project continues regardless of any individual +- Sustainable participation that doesn't depend on individual heroics **The Outcome**: Redis survived due to corporate backing, but most projects lack this safety net. -### Case Study: The Ignored Patch Problem +### The Ignored Patch Problem **The Crisis**: Research reveals systematic failure where valuable contributions get ignored, leading to contributor abandonment. -**The Pattern**: -- Contributor submits well-crafted patch -- Maintainer doesn't respond (too busy, on vacation, burned out) -- Contributor pings once, twice, then gives up -- Valuable improvement is lost -- Contributor doesn't contribute again - -**Documented Examples**: -- Studies show "wastelands of good patches that were completely ignored" -- Contributors report submitting patches to multiple projects with no response -- First-time contributors frequently abandon participation after being ignored +**The Pattern**: Contributor submits well-crafted patch → Maintainer doesn't respond (too busy, burned out) → Contributor pings once, twice, gives up → Valuable improvement lost → Contributor doesn't return. **How Worlddriven Would Help**: -- **Automatic processing** ensures every contribution gets consideration -- **Time-based merging** means good patches don't languish indefinitely -- **Community review** distributes evaluation burden beyond single maintainer -- **Democratic blocking** allows community to prevent problematic merges -- **Transparent timeline** shows contributors exactly when their work will be considered - -**The Impact**: Dramatically increased contributor retention and participation. +- Automatic processing ensures every contribution gets consideration +- Time-based merging prevents good patches from languishing +- Community review distributes evaluation burden +- Transparent timeline shows contributors when their work will be considered ## Corporate Takeovers and License Changes -### Case Study: MongoDB's SSPL License Change +### MongoDB's SSPL License Change -**The Crisis**: In 2018, MongoDB changed from AGPL to the more restrictive Server Side Public License (SSPL) to prevent cloud vendors from offering MongoDB-as-a-service without contributing back. +**The Crisis**: In 2018, MongoDB changed from AGPL to the more restrictive SSPL to prevent cloud vendors from offering MongoDB-as-a-service without contributing back. -**The Problem**: -- **Unilateral decision** by corporate entity controlling the project -- **Community had no voice** in license change affecting their contributions -- **Uncertainty for users** about future license stability -- **Precedent set** for other corporate-controlled projects - -**Community Reaction**: -- Confusion about implications for existing users -- Concerns about future commercial restrictions -- Some users began evaluating alternatives -- Contributors questioned their future involvement +**The Problem**: Unilateral decision by corporate entity, community had no voice, uncertainty for users, precedent set for other corporate-controlled projects. **How Worlddriven Would Help**: -- **Community vote** required for major changes like license modifications -- **Contributor consensus** needed before implementation -- **Transparent discussion** of alternatives and implications -- **Democratic legitimacy** for decisions affecting all contributors -- **Protection from unilateral corporate decisions** - -**The Result**: License changes would require genuine community support, preventing corporate capture of community projects. +- Community vote required for major changes like licenses +- Contributor consensus needed before implementation +- Transparent discussion of alternatives and implications +- Protection from unilateral corporate decisions -### Case Study: Docker Governance Tensions +### Docker Governance Tensions -**The Crisis**: Docker Inc. maintained control over the Docker project while building commercial products around it, creating tensions between community and corporate interests. +**The Crisis**: Docker Inc. maintained control over Docker while building commercial products, creating tensions between community and corporate interests. -**The Problem**: -- **Unclear boundaries** between open source project and commercial product -- **Community contributions** potentially benefiting corporate interests disproportionately -- **Governance confusion** about who makes final decisions -- **Contributor concerns** about working for free to benefit corporate entity +**The Problem**: Unclear boundaries between open source and commercial product, community contributions potentially benefiting corporate interests disproportionately, governance confusion. **How Worlddriven Would Help**: -- **Clear democratic control** by contributors, not corporate entity -- **Transparent decision-making** about project direction -- **Community ownership** of project outcomes -- **Corporate participation** as contributor, not controller -- **Democratic oversight** of any commercial relationships +- Clear democratic control by contributors, not corporate entity +- Corporate participation as contributor, not controller +- Democratic oversight of commercial relationships ## Project Forks and Community Splits -### Case Study: GCC/EGCS Split and Reunification +### GCC/EGCS Split and Reunification -**The Crisis**: In the 1990s, disagreements between GCC's official maintainers and Cygnus Software (major contributor group) led to the creation of EGCS (Enhanced GNU Compiler Collection) as a competing fork. +**The Crisis**: In the 1990s, disagreements between GCC's official maintainers and Cygnus Software led to EGCS (Enhanced GNU Compiler Collection) as a competing fork. -**The Progression**: -1. **Technical disagreements** about development pace and feature inclusion -2. **Maintainer conflicts** over project direction -3. **Community split** with some supporting GCC, others EGCS -4. **Resource duplication** as both projects developed in parallel -5. **Market confusion** as distributors chose between compilers -6. **Resolution** when EGCS gained wider adoption and was renamed back to GCC +**The Progression**: Technical disagreements → Maintainer conflicts → Community split → Resource duplication → Market confusion → Resolution when EGCS gained wider adoption **How Worlddriven Would Have Helped**: -- **Democratic voting** would have resolved direction disputes without forking -- **Contribution-weighted influence** would have given Cygnus voice proportional to their work -- **Transparent process** would have prevented behind-the-scenes conflicts -- **Community consensus** would have emerged naturally through voting -- **Resource focus** would have prevented duplicated effort +- Democratic voting would have resolved direction disputes without forking +- Contribution-weighted influence would have given Cygnus voice proportional to their work +- Transparent process would have prevented behind-the-scenes conflicts +- Community consensus would have emerged naturally through voting **The Success**: The eventual reunification proved democratic choice works—EGCS won through community adoption. Worlddriven would have achieved this result without the wasteful fork period. -### Case Study: GNU Emacs/XEmacs Division +### GNU Emacs/XEmacs Division -**The Crisis**: Conflicts between Richard Stallman's Free Software Foundation and Lucid, Inc. over GNU Emacs direction led to the XEmacs fork that persisted for decades. +**The Crisis**: Conflicts between Richard Stallman's FSF and Lucid, Inc. over GNU Emacs direction led to the XEmacs fork that persisted for decades. -**The Problem**: -- **Philosophical disagreements** about project direction -- **Technical disputes** about feature inclusion -- **Personal conflicts** between key developers -- **Community fragmentation** lasting over 20 years -- **Duplicated effort** on essentially similar projects +**The Waste**: Two development teams working on similar goals, community split, user confusion, features developed separately instead of collaboratively. -**The Waste**: -- Two development teams working on similar goals -- Community split between competing implementations -- User confusion about which version to choose -- Features developed separately instead of collaboratively - -**How Worlddriven Would Have Helped**: -- **Democratic resolution** of technical disputes through contributor voting -- **Conflict mediation** through transparent, fair process -- **Community decision-making** rather than individual authority -- **Focus on code quality** rather than politics -- **Unified development** based on collective contributor judgment +**How Worlddriven Would Have Helped**: Democratic resolution of technical disputes through contributor voting, conflict mediation through transparent fair process, unified development based on collective judgment. ## Small Contributor Marginalization -### Case Study: Systematic Exclusion Patterns - -**The Problem**: Research documents patterns where small contributors face barriers to meaningful participation: +### Systematic Exclusion Patterns -**Barriers Identified**: +**The Problem**: Research documents patterns where small contributors face barriers: - Pull requests ignored for weeks or months -- No feedback provided on rejected contributions -- High-friction review processes for minor improvements -- Informal "insider" knowledge required for participation +- No feedback on rejected contributions +- High-friction review for minor improvements +- Informal "insider" knowledge required - Maintainer preferences override contributor efforts -**Real Examples**: -- Documentation improvements rejected for style reasons not documented anywhere -- Bug fixes ignored because they don't align with unstated roadmap priorities -- New contributor suggestions dismissed without explanation -- Feature requests closed without discussion +**Real Examples**: Documentation improvements rejected for undocumented style reasons, bug fixes ignored, new contributor suggestions dismissed without explanation. **How Worlddriven Changes This**: -- **Every contribution matters** because contributors become voters -- **Transparent evaluation** through public review process -- **Democratic consideration** of all improvements -- **Time-bound decisions** prevent indefinite delays -- **Community ownership** of quality standards +- Every contribution matters because contributors become voters +- Transparent evaluation through public review +- Time-bound decisions prevent indefinite delays +- Community ownership of quality standards **The Impact**: Small contributors become stakeholders rather than supplicants. ## Successful Democratic Resolutions -### Case Study: Linux Kernel's Distributed Development - -**What Works**: The Linux kernel successfully manages thousands of contributors through hierarchical but democratic processes: - -- **Maintainer hierarchy** with clear responsibilities -- **Contribution-based authority** where expertise determines influence -- **Transparent processes** for patch submission and review -- **Democratic consensus** for major decisions -- **Distributed ownership** preventing single points of failure +### Linux Kernel's Distributed Development -**Worlddriven Enhancement**: Worlddriven would formalize and automate these successful democratic principles while removing dependencies on individual maintainer availability. +**What Works**: The Linux kernel successfully manages thousands of contributors through hierarchical but democratic processes—maintainer hierarchy, contribution-based authority, transparent processes, democratic consensus for major decisions, distributed ownership. -### Case Study: Apache Software Foundation Model +**Worlddriven Enhancement**: Formalizes and automates these successful democratic principles while removing dependencies on individual maintainer availability. -**What Works**: Apache projects use democratic governance: +### Apache Software Foundation Model -- **Merit-based advancement** from contributor to committer to PMC member -- **Voting requirements** for major decisions -- **Transparent processes** documented in project bylaws -- **Community ownership** through foundation structure -- **Conflict resolution** through established procedures +**What Works**: Merit-based advancement (contributor → committer → PMC), voting requirements for major decisions, transparent processes, community ownership through foundation structure. -**Worlddriven Enhancement**: Worlddriven would automate merit recognition and voting, making participation more fluid and responsive. +**Worlddriven Enhancement**: Automates merit recognition and voting, making participation more fluid and responsive. ## The Pattern: Democracy Works ### Common Success Factors -1. **Contribution determines influence** rather than arbitrary authority -2. **Transparent processes** prevent hidden agendas -3. **Community ownership** creates investment in outcomes -4. **Conflict resolution** through fair, open procedures -5. **Distributed responsibility** prevents single points of failure +1. Contribution determines influence rather than arbitrary authority +2. Transparent processes prevent hidden agendas +3. Community ownership creates investment in outcomes +4. Conflict resolution through fair, open procedures +5. Distributed responsibility prevents single points of failure ### Common Failure Factors -1. **Concentrated authority** in individuals or corporations -2. **Opaque decision-making** processes -3. **Exclusion of contributor voices** from important decisions -4. **Arbitrary or inconsistent** standards and processes -5. **Single points of failure** in leadership or infrastructure +1. Concentrated authority in individuals or corporations +2. Opaque decision-making processes +3. Exclusion of contributor voices from important decisions +4. Arbitrary or inconsistent standards and processes +5. Single points of failure in leadership or infrastructure ## Lessons for Future Projects ### For Project Creators -- **Plan for your own departure** from the beginning -- **Build democratic processes** rather than depending on benevolent dictatorship -- **Create transparent systems** that work without your constant involvement -- **Empower contributors** to become stakeholders, not just suppliers +- Plan for your own departure from the beginning +- Build democratic processes rather than depending on benevolent dictatorship +- Create transparent systems that work without your constant involvement +- Empower contributors to become stakeholders ### For Contributors -- **Choose projects with democratic governance** for sustainable participation -- **Understand your responsibility** when you gain influence -- **Participate in project governance** as well as code contribution -- **Support transparent, accountable decision-making** +- Choose projects with democratic governance for sustainable participation +- Understand your responsibility when you gain influence +- Participate in project governance as well as code contribution +- Support transparent, accountable decision-making ### For the Ecosystem -- **Governance is a feature** as important as technical capabilities -- **Democratic projects are more sustainable** than autocratic ones -- **Community ownership** creates better long-term outcomes -- **Transparency prevents most conflicts** before they become crises +- Governance is a feature as important as technical capabilities +- Democratic projects are more sustainable than autocratic ones +- Community ownership creates better long-term outcomes +- Transparency prevents most conflicts before they become crises ## Conclusion: Learning from History -Every governance crisis in open source history demonstrates the same fundamental problem: concentration of power without accountability leads to community fragmentation, contributor burnout, and project instability. +Every governance crisis demonstrates the same fundamental problem: concentration of power without accountability leads to community fragmentation, contributor burnout, and project instability. -Worlddriven solves this by distributing both power and responsibility among those who actually build the software. It's not a theoretical improvement—it's a practical solution to documented, recurring problems in open source governance. +Worlddriven solves this by distributing both power and responsibility among those who actually build the software. It's not a theoretical improvement—it's a practical solution to documented, recurring problems. -**The choice is simple**: continue repeating the same governance failures, or adopt democratic principles that have already proven successful in the most important open source projects. \ No newline at end of file +**The choice is simple**: continue repeating the same governance failures, or adopt democratic principles that have already proven successful in the most important open source projects. diff --git a/PHILOSOPHY.md b/PHILOSOPHY.md index 94b5d7c..0182cd2 100644 --- a/PHILOSOPHY.md +++ b/PHILOSOPHY.md @@ -6,7 +6,7 @@ Worlddriven represents a fundamental shift in how we think about software develo ### 1. Those Who Build Should Govern -The fundamental principle of worlddriven is simple: the people who do the work should make the decisions. This isn't just practical—it's morally correct. +The fundamental principle of worlddriven is simple: the people who do the work should make the decisions. **Traditional Model**: Maintainers control projects while contributors supply labor **Democratic Model**: Contributors collectively control the projects they build @@ -34,7 +34,6 @@ Democracy requires informed participation. Worlddriven makes all governance proc - All votes and reviews are public - Decision algorithms are open source - Influence calculations are verifiable -- Process changes require community approval Without transparency, democracy becomes theater. With it, democracy becomes accountable. @@ -54,178 +53,99 @@ This creates investment mentality rather than consumer mentality. ### Direct Democracy for Code -Traditional representative democracy makes sense for large-scale governance where direct participation is impractical. Software projects can implement direct democracy because: - -**Scale is Manageable**: Most projects have dozens to hundreds of active contributors, not millions of citizens - -**Issue Specificity**: Votes focus on specific technical changes rather than broad policy directions - -**Expertise Relevance**: Contributors have direct technical knowledge of what they're voting on - -**Continuous Participation**: Contributors remain engaged with ongoing project evolution +Software projects can implement direct democracy because scale is manageable (dozens to hundreds of active contributors), votes focus on specific technical changes, contributors have direct expertise, and participation is continuous. ### Weighted Voting Systems -Pure one-person-one-vote democracy doesn't account for different levels of investment and expertise. Worlddriven uses contribution-weighted voting because: - -**Investment Alignment**: Those with more at stake get more influence over outcomes - -**Expertise Recognition**: Sustained contribution demonstrates competence and commitment +Pure one-person-one-vote doesn't account for different levels of investment and expertise. Worlddriven uses contribution-weighted voting because: -**Sybil Attack Prevention**: Voting weight requires actual work, not just account creation - -**Natural Meritocracy**: Influence flows to those who prove value through contribution +- **Investment Alignment**: Those with more at stake get more influence +- **Expertise Recognition**: Sustained contribution demonstrates competence +- **Sybil Attack Prevention**: Voting weight requires actual work +- **Natural Meritocracy**: Influence flows to those who prove value ### Temporal Governance -Unlike traditional elections with fixed terms, worlddriven implements continuous governance where: - -**Decisions Happen Continuously**: Every pull request is a small democratic decision - -**Influence Updates Dynamically**: Recent contributions affect current voting weight - -**Participation is Voluntary**: Contributors vote when they care about specific changes - -**Authority Flows Naturally**: Leadership emerges through sustained quality contribution +Unlike traditional elections, worlddriven implements continuous governance where decisions happen continuously, influence updates dynamically, participation is voluntary, and authority flows naturally through sustained quality contribution. ## Philosophical Foundations ### Social Contract Theory -Worlddriven implements a social contract where: - -**Contributors Agree**: To submit their work to democratic evaluation - -**Community Commits**: To fair, transparent review processes - -**Everyone Benefits**: From collective wisdom and shared responsibility - -**Mutual Accountability**: Creates stability and trust +Worlddriven implements a social contract where contributors agree to submit their work to democratic evaluation, the community commits to fair review processes, everyone benefits from collective wisdom, and mutual accountability creates stability. This voluntary association creates legitimacy that top-down authority lacks. ### Libertarian Principles -Worlddriven respects individual autonomy while enabling collective action: - -**Voluntary Participation**: No one is forced to contribute or vote - -**Exit Rights**: Contributors can fork if they disagree with community direction - -**Minimal Coercion**: Decisions emerge from voluntary association, not imposed authority - -**Self-Organization**: Communities organize themselves through contribution patterns +Worlddriven respects individual autonomy while enabling collective action through voluntary participation, exit rights (forking), minimal coercion, and self-organization based on contribution patterns. ### Commons Governance -Drawing from Elinor Ostrom's work on commons management, worlddriven implements proven principles for sustainable collective resource management: - -**Clearly Defined Boundaries**: Who can vote (contributors) and what they control (project direction) - -**Congruence**: Those affected by decisions have voice proportional to their involvement - -**Collective Choice**: Rules can be modified by those affected by them +Drawing from Elinor Ostrom's work on commons management: -**Monitoring**: Transparent processes allow community oversight - -**Graduated Sanctions**: Poor contributions get downvoted, but contributors aren't expelled - -**Conflict Resolution**: Democratic voting provides fair mechanism for dispute resolution +- **Clearly Defined Boundaries**: Who can vote (contributors) and what they control +- **Congruence**: Those affected by decisions have voice proportional to involvement +- **Collective Choice**: Rules can be modified by those affected +- **Monitoring**: Transparent processes allow community oversight +- **Conflict Resolution**: Democratic voting provides fair dispute mechanism ### Pragmatic Idealism -Worlddriven balances idealistic vision with practical implementation: - -**Idealistic Vision**: Truly democratic software development that empowers all contributors - -**Practical Implementation**: Working system deployed today that solves real problems - -**Gradual Evolution**: Three-phase roadmap from current PR voting to future self-governing systems - -**Proven Principles**: Applies democratic theory that works in other contexts to software development +Worlddriven balances idealistic vision (truly democratic software development) with practical implementation (working system deployed today), gradual evolution (three-phase roadmap), and proven principles from democratic theory. ## Addressing Common Criticisms ### "Developers Aren't Politicians" -**Criticism**: Software developers aren't trained in governance and should focus on code +**Criticism**: Developers aren't trained in governance and should focus on code. -**Response**: Developers already make governance decisions (code review, architecture choices, community standards). Worlddriven makes these decisions transparent and accountable rather than arbitrary and opaque. - -**Evidence**: The most successful open source projects (Linux, Apache projects) already use democratic governance principles. Worlddriven formalizes what works. +**Response**: Developers already make governance decisions (code review, architecture, community standards). Worlddriven makes these decisions transparent and accountable rather than arbitrary. The most successful projects (Linux, Apache) already use democratic governance—worlddriven formalizes what works. ### "Majority Rule Oppresses Minorities" -**Criticism**: Democratic voting allows majorities to override minority viewpoints - -**Response**: Contribution-weighted voting means technical minorities with expertise can outweigh uninformed majorities. Plus, fork rights provide ultimate minority protection. +**Criticism**: Democratic voting allows majorities to override minority viewpoints. -**Safeguards**: Historical contributors maintain influence, new ideas can gain support through demonstration, and technical merit affects contribution weight. +**Response**: Contribution-weighted voting means technical minorities with expertise can outweigh uninformed majorities. Fork rights provide ultimate minority protection. Historical contributors maintain influence, and technical merit affects contribution weight. ### "This Will Slow Down Development" -**Criticism**: Democratic processes are slower than benevolent dictatorship - -**Response**: Worlddriven actually accelerates development by removing maintainer bottlenecks. Automatic time-based merging ensures progress continues even when maintainers are unavailable. +**Criticism**: Democratic processes are slower than benevolent dictatorship. -**Evidence**: Projects die from maintainer burnout more often than from too much democracy. +**Response**: Worlddriven accelerates development by removing maintainer bottlenecks. Automatic time-based merging ensures progress continues even when maintainers are unavailable. Projects die from maintainer burnout more often than from too much democracy. ### "Code Quality Will Suffer" -**Criticism**: Democratic voting will allow poor code to be merged +**Criticism**: Democratic voting will allow poor code to be merged. -**Response**: Contributors who control the project have direct incentive to maintain quality. Poor code affects something they own and must maintain. - -**Safeguards**: Experienced contributors have more voting weight, change requests can block merges, and transparent review creates accountability. +**Response**: Contributors who control the project have direct incentive to maintain quality—poor code affects something they own. Experienced contributors have more voting weight, change requests can block merges, and transparent review creates accountability. ## Philosophical Implications ### Democratizing Digital Infrastructure -Software runs the world. Democratic governance of software development means democratic control of digital infrastructure. This has profound implications: - -**Political**: Software becomes accountable to users rather than corporate interests +Software runs the world. Democratic governance of software development means democratic control of digital infrastructure: -**Economic**: Value creation gets shared among those who build rather than concentrated among those who own +- **Political**: Software becomes accountable to users rather than corporate interests +- **Economic**: Value creation shared among those who build +- **Social**: Technical communities become models for democratic organization +- **Cultural**: Collaboration replaces competition as organizing principle -**Social**: Technical communities become models for democratic organization +### Beyond Software -**Cultural**: Collaboration replaces competition as the organizing principle - -### Beyond Software: Democratic Organization Models - -Worlddriven principles apply beyond software: - -**Research Collaboration**: Academic papers could use contribution-weighted review - -**Content Creation**: Wikis and documentation could implement democratic editing - -**Community Management**: Online communities could use participation-based governance - -**Resource Allocation**: Shared resources could be managed democratically by users +Worlddriven principles apply to research collaboration, content creation, community management, and shared resource allocation—any domain where contribution can be measured and governance matters. ### Evolutionary Pressure -Worlddriven creates evolutionary pressure toward better governance: - -**Projects with Democratic Governance**: Attract more contributors, have better retention, and produce higher quality outcomes - -**Projects with Autocratic Governance**: Lose contributors to democratic alternatives, suffer from maintainer burnout, and stagnate over time - -**Market Forces**: Users and contributors naturally gravitate toward more responsive, accountable projects - -This creates positive feedback loops that spread democratic governance throughout the ecosystem. +Worlddriven creates evolutionary pressure toward better governance. Projects with democratic governance attract more contributors, have better retention, and produce higher quality outcomes. Users and contributors naturally gravitate toward more responsive, accountable projects, creating positive feedback loops. ## The Vision: Software as Democratic Practice -### Phase 1: Proof of Concept -Current worlddriven deployment proves democratic software governance works at scale. Contributors participate enthusiastically when they have real influence over outcomes. +**Phase 1: Proof of Concept** - Current deployment proves democratic software governance works at scale. -### Phase 2: Infrastructure Democracy -Extending democratic governance to infrastructure management creates transparency and accountability in how software systems operate, not just how they're developed. +**Phase 2: Infrastructure Democracy** - Democratic governance extends to infrastructure management, creating transparency in how systems operate. -### Phase 3: Self-Governing Systems -The ultimate vision: software systems that govern themselves through democratic contributor consensus, creating truly autonomous, accountable digital infrastructure. +**Phase 3: Self-Governing Systems** - Software systems govern themselves through democratic contributor consensus. ## Conclusion: Democracy as Default @@ -235,4 +155,4 @@ Worlddriven makes the democratic choice explicit and automatic. It turns the exc **Democracy isn't just a political ideal—it's a practical tool for building better software with better communities.** -The future of software development is democratic. Worlddriven makes that future available today. \ No newline at end of file +The future of software development is democratic. Worlddriven makes that future available today. diff --git a/README.md b/README.md index 89bda0b..f2e8aa2 100644 --- a/README.md +++ b/README.md @@ -7,30 +7,17 @@ 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. ### Maintainer Bottlenecks -- **58% of maintainers** have abandoned projects or considered doing so due to burnout -- **22% have already left**, with 36% actively considering it -- Over **three-quarters receive no financial compensation** for their work -- Projects die when single maintainers become overwhelmed or move on +- **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," where contributors: -- Submit valuable improvements that receive no response -- Ping maintainers multiple times before giving up -- Abandon participation due to systematic neglect -- Face barriers that prevent democratic participation in projects they care about +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 -- **MongoDB, Redis, and others** changed licenses to prevent corporate exploitation -- **Docker governance tensions** between project and company interests -- **Foundation vs. company-led models** create ongoing conflicts over control -- License changes effectively privatize community work +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 that split communities and waste resources: -- **GCC/EGCS split** due to maintainer disagreements (eventually resolved) -- **GNU Emacs/XEmacs** division over project direction -- **BSD fragmentation** into FreeBSD, NetBSD, and OpenBSD -- Personal conflicts creating unnecessary project duplication +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? @@ -52,19 +39,35 @@ Pull requests automatically merge after a configurable time period (default: 10 ### 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. +## 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. + +### 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 + +**Learn more**: [AUTOMATION.md](AUTOMATION.md) - Complete guide to our infrastructure automation + +**Current repositories**: [View on GitHub](https://github.com/orgs/worlddriven/repositories) + ## Real-World Examples Where Worlddriven Would Help -### Redis Creator's Departure -Salvatore Sanfilippo, Redis founder, stepped down in 2020 saying: "I'm asked more and more to express myself less and to maintain the project more. This is not what I want to do." Worlddriven would have distributed this maintenance burden across the contributor community. +**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. -### The Ignored Patch Problem -Many projects show systematic failures where good contributions are ignored, leading to contributor abandonment. Worlddriven's automatic merge system ensures every contribution gets proper consideration and resolution. +**Ignored Patches**: Many projects systematically ignore good contributions, leading to contributor abandonment. Worlddriven's automatic merge system ensures every contribution gets proper consideration. -### MongoDB License Controversy -When MongoDB changed to SSPL to prevent cloud vendor exploitation, it created uncertainty for users. Worlddriven's democratic process would have allowed the community to collectively decide on license changes based on contributor consensus. +**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. -### GCC/EGCS Success Story -The GCC/EGCS fork eventually reunited when it became clear EGCS had better community support. Worlddriven's voting system would have revealed this preference earlier, preventing the fork entirely and focusing energy on collaborative improvement. +**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. ## The Responsibility Model @@ -82,17 +85,13 @@ Veteran contributors become democratic leaders who guide through influence and e ## How Worlddriven Changes the Game -### From Spectator to Stakeholder -Traditional open source asks you to submit patches and hope they're accepted. Worlddriven makes you an immediate stakeholder with both power and responsibility for project success. +**From Spectator to Stakeholder**: Your first contribution makes you an immediate stakeholder with both power and responsibility for project success. -### Prevents Corporate Capture -When the community collectively owns decision-making, no single entity can unilaterally change licenses, direction, or governance. Contributors who built the project retain democratic control. +**Prevents Corporate Capture**: Collective decision-making means no single entity can unilaterally change licenses, direction, or governance. -### Reduces Fork Necessity -Disagreements get resolved through democratic process rather than community fragmentation. Energy focuses on collaborative improvement instead of competing implementations. +**Reduces Fork Necessity**: Disagreements resolve through democratic process rather than community fragmentation, focusing energy on collaborative improvement. -### Sustainable Participation -By distributing both power and responsibility, worlddriven creates sustainable participation models that don't depend on individual heroics or burnout-prone maintainership. +**Sustainable Participation**: Distributing power and responsibility creates sustainable models that don't depend on individual heroics or burnout-prone maintainership. ## The Vision: Three Phases @@ -116,17 +115,13 @@ By distributing both power and responsibility, worlddriven creates sustainable p ## Why Now? -### The Crisis is Real -Open source faces a sustainability crisis with widespread maintainer burnout, corporate capture of community projects, and a democratic deficit in software that runs the world's infrastructure. +**The Crisis is Real**: Open source faces widespread maintainer burnout, corporate capture, and a democratic deficit in software running the world's infrastructure. -### The Infrastructure Exists -GitHub and GitLab provide the technical foundation. The challenge isn't technical—it's governance. Worlddriven solves the governance problem. +**The Infrastructure Exists**: GitHub and GitLab provide the technical foundation. The challenge is governance—which worlddriven solves. -### Community Readiness -Growing awareness of open source governance problems creates demand for solutions. Contributors want meaningful participation, not just code submission privileges. +**Community Readiness**: Growing awareness of governance problems creates demand for solutions. Contributors want meaningful participation, not just code submission privileges. -### Proven Principles -Democratic governance works in other contexts. Worlddriven adapts these principles for software development, creating accountability through transparency and shared ownership. +**Proven Principles**: Democratic governance works in other contexts. Worlddriven adapts these principles for software, creating accountability through transparency and shared ownership. ## Get Started @@ -140,6 +135,6 @@ Visit [www.worlddriven.org](https://www.worlddriven.org) to enable worlddriven f - [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 -- [Vision](VISION.md) - The three-phase roadmap to self-governing software +- [Automation](AUTOMATION.md) - How this organization manages itself democratically *Technical implementation details are available in the [core repository](../core/README.md).* \ No newline at end of file diff --git a/REPOSITORIES.md b/REPOSITORIES.md index c378639..30b82cc 100644 --- a/REPOSITORIES.md +++ b/REPOSITORIES.md @@ -1,6 +1,23 @@ # Worlddriven Organization Repositories -This file serves as the source of truth for all repositories in the worlddriven GitHub organization. Changes to this file via pull requests will automatically sync the organization structure through democratic voting. +This file is the **source of truth** for all repositories in the worlddriven GitHub organization. Changes to this file democratically control our infrastructure through automated synchronization. + +## How It Works + +**When you create a PR modifying this file:** +- GitHub Actions automatically runs drift detection +- A comment appears showing exactly what will change (repositories to create, update, or delete) +- You can review the impact before the PR merges + +**When your PR merges to main:** +- Sync automation applies changes to GitHub organization +- Repositories are created, updated, or deleted to match this file +- A commit comment shows the sync results +- If failures occur, an issue is automatically created + +**Protected repositories** (documentation, core, webapp) cannot be auto-deleted but can be updated. + +**Learn more**: [AUTOMATION.md](AUTOMATION.md) - Complete automation documentation ## Format diff --git a/RESPONSIBILITY.md b/RESPONSIBILITY.md index 3b7f884..a19bdf8 100644 --- a/RESPONSIBILITY.md +++ b/RESPONSIBILITY.md @@ -6,7 +6,7 @@ Worlddriven fundamentally changes the relationship between contributors and proj Traditional open source treats contributors as external suppliers submitting patches to maintainer gatekeepers. Worlddriven transforms contributors into owners who collectively control project destiny. -### The Transformation +**The Transformation**: - **Before**: Submit code → Hope for acceptance → No ongoing influence - **After**: Submit code → Gain voting power → Share responsibility for outcomes @@ -16,162 +16,106 @@ This shift creates deep investment in project success because contributors contr ### Entry Level: First Commit, First Vote, First Responsibility -Making your first contribution immediately grants: -- **Voting rights** on all future pull requests -- **Influence weight** proportional to your single contribution -- **Stewardship responsibility** for the project's future direction - -You're no longer an external contributor hoping for acceptance—you're a project owner with decision-making power and accountability for outcomes. +Making your first contribution immediately grants voting rights, influence weight proportional to your contribution, and stewardship responsibility for the project's future. You're no longer an external contributor—you're a project owner with decision-making power and accountability. ### Building Influence Through Investment -Each additional contribution increases your: -- **Vote weight** in proportion to cumulative contributions -- **Responsibility** for project direction and quality -- **Stake** in long-term project success - -This creates natural incentives for thoughtful, high-quality contributions because poor decisions directly impact something you help control. +Each additional contribution increases your vote weight, responsibility for project direction, and stake in long-term success. This creates natural incentives for thoughtful, high-quality contributions because poor decisions directly impact something you help control. ### Veteran Leadership Through Democratic Means -Long-term contributors gain substantial influence but cannot exercise dictatorial control: -- **Their expertise carries weight** through accumulated vote power -- **They guide through example** rather than mandate -- **Community can override** through collective action -- **Responsibility scales** with their increased influence +Long-term contributors gain substantial influence but cannot exercise dictatorial control. Their expertise carries weight through accumulated vote power, they guide through example rather than mandate, the community can override through collective action, and responsibility scales with their influence. ## The Accountability Framework ### Individual Accountability Every contributor is accountable for: -- **Quality of their own contributions** (poor code affects their reputation) -- **Voting decisions** (they help shape what gets merged) -- **Project health** (they partially control its future) -- **Community standards** (their behavior affects project culture) +- Quality of their own contributions +- Voting decisions +- Project health +- Community standards ### Collective Accountability -The contributor community is collectively responsible for: -- **Project direction** through democratic voting -- **Code quality** through review and approval processes -- **Community standards** through peer accountability -- **Long-term sustainability** through shared stewardship +The contributor community is collectively responsible for project direction, code quality, community standards, and long-term sustainability through shared stewardship. ### Transparent Responsibility -All responsibility is visible and auditable: -- **Vote weights** are public and based on transparent contribution history -- **Voting decisions** are recorded and attributed -- **Contribution patterns** show who's building the project -- **Influence calculations** are open for community verification +All responsibility is visible: vote weights are public and based on transparent contribution history, voting decisions are recorded and attributed, contribution patterns show who's building the project, and influence calculations are open for verification. ## Responsibility in Action ### Decision Making -When reviewing pull requests, contributors must consider: -- **Technical merit** of the proposed changes -- **Project direction** alignment -- **Long-term maintainability** implications -- **Community impact** of their voting decision -Their vote carries weight proportional to their investment, creating natural incentives for thoughtful decisions. +When reviewing pull requests, contributors must consider technical merit, project direction alignment, long-term maintainability implications, and community impact. Their vote carries weight proportional to their investment, creating natural incentives for thoughtful decisions. ### Quality Control -Contributors become invested in maintaining high standards because: -- **Poor quality** affects a project they help control -- **Technical debt** becomes their problem to solve -- **Security issues** impact their reputation and the project's future -- **Community conflicts** disrupt something they've helped build + +Contributors become invested in maintaining high standards because poor quality affects a project they help control, technical debt becomes their problem, security issues impact their reputation, and community conflicts disrupt something they've helped build. ### Conflict Resolution -Disputes get resolved democratically rather than by maintainer decree: -- **Controversial changes** require broader consensus -- **Community disagreements** get decided by those who contribute -- **Project direction changes** need support from active contributors -- **Personal conflicts** can't override democratic process + +Disputes get resolved democratically: controversial changes require broader consensus, community disagreements get decided by those who contribute, and personal conflicts can't override democratic process. ## The Investment Psychology ### From Consumer to Owner Mindset -Traditional open source creates consumer mentality: -- "Someone else maintains this" -- "I'll request features and wait" -- "If I don't like it, I'll fork" +**Traditional** (consumer mentality): "Someone else maintains this," "I'll request features and wait," "If I don't like it, I'll fork" -Worlddriven creates owner mentality: -- "I help control this project's future" -- "My votes determine what gets built" -- "I'm responsible for making this work" +**Worlddriven** (owner mentality): "I help control this project's future," "My votes determine what gets built," "I'm responsible for making this work" ### Skin in the Game -When you have voting power, you have skin in the game: -- **Bad decisions** affect something you partially control -- **Good contributions** improve your own project -- **Quality issues** become your responsibility to fix -- **Project success** directly benefits your work +When you have voting power, you have skin in the game: bad decisions affect something you partially control, good contributions improve your own project, quality issues become your responsibility, and project success directly benefits your work. ## Preventing Abuse ### Democratic Safeguards Multiple mechanisms prevent individual abuse: -- **Contribution history** determines vote weight (can't buy influence) -- **Transparent calculations** prevent hidden manipulation -- **Collective decisions** prevent individual control -- **Historical accountability** creates reputation incentives +- Contribution history determines vote weight (can't buy influence) +- Transparent calculations prevent hidden manipulation +- Collective decisions prevent individual control +- Historical accountability creates reputation incentives ### Community Self-Policing -Responsible contributors naturally police bad actors: -- **Poor contributors** get downvoted by quality contributors -- **Malicious actors** face community resistance -- **Spam submissions** get blocked by invested reviewers -- **Disruptive behavior** threatens something contributors control +Responsible contributors naturally police bad actors: poor contributors get downvoted by quality contributors, malicious actors face community resistance, spam submissions get blocked by invested reviewers, and disruptive behavior threatens something contributors control. ### Gradual Influence Building -New contributors must earn influence over time: -- **First contribution** grants minimal voting power -- **Sustained quality** work increases influence -- **Community trust** develops through demonstrated responsibility -- **Leadership roles** emerge naturally through merit +New contributors must earn influence over time through sustained quality work and demonstrated responsibility. Leadership roles emerge naturally through merit. ## Benefits of the Responsibility Model -### Sustainable Participation -Contributors stay engaged because they control outcomes, not just hope for acceptance. +**Sustainable Participation**: Contributors stay engaged because they control outcomes. -### Higher Quality Standards -People who control the project maintain higher standards because poor quality affects them directly. +**Higher Quality Standards**: People maintain higher standards when they control the project. -### Reduced Maintainer Burden -Responsibility distributes across all contributors rather than concentrating on single maintainers. +**Reduced Maintainer Burden**: Responsibility distributes across all contributors. -### Long-term Thinking -Owners think long-term because they'll live with the consequences of decisions. +**Long-term Thinking**: Owners think long-term because they'll live with the consequences. -### Community Investment -Contributors become invested in project success, community health, and collaborative relationships. +**Community Investment**: Contributors become invested in project success and community health. ## Getting Started with Responsibility ### For New Contributors -1. **Make your first contribution** to gain voting rights -2. **Participate in reviews** to exercise your democratic voice -3. **Think like an owner** when evaluating changes -4. **Build your influence** through sustained quality contributions +1. Make your first contribution to gain voting rights +2. Participate in reviews to exercise your democratic voice +3. Think like an owner when evaluating changes +4. Build your influence through sustained quality contributions ### For Existing Projects -1. **Enable worlddriven** to distribute decision-making power -2. **Educate contributors** about their new responsibilities -3. **Trust the democratic process** even when individual decisions differ from your preferences -4. **Focus on influence through contribution** rather than maintainer authority +1. Enable worlddriven to distribute decision-making power +2. Educate contributors about their new responsibilities +3. Trust the democratic process +4. Focus on influence through contribution rather than maintainer authority ## The Result: True Collaborative Ownership Worlddriven creates software projects that are genuinely owned and controlled by the people who build them. This aligns incentives, distributes responsibility, and creates sustainable communities where contributors are stakeholders, not supplicants. -**Ready to take responsibility for the software you help create?** \ No newline at end of file +**Ready to take responsibility for the software you help create?** diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..fff9930 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,359 @@ +# Automation Scripts Reference + +This directory contains the automation scripts that manage the worlddriven GitHub organization based on REPOSITORIES.md as the source of truth. + +## Overview + +The automation system consists of four main scripts that work together to synchronize the GitHub organization with the desired state defined in REPOSITORIES.md: + +1. **parse-repositories.js** - Parses REPOSITORIES.md markdown format +2. **fetch-github-state.js** - Fetches current GitHub organization state +3. **detect-drift.js** - Compares desired vs actual state +4. **sync-repositories.js** - Applies changes to GitHub organization + +## Scripts + +### parse-repositories.js + +**Purpose**: Parses REPOSITORIES.md to extract repository definitions. + +**Usage**: +```javascript +import { parseRepositoriesFile } from './parse-repositories.js'; + +const repositories = await parseRepositoriesFile(); +// Returns array of { name, description, topics } +``` + +**Features**: +- Extracts repository name from markdown h2 headings (`## repo-name`) +- Parses description from `- Description: ...` lines +- Parses topics from `- Topics: topic1, topic2, topic3` lines +- Validates required fields (name and description) +- Skips code blocks (between triple backticks) to ignore examples +- Handles optional topics field + +**Error Handling**: +- Throws error if repository missing required description +- Skips malformed entries with warnings +- Validates markdown structure + +**Example Repository Definition**: +```markdown +## my-repository +- Description: A brief description of what this repository does +- Topics: topic1, topic2, topic3 +``` + +### fetch-github-state.js + +**Purpose**: Fetches current repository state from GitHub organization. + +**Usage**: +```javascript +import { fetchGitHubRepositories } from './fetch-github-state.js'; + +const token = process.env.WORLDDRIVEN_GITHUB_TOKEN; +const repositories = await fetchGitHubRepositories(token); +// Returns array of { name, description, topics } +``` + +**Features**: +- Fetches all repositories in worlddriven organization +- Handles pagination for large organizations +- Extracts repository names, descriptions, and topics +- Uses GitHub REST API v3 + +**API Calls**: +- `GET /orgs/worlddriven/repos` - List organization repositories +- Handles rate limiting gracefully +- Supports pagination via Link headers + +**Returns**: +```javascript +[ + { + name: "repository-name", + description: "Repository description", + topics: ["topic1", "topic2"] + }, + // ... +] +``` + +### detect-drift.js + +**Purpose**: Compares desired state (REPOSITORIES.md) with actual state (GitHub organization) and identifies differences. + +**Usage**: +```javascript +import { detectDrift } from './detect-drift.js'; + +const drift = detectDrift(desiredRepos, actualRepos); +``` + +**Detects**: +- **Missing repositories**: In REPOSITORIES.md but not on GitHub +- **Extra repositories**: On GitHub but not in REPOSITORIES.md +- **Description drift**: Descriptions don't match +- **Topic drift**: Topics don't match + +**Returns**: +```javascript +{ + missing: [{ name, description, topics }], // To be created + extra: [{ name, description, topics }], // To be deleted + descriptionDiff: [{ name, actual, desired }], // To be updated + topicsDiff: [{ name, actual, desired }] // To be updated +} +``` + +**CLI Usage**: +```bash +# Requires WORLDDRIVEN_GITHUB_TOKEN environment variable +export WORLDDRIVEN_GITHUB_TOKEN=your_token_here +node scripts/detect-drift.js +``` + +**Output**: Markdown-formatted drift report showing all differences. + +### sync-repositories.js + +**Purpose**: Main synchronization engine that applies changes to GitHub organization. + +**Usage**: +```bash +# Dry-run mode (default) - shows what would happen without making changes +export WORLDDRIVEN_GITHUB_TOKEN=your_token_here +node scripts/sync-repositories.js + +# Apply mode - actually makes changes +node scripts/sync-repositories.js --apply +``` + +**Modes**: +- **Dry-run** (default): Shows what would be applied without making changes +- **Apply** (`--apply` flag): Actually applies changes to GitHub + +**Actions**: +1. **Create repositories**: Creates missing repositories with auto_init +2. **Update descriptions**: Updates repository descriptions +3. **Update topics**: Updates repository topics +4. **Ensure settings**: Applies standard repository settings and branch protection +5. **Initialize empty repos**: Adds first commit to empty repositories +6. **Delete repositories**: Deletes extra repositories (except protected ones) + +**Standard Settings Applied**: +```javascript +{ + allow_squash_merge: true, + allow_merge_commit: false, + allow_rebase_merge: false, + allow_auto_merge: false, + delete_branch_on_merge: true, + allow_update_branch: false +} +``` + +**Branch Protection Ruleset**: +- Name: "Worlddriven Democratic Governance" +- Applies to default branch +- Requires pull request (no direct commits) +- Prevents force push and branch deletion +- Allows squash merge only +- No bypass actors (applies to everyone) + +**Protected Repositories**: +The following repositories cannot be auto-deleted: +- `documentation` - This repository +- `core` - The worlddriven application server +- `webapp` - The worlddriven web interface + +**Exit Codes**: +- `0` - Success (all actions completed) +- `1` - Failure (one or more actions failed) + +**Environment Variables**: +- `WORLDDRIVEN_GITHUB_TOKEN` (required) - GitHub Personal Access Token with: + - `repo` - Full control of repositories + - `admin:org` - Manage organization + - `delete_repo` - Delete repositories + +## Development + +### Running Tests + +```bash +npm test +``` + +Tests are located in `../tests/` directory and cover: +- Repository parsing logic +- Edge cases in markdown format +- Code block handling +- Validation of required fields + +### Local Testing + +```bash +# Set your GitHub token +export WORLDDRIVEN_GITHUB_TOKEN=ghp_your_token_here + +# Test parsing +node scripts/parse-repositories.js + +# Test drift detection (read-only) +node scripts/detect-drift.js + +# Test sync in dry-run mode (read-only, safe) +node scripts/sync-repositories.js + +# Apply changes (CAUTION: Makes real changes!) +node scripts/sync-repositories.js --apply +``` + +### Adding New Features + +When modifying the automation scripts: + +1. **Update parser** (`parse-repositories.js`) if adding new repository properties +2. **Update drift detection** (`detect-drift.js`) to detect new property differences +3. **Update sync** (`sync-repositories.js`) to apply new property changes +4. **Add tests** in `../tests/` directory +5. **Update documentation** in this file and AUTOMATION.md + +### Error Handling + +All scripts handle errors gracefully: +- **Network errors**: Retry logic for transient failures +- **API errors**: Clear error messages with HTTP status codes +- **Validation errors**: Specific error messages about what's wrong +- **Rate limiting**: Respect GitHub API rate limits + +### Debugging + +Enable verbose output: +```bash +# Scripts log to stderr for status updates +# Actual reports go to stdout for piping +node scripts/sync-repositories.js 2>&1 | tee sync-log.txt +``` + +## GitHub Actions Integration + +These scripts are used by GitHub Actions workflows: + +### Drift Detection Workflow +**File**: `.github/workflows/drift-detection.yml` +**Trigger**: PRs modifying REPOSITORIES.md +**Script**: `node scripts/detect-drift.js` +**Output**: PR comment showing drift + +### Sync Workflow +**File**: `.github/workflows/sync-repositories.yml` +**Trigger**: Push to main branch +**Script**: `node scripts/sync-repositories.js --apply` +**Output**: Commit comment with sync results + +See [AUTOMATION.md](../AUTOMATION.md) for complete workflow documentation. + +## API Reference + +### parseRepositoriesFile() + +```javascript +/** + * Parse REPOSITORIES.md and extract repository definitions + * @returns {Promise>} Array of repository objects + * @throws {Error} If required fields are missing + */ +async function parseRepositoriesFile(): Promise + +interface Repository { + name: string // Repository name (required) + description: string // Repository description (required) + topics?: string[] // Optional topics +} +``` + +### fetchGitHubRepositories(token) + +```javascript +/** + * Fetch current repository state from GitHub organization + * @param {string} token - GitHub Personal Access Token + * @returns {Promise>} Current GitHub repositories + * @throws {Error} If API call fails + */ +async function fetchGitHubRepositories(token: string): Promise +``` + +### detectDrift(desired, actual) + +```javascript +/** + * Compare desired and actual repository state + * @param {Array} desired - Desired repositories from REPOSITORIES.md + * @param {Array} actual - Current GitHub repositories + * @returns {Drift} Object describing all differences + */ +function detectDrift(desired: Repository[], actual: Repository[]): Drift + +interface Drift { + missing: Repository[] // In REPOSITORIES.md but not GitHub + extra: Repository[] // On GitHub but not in REPOSITORIES.md + descriptionDiff: DescDiff[] // Description mismatches + topicsDiff: TopicDiff[] // Topic mismatches +} +``` + +## Troubleshooting + +### "WORLDDRIVEN_GITHUB_TOKEN environment variable is not set" + +**Solution**: Set the environment variable with your GitHub Personal Access Token: +```bash +export WORLDDRIVEN_GITHUB_TOKEN=ghp_your_token_here +``` + +### "GitHub API error (403)" + +**Possible causes**: +- Token doesn't have required permissions +- Rate limit exceeded +- Resource not accessible with this token type + +**Solutions**: +- Verify token has `repo`, `admin:org`, and `delete_repo` scopes +- Wait for rate limit to reset +- Use GitHub App authentication instead of PAT + +### "Repository not found" when syncing + +**Cause**: Repository was already deleted or never existed + +**Solution**: Run drift detection first to see current state + +### Sync fails with conflicts + +**Cause**: Manual changes made to GitHub that conflict with REPOSITORIES.md + +**Solution**: Either: +1. Update REPOSITORIES.md to match GitHub (revert manual changes) +2. Re-run sync to overwrite GitHub with REPOSITORIES.md state + +## Security Considerations + +- **Token Security**: Never commit tokens to repository +- **Least Privilege**: Token should only have necessary permissions +- **Audit Logging**: All changes logged in commit comments and workflow summaries +- **Protected Repos**: Critical infrastructure protected from auto-deletion +- **Transparency**: All changes visible in git history + +## Contributing + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines on: +- Proposing automation improvements +- Adding new features +- Testing changes +- Security best practices