mirror of
https://github.com/lfnovo/open-notebook.git
synced 2026-05-02 21:30:38 +00:00
1331e0feec
* 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.
191 lines
9.1 KiB
Markdown
191 lines
9.1 KiB
Markdown
# 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.
|