This folder contains GitHub-specific configuration for Open Notebook's contribution workflow.

We have three issue templates to guide contributors:

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.

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.

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.

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

Our CI/CD workflows in .github/workflows/:

• Builds Docker images on releases
• Publishes to Docker Hub and GitHub Container Registry
• Supports multi-platform builds (amd64, arm64)

• Builds dev images on pushes to main
• Tags with commit SHA for testing

• Automated code review using Claude Code
• Runs on pull requests
• Provides AI-powered suggestions

┌─────────────────────────────────────────────────────────┐ │ 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 │ └─────────────────────────────────────────────────────────┘ 

• Contributors don't spend time on code that won't be merged
• Ensures alignment with project vision before coding starts

• All code reviewed against design principles
• Consistent architecture across contributions
• Proper testing and documentation

• Clear expectations upfront
• Structured feedback process
• Efficient review process

• Maintainers can guide direction
• Features align with long-term goals
• Technical debt is minimized

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

• 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.