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
• 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 - Contribution guidelines
• DESIGN_PRINCIPLES.md - Project vision and principles
• docs/development/architecture.md - Technical architecture

For maintainers:

• MAINTAINER_GUIDE.md - How to review and manage contributions

🤝 Questions?

• Join our Discord
• Open a Discussion
• Read the FAQ

---

Thank you for contributing to Open Notebook! Your contributions help make this the best open-source research tool available.