docs: improve contribution workflow and project governance (#246)

* chore: bump esperanto for anthropic on langchain * docs: improve contribution workflow and project governance Implements a comprehensive contribution management system to maintain project quality and vision while welcoming community contributions. Key Changes: - Updated CONTRIBUTING.md with clear issue-first workflow - Added "willing to contribute" checkbox to issue templates - Created DESIGN_PRINCIPLES.md documenting project vision and principles - Added comprehensive PR template with quality checklists - Created MAINTAINER_GUIDE.md with review processes and templates - Added .github/README.md explaining the contribution flow Benefits: - Prevents wasted effort on misaligned contributions - Maintains architectural consistency - Provides clear expectations for contributors - Gives maintainers tools to manage contributions effectively - Educates contributors on project goals and standards Related to managing increased community contributions while maintaining project direction.
2026-05-02 21:30:38 +00:00 · 2025-11-01 16:34:28 -03:00 · 2025-11-01 16:34:28 -03:00 · 1331e0feec
commit 1331e0feec
parent 6fe78a64f7
7 changed files with 1177 additions and 13 deletions
--- a/.github/README.md
+++ b/.github/README.md
@ -0,0 +1,191 @@
+# GitHub Workflow & Templates
+
+This folder contains GitHub-specific configuration for Open Notebook's contribution workflow.
+
+## 📋 Issue Templates
+
+We have three issue templates to guide contributors:
+
+### 🐛 Bug Report (`ISSUE_TEMPLATE/bug_report.yml`)
+
+For reporting bugs or unexpected behavior when the app is running but misbehaving.
+
+**Key Features:**
+- Structured format for bug details
+- Environment and version information
+- Checkbox for contributors who want to fix the issue
+- Automatic `bug` and `needs-triage` labels
+
+**When to Use:** App is installed and running, but something doesn't work as expected.
+
+### ✨ Feature Request (`ISSUE_TEMPLATE/feature_request.yml`)
+
+For suggesting new features or improvements.
+
+**Key Features:**
+- Description of the feature
+- Explanation of why it would be helpful
+- Space for proposed solution
+- Checkbox for contributors who want to implement it
+- Automatic `enhancement` and `needs-triage` labels
+
+**When to Use:** You have an idea for a new feature or improvement.
+
+### 🔧 Installation Issue (`ISSUE_TEMPLATE/installation_issue.yml`)
+
+For problems with installation or setup.
+
+**Key Features:**
+- Deployment type selection
+- Environment details
+- Error message collection
+- Automatic `installation` label
+
+**When to Use:** Having trouble getting Open Notebook running.
+
+## 🔄 Pull Request Template
+
+The PR template (`pull_request_template.md`) ensures contributors provide all necessary information:
+
+**Sections:**
+- Description and related issue
+- Type of change
+- Testing details
+- Design alignment with project principles
+- Comprehensive checklist for code quality, testing, documentation
+- Screenshots for UI changes
+
+**Key Checkpoints:**
+- References an approved issue
+- Aligns with [design principles](../DESIGN_PRINCIPLES.md)
+- Includes tests and documentation
+- Follows code style guidelines
+
+## 🚀 GitHub Actions
+
+Our CI/CD workflows in `.github/workflows/`:
+
+### `build-and-release.yml`
+- Builds Docker images on releases
+- Publishes to Docker Hub and GitHub Container Registry
+- Supports multi-platform builds (amd64, arm64)
+
+### `build-dev.yml`
+- Builds dev images on pushes to main
+- Tags with commit SHA for testing
+
+### `claude-code-review.yml`
+- Automated code review using Claude Code
+- Runs on pull requests
+- Provides AI-powered suggestions
+
+## 📖 How the Contribution Flow Works
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. Contributor identifies a bug or has a feature idea   │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 2. Creates an issue using appropriate template          │
+│    - Describes the problem/feature                      │
+│    - Checks "I am a developer..." if willing to work    │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 3. Maintainer reviews issue (within 48 hours)           │
+│    - Assesses alignment with design principles          │
+│    - Labels appropriately                               │
+│    - Asks for clarification if needed                   │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 4. If approved: Contributor proposes solution approach  │
+│    - Discusses implementation strategy                  │
+│    - Maintainer provides feedback                       │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 5. Issue is assigned to contributor                     │
+│    - Contributor forks repo                             │
+│    - Creates feature branch from main                   │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 6. Contributor develops solution                        │
+│    - Reads DESIGN_PRINCIPLES.md                         │
+│    - Reads docs/development/architecture.md             │
+│    - Writes code, tests, documentation                  │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 7. Creates Pull Request                                 │
+│    - Uses PR template                                   │
+│    - References issue number                            │
+│    - Fills out all checklist items                      │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 8. Maintainer reviews PR                                │
+│    - Checks code quality                                │
+│    - Verifies tests pass                                │
+│    - Ensures alignment with architecture                │
+│    - Provides feedback or approves                      │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 9. If approved: PR is merged! 🎉                        │
+│    - Contributor is thanked                             │
+│    - Issue is closed                                    │
+│    - Changes included in next release                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 🎯 Why This Process?
+
+### Prevents Wasted Effort
+- Contributors don't spend time on code that won't be merged
+- Ensures alignment with project vision before coding starts
+
+### Maintains Quality
+- All code reviewed against design principles
+- Consistent architecture across contributions
+- Proper testing and documentation
+
+### Respects Everyone's Time
+- Clear expectations upfront
+- Structured feedback process
+- Efficient review process
+
+### Protects Project Vision
+- Maintainers can guide direction
+- Features align with long-term goals
+- Technical debt is minimized
+
+## 📚 Related Documentation
+
+For contributors:
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
+- [DESIGN_PRINCIPLES.md](../DESIGN_PRINCIPLES.md) - Project vision and principles
+- [docs/development/architecture.md](../docs/development/architecture.md) - Technical architecture
+
+For maintainers:
+- [MAINTAINER_GUIDE.md](../MAINTAINER_GUIDE.md) - How to review and manage contributions
+
+## 🤝 Questions?
+
+- Join our [Discord](https://discord.gg/37XJPXfz2w)
+- Open a [Discussion](https://github.com/lfnovo/open-notebook/discussions)
+- Read the [FAQ](../docs/troubleshooting/faq.md)
+
+---
+
+**Thank you for contributing to Open Notebook!** Your contributions help make this the best open-source research tool available.