From 1331e0feeceac4945fe6e64f3e06c0421477e064 Mon Sep 17 00:00:00 2001 From: Luis Novo Date: Sat, 1 Nov 2025 16:34:28 -0300 Subject: [PATCH] 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. --- .github/ISSUE_TEMPLATE/bug_report.yml | 19 + .github/ISSUE_TEMPLATE/feature_request.yml | 28 ++ .github/README.md | 191 ++++++++++ .github/pull_request_template.md | 107 ++++++ CONTRIBUTING.md | 86 ++++- DESIGN_PRINCIPLES.md | 351 ++++++++++++++++++ MAINTAINER_GUIDE.md | 408 +++++++++++++++++++++ 7 files changed, 1177 insertions(+), 13 deletions(-) create mode 100644 .github/README.md create mode 100644 .github/pull_request_template.md create mode 100644 DESIGN_PRINCIPLES.md create mode 100644 MAINTAINER_GUIDE.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 8d5077e..1da9bd5 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -83,3 +83,22 @@ body: placeholder: "This started happening after I upgraded to v1.5.0..." validations: required: false + + - type: checkboxes + id: willing-to-contribute + attributes: + label: Contribution + description: Would you like to work on fixing this bug? + options: + - label: I am a developer and would like to work on fixing this issue (pending maintainer approval) + required: false + + - type: markdown + attributes: + value: | + --- + **Next Steps:** + 1. A maintainer will review your bug report + 2. If you checked the box above and want to fix it, please propose your solution approach + 3. Wait for assignment before starting development + 4. See our [Contributing Guide](https://github.com/lfnovo/open-notebook/blob/main/CONTRIBUTING.md) for more details diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 8bb89fc..912f1f1 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -26,6 +26,15 @@ body: validations: required: true + - type: textarea + id: proposed-solution + attributes: + label: Proposed Solution (Optional) + description: If you have ideas on how to implement this feature, please share them + placeholder: "This could be implemented by..." + validations: + required: false + - type: textarea id: additional-context attributes: @@ -35,3 +44,22 @@ body: validations: required: false + - type: checkboxes + id: willing-to-contribute + attributes: + label: Contribution + description: Would you like to work on implementing this feature? + options: + - label: I am a developer and would like to work on implementing this feature (pending maintainer approval) + required: false + + - type: markdown + attributes: + value: | + --- + **Next Steps:** + 1. A maintainer will review your feature request + 2. If approved and you checked the box above, the issue will be assigned to you + 3. Please wait for assignment before starting development + 4. See our [Contributing Guide](https://github.com/lfnovo/open-notebook/blob/main/CONTRIBUTING.md) for more details + diff --git a/.github/README.md b/.github/README.md new file mode 100644 index 0000000..66f0a27 --- /dev/null +++ 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. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..71e18da --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,107 @@ +## Description + + + +## Related Issue + + + +Fixes # + +## Type of Change + + + +- [ ] Bug fix (non-breaking change that fixes an issue) +- [ ] New feature (non-breaking change that adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Code refactoring (no functional changes) +- [ ] Performance improvement +- [ ] Test coverage improvement + +## How Has This Been Tested? + + + +- [ ] Tested locally with Docker +- [ ] Tested locally with development setup +- [ ] Added new unit tests +- [ ] Existing tests pass (`uv run pytest`) +- [ ] Manual testing performed (describe below) + +**Test Details:** + + +## Design Alignment + + + +**Which design principles does this PR support?** (See [DESIGN_PRINCIPLES.md](../DESIGN_PRINCIPLES.md)) + +- [ ] Privacy First +- [ ] Simplicity Over Features +- [ ] API-First Architecture +- [ ] Multi-Provider Flexibility +- [ ] Extensibility Through Standards +- [ ] Async-First for Performance + +**Explanation:** + + +## Checklist + + + +### Code Quality +- [ ] My code follows PEP 8 style guidelines (Python) +- [ ] My code follows TypeScript best practices (Frontend) +- [ ] I have added type hints to my code (Python) +- [ ] I have added JSDoc comments where appropriate (TypeScript) +- [ ] I have performed a self-review of my code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] My changes generate no new warnings or errors + +### Testing +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] I ran linting: `make ruff` or `ruff check . --fix` +- [ ] I ran type checking: `make lint` or `uv run python -m mypy .` + +### Documentation +- [ ] I have updated the relevant documentation in `/docs` (if applicable) +- [ ] I have added/updated docstrings for new/modified functions +- [ ] I have updated the API documentation (if API changes were made) +- [ ] I have added comments to complex logic + +### Database Changes +- [ ] I have created migration scripts for any database schema changes (in `/migrations`) +- [ ] Migration includes both up and down scripts +- [ ] Migration has been tested locally + +### Breaking Changes +- [ ] This PR includes breaking changes +- [ ] I have documented the migration path for users +- [ ] I have updated MIGRATION.md (if applicable) + +## Screenshots (if applicable) + + + +## Additional Context + + + +## Pre-Submission Verification + +Before submitting, please verify: + +- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md) +- [ ] I have read [DESIGN_PRINCIPLES.md](../DESIGN_PRINCIPLES.md) +- [ ] This PR addresses an approved issue that was assigned to me +- [ ] I have not included unrelated changes in this PR +- [ ] My PR title follows conventional commits format (e.g., "feat: add user authentication") + +--- + +**Thank you for contributing to Open Notebook!** 🎉 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e103815..833912d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,30 +1,90 @@ # Contributing to Open Notebook -First off, thank you for considering contributing to Open Notebook! What makes open source great is the fact that we can work together and accomplish things we would never do on our own. All suggestions are welcome. +First off, thank you for considering contributing to Open Notebook! What makes open source great is the fact that we can work together and accomplish things we would never do on our own. All suggestions are welcome. + +## 🚨 Important: Read Before Contributing Code + +**To maintain project coherence and avoid wasted effort, please follow this process:** + +1. **Create an issue first** - Before writing any code, create an issue describing the bug or feature +2. **Propose your solution** - Explain how you plan to implement the fix or feature +3. **Wait for assignment** - A maintainer will review and assign the issue to you if approved +4. **Only then start coding** - This ensures your work aligns with the project's vision and architecture + +**Why this process?** +- Prevents duplicate work +- Ensures solutions align with our architecture and design principles +- Saves your time by getting feedback before coding +- Helps maintainers manage the project direction + +> ⚠️ **Pull requests without an assigned issue may be closed**, even if the code is good. We want to respect your time by making sure work is aligned before it starts. ## Code of Conduct -By participating in this project, you are expected to uphold our Code of Conduct (to be created separately). +By participating in this project, you are expected to uphold our Code of Conduct. Be respectful, constructive, and collaborative. ## How Can I Contribute? ### Reporting Bugs -- Ensure the bug was not already reported by searching on GitHub under [Issues](https://github.com/yourusername/open-notebook/issues). -- If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/yourusername/open-notebook/issues/new). Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring. +1. **Search existing issues** - Check if the bug was already reported in [Issues](https://github.com/lfnovo/open-notebook/issues) +2. **Create a bug report** - Use the [Bug Report template](https://github.com/lfnovo/open-notebook/issues/new?template=bug_report.yml) +3. **Provide details** - Include: + - Steps to reproduce + - Expected vs actual behavior + - Logs, screenshots, or error messages + - Your environment (OS, Docker version, Open Notebook version) +4. **Indicate if you want to fix it** - Check the "I would like to work on this" box if you're interested -### Suggesting Enhancements +### Suggesting Features -- Open a new issue with a clear title and detailed description of the suggested enhancement. -- Provide any relevant examples or mockups if applicable. +1. **Search existing issues** - Check if the feature was already suggested +2. **Create a feature request** - Use the [Feature Request template](https://github.com/lfnovo/open-notebook/issues/new?template=feature_request.yml) +3. **Explain the value** - Describe why this feature would be helpful +4. **Propose implementation** - If you have ideas on how to implement it, share them +5. **Indicate if you want to build it** - Check the "I would like to work on this" box if you're interested -### Pull Requests +### Contributing Code (Pull Requests) -1. Fork the repo and create your branch from `main`. -2. If you've added code that should be tested, add tests. -3. Ensure the test suite passes. -4. Make sure your code lints. -5. Issue that pull request! +**IMPORTANT: Follow the issue-first workflow above before starting any PR** + +Once your issue is assigned: + +1. **Fork the repo** and create your branch from `main` +2. **Understand our vision and principles** - Read [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md) to understand what guides our decisions +3. **Follow our architecture** - Read [docs/development/architecture.md](docs/development/architecture.md) to understand the project structure +4. **Write quality code**: + - Follow PEP 8 for Python + - Use TypeScript best practices for frontend + - Add type hints and proper error handling + - Write docstrings for functions and classes +4. **Test your changes**: + - Add tests for new features + - Ensure existing tests pass: `uv run pytest` + - Run linter: `make ruff` or `ruff check . --fix` + - Run type checker: `make lint` or `uv run python -m mypy .` +5. **Update documentation** - If you changed functionality, update the relevant docs in `/docs` +6. **Create your PR**: + - Reference the issue number (e.g., "Fixes #123") + - Describe what changed and why + - Include screenshots for UI changes + - Keep PRs focused - one issue per PR + +### What Makes a Good Contribution? + +✅ **We love PRs that:** +- Solve a real problem described in an issue +- Follow our architecture and coding standards +- Include tests and documentation +- Are well-scoped (focused on one thing) +- Have clear commit messages + +❌ **We may close PRs that:** +- Don't have an associated approved issue +- Introduce breaking changes without discussion +- Conflict with our architectural vision +- Lack tests or documentation +- Try to solve multiple unrelated problems ## Styleguides diff --git a/DESIGN_PRINCIPLES.md b/DESIGN_PRINCIPLES.md new file mode 100644 index 0000000..7ca5346 --- /dev/null +++ b/DESIGN_PRINCIPLES.md @@ -0,0 +1,351 @@ +# Design Principles & Project Vision + +This document outlines the core principles, vision, and design philosophy that guide Open Notebook's development. All contributors should read and understand these principles before proposing changes or new features. + +## 🎯 Project Vision + +Open Notebook aims to be a **privacy-focused, self-hosted alternative to Google's Notebook LM** that empowers users to: + +1. **Own their research data** - Full control over where data lives and who can access it +2. **Choose their AI providers** - Freedom to use any AI provider or run models locally +3. **Customize their workflows** - Flexibility to adapt the tool to different research needs +4. **Access their work anywhere** - Through web UI, API, or integrations + +### What Open Notebook IS + +- A **research assistant** for managing and understanding content +- A **platform** that connects various AI providers +- A **privacy-first** tool that keeps your data under your control +- An **extensible system** with APIs and customization options + +### What Open Notebook IS NOT + +- A document editor (use Google Docs, Notion, etc. for that) +- A file storage system (use Dropbox, S3, etc. for that) +- A general-purpose chatbot (use ChatGPT, Claude, etc. for that) +- A replacement for your entire workflow (it's one tool in your toolkit) + +## 🏗️ Core Design Principles + +### 1. Privacy First + +**Principle**: User data and research should stay under user control by default. + +**In Practice**: +- Self-hosted deployment is the primary use case +- No telemetry or analytics without explicit opt-in +- No hard dependency on specific cloud services +- Clear documentation on what data goes where + +**Example Decisions**: +- ✅ Support for local Ollama models +- ✅ Configurable AI provider selection +- ❌ Hard-coded cloud service integrations +- ❌ Required external service dependencies + +### 2. Simplicity Over Features + +**Principle**: The tool should be easy to understand and use, even if it means fewer features. + +**In Practice**: +- Clear, focused UI with well-defined sections +- Sensible defaults that work for most users +- Advanced features hidden behind optional configuration +- Documentation written for non-technical users + +**Example Decisions**: +- ✅ Three-column layout (Sources, Notes, Chat) +- ✅ Default models that work out of the box +- ❌ Overwhelming users with too many options upfront +- ❌ Complex multi-step workflows for basic tasks + +### 3. API-First Architecture + +**Principle**: All functionality should be accessible via API, not just the UI. + +**In Practice**: +- UI calls the same API that external clients use +- Comprehensive REST API with OpenAPI documentation +- No "UI-only" features that can't be automated +- Clear separation between frontend and backend + +**Example Decisions**: +- ✅ FastAPI backend with full API documentation +- ✅ Consistent API patterns across all endpoints +- ❌ Business logic in UI components +- ❌ Features that require direct database access + +### 4. Multi-Provider Flexibility + +**Principle**: Users should never be locked into a single AI provider. + +**In Practice**: +- Support for multiple AI providers through Esperanto library +- Easy switching between providers and models +- Clear documentation on provider limitations +- Graceful degradation when providers are unavailable + +**Example Decisions**: +- ✅ Support for 16+ AI providers +- ✅ Per-feature model selection (chat, embeddings, TTS) +- ❌ Features that only work with OpenAI +- ❌ Hard-coded API endpoints for specific providers + +### 5. Extensibility Through Standards + +**Principle**: The system should be extensible through well-defined interfaces, not by forking. + +**In Practice**: +- Plugin systems for transformations and commands +- Standard data formats (JSON, Markdown) +- Clear extension points in the architecture +- Documentation for common customization scenarios + +**Example Decisions**: +- ✅ Custom transformation templates +- ✅ Background command system +- ✅ Jinja2 prompt templates +- ❌ Hard-coded business logic without extension points + +### 6. Async-First for Performance + +**Principle**: Long-running operations should not block the user interface or API. + +**In Practice**: +- Async/await patterns throughout the backend +- Background job processing for heavy workloads +- Status updates and progress tracking +- Graceful handling of slow AI provider responses + +**Example Decisions**: +- ✅ AsyncIO for database operations +- ✅ Background commands for podcast generation +- ✅ Streaming responses for chat +- ❌ Synchronous blocking operations in API endpoints + +## 🎨 UI/UX Principles + +### Focus on Content, Not Chrome + +- Minimize UI clutter and distractions +- Content should occupy most of the screen space +- Controls appear when needed, not always visible +- Consistent layout across different views + +### Progressive Disclosure + +- Show simple options first, advanced options on demand +- Don't overwhelm new users with every possible setting +- Provide sensible defaults that work for 80% of use cases +- Make power features discoverable but not intrusive + +### Responsive and Fast + +- UI should feel instant for common operations +- Show loading states for operations that take time +- Cache and optimize where possible +- Degrade gracefully on slow connections + +## 🔧 Technical Principles + +### Clean Separation of Concerns + +**Layers should not leak**: +- Frontend should not know about database structure +- API should not contain business logic (delegate to domain layer) +- Domain models should not know about HTTP requests +- Database layer should not know about AI providers + +### Type Safety and Validation + +**Catch errors early**: +- Use Pydantic models for all API boundaries +- Type hints throughout Python codebase +- TypeScript for frontend code +- Validate data at system boundaries + +### Test What Matters + +**Focus on valuable tests**: +- Test business logic and domain models +- Test API contracts and error handling +- Don't test framework code (FastAPI, React, etc.) +- Integration tests for critical workflows + +### Database as Source of Truth + +**SurrealDB is our single source of truth**: +- All state persisted in database +- No business logic in database layer +- Use SurrealDB features (record links, queries) appropriately +- Schema migrations for all schema changes + +## 🚫 Anti-Patterns to Avoid + +### Feature Creep + +**What it looks like**: +- Adding features because they're "cool" or "easy" +- Building features for edge cases before common cases work well +- Trying to be everything to everyone + +**Why we avoid it**: +- Increases complexity and maintenance burden +- Makes the tool harder to learn and use +- Dilutes the core value proposition + +**Instead**: +- Focus on core use cases +- Say no to features that don't align with vision +- Build extensibility points for edge cases + +### Premature Optimization + +**What it looks like**: +- Optimizing code before knowing if it's slow +- Complex caching strategies without measuring impact +- Trading code clarity for marginal performance gains + +**Why we avoid it**: +- Makes code harder to understand and maintain +- Optimizes the wrong things +- Wastes development time + +**Instead**: +- Measure first, optimize second +- Focus on algorithmic improvements +- Profile before making performance changes + +### Over-Engineering + +**What it looks like**: +- Building abstraction layers "in case we need them later" +- Implementing design patterns for 3-line functions +- Creating frameworks instead of solving problems + +**Why we avoid it**: +- Increases cognitive load for contributors +- Makes simple changes require touching many files +- Hides the actual business logic + +**Instead**: +- Start simple, refactor when patterns emerge +- Optimize for readability and clarity +- Use abstractions when they simplify, not complicate + +### Breaking Changes Without Migration Path + +**What it looks like**: +- Changing database schema without migration scripts +- Modifying API contracts without versioning +- Removing features without deprecation warnings + +**Why we avoid it**: +- Breaks existing installations +- Frustrates users and contributors +- Creates maintenance nightmares + +**Instead**: +- Always provide migration scripts for schema changes +- Deprecate before removing +- Document breaking changes clearly + +## 🤝 Decision-Making Framework + +When evaluating new features or changes, ask: + +### 1. Does it align with our vision? +- Does it help users own their research data? +- Does it support privacy and self-hosting? +- Does it fit our core use cases? + +### 2. Does it follow our principles? +- Is it simple to use and understand? +- Does it work via API? +- Does it support multiple providers? +- Can it be extended by users? + +### 3. Is the implementation sound? +- Does it maintain separation of concerns? +- Is it properly typed and validated? +- Does it include tests? +- Is it documented? + +### 4. What is the cost? +- How much complexity does it add? +- How much maintenance burden? +- Does it introduce new dependencies? +- Will it be used enough to justify the cost? + +### 5. Are there alternatives? +- Can existing features solve this problem? +- Can this be built as a plugin or extension? +- Should this be a separate tool instead? + +## 📚 Examples of Principle-Driven Decisions + +### Why we migrated from Streamlit to Next.js + +**Principle**: API-First Architecture + +**Reasoning**: +- Streamlit coupled UI and backend logic +- Difficult to build external integrations +- Limited control over API behavior +- Next.js + FastAPI provides clear separation + +### Why we use Esperanto for AI providers + +**Principle**: Multi-Provider Flexibility + +**Reasoning**: +- Abstracts provider-specific details +- Easy to add new providers +- Consistent interface across providers +- No vendor lock-in + +### Why we have a Background Command System + +**Principle**: Async-First for Performance + +**Reasoning**: +- Podcast generation takes minutes +- Users shouldn't wait for long operations +- Need status tracking and error handling +- Supports future batch operations + +### Why we support Local Ollama + +**Principle**: Privacy First + +**Reasoning**: +- Enables fully offline operation +- No data sent to external services +- Free for users after hardware cost +- Aligns with self-hosted philosophy + +## 🔄 Evolution of Principles + +These principles are not set in stone. As the project grows and we learn from users, some principles may evolve. However, changes to core principles should be: + +1. **Well-justified** - Clear reasoning for why the change is needed +2. **Discussed openly** - Community input on major changes +3. **Documented** - Updated in this document with explanation +4. **Gradual** - Not implemented as breaking changes when possible + +--- + +## For Contributors + +When proposing a feature or change: + +1. **Reference these principles** - Explain how your proposal aligns +2. **Identify trade-offs** - Be honest about what you're trading for what +3. **Suggest alternatives** - Show you've considered other approaches +4. **Be open to feedback** - Maintainers may see concerns you don't + +**Remember**: A "no" to a feature isn't a judgment on you or your idea. It means we're staying focused on our core vision. We appreciate all contributions and ideas! + +--- + +**Questions about these principles?** Open a discussion on GitHub or join our [Discord](https://discord.gg/37XJPXfz2w). diff --git a/MAINTAINER_GUIDE.md b/MAINTAINER_GUIDE.md new file mode 100644 index 0000000..738ea35 --- /dev/null +++ b/MAINTAINER_GUIDE.md @@ -0,0 +1,408 @@ +# Maintainer Guide + +This guide is for project maintainers to help manage contributions effectively while maintaining project quality and vision. + +## Table of Contents + +- [Issue Management](#issue-management) +- [Pull Request Review](#pull-request-review) +- [Common Scenarios](#common-scenarios) +- [Communication Templates](#communication-templates) + +## Issue Management + +### When a New Issue is Created + +**1. Initial Triage** (within 24-48 hours) + +- Add appropriate labels: + - `bug`, `enhancement`, `documentation`, etc. + - `good first issue` for beginner-friendly tasks + - `needs-triage` until reviewed + - `help wanted` if you'd welcome community contributions + +- Quick assessment: + - Is it clear and well-described? + - Is it aligned with project vision? (See [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md)) + - Does it duplicate an existing issue? + +**2. Initial Response** + +```markdown +Thanks for opening this issue! We'll review it and get back to you soon. + +[If it's a bug] In the meantime, have you checked our [troubleshooting guide](docs/troubleshooting/index.md)? + +[If it's a feature] You might find our [design principles](DESIGN_PRINCIPLES.md) helpful for understanding what we're building toward. +``` + +**3. Decision Making** + +Ask yourself: +- Does this align with our [design principles](DESIGN_PRINCIPLES.md)? +- Is this something we want in the core project, or better as a plugin/extension? +- Do we have the capacity to support this feature long-term? +- Will this benefit most users, or just a specific use case? + +**4. Issue Assignment** + +If the contributor checked "I am a developer and would like to work on this": + +**For Accepted Issues:** +```markdown +Great idea! This aligns well with our goals, particularly [specific design principle]. + +I see you'd like to work on this. Before you start: + +1. Please share your proposed approach/solution +2. Review our [Contributing Guide](CONTRIBUTING.md) and [Design Principles](DESIGN_PRINCIPLES.md) +3. Once we agree on the approach, I'll assign this to you + +Looking forward to your thoughts! +``` + +**For Issues Needing Clarification:** +```markdown +Thanks for offering to work on this! Before we proceed, we need to clarify a few things: + +1. [Question 1] +2. [Question 2] + +Once we have these details, we can discuss the best approach. +``` + +**For Issues Not Aligned with Vision:** +```markdown +Thank you for the suggestion and for offering to work on this! + +After reviewing against our [design principles](DESIGN_PRINCIPLES.md), we've decided not to pursue this in the core project because [specific reason]. + +However, you might be able to achieve this through [alternative approach, if applicable]. + +We appreciate your interest in contributing! Feel free to check out our [open issues](link) for other ways to contribute. +``` + +### Labels to Use + +**Priority:** +- `priority: critical` - Security issues, data loss bugs +- `priority: high` - Major functionality broken +- `priority: medium` - Annoying bugs, useful features +- `priority: low` - Nice to have, edge cases + +**Status:** +- `needs-triage` - Not yet reviewed by maintainer +- `needs-info` - Waiting for more information from reporter +- `needs-discussion` - Requires community/team discussion +- `ready` - Approved and ready to be worked on +- `in-progress` - Someone is actively working on this +- `blocked` - Cannot proceed due to external dependency + +**Type:** +- `bug` - Something is broken +- `enhancement` - New feature or improvement +- `documentation` - Documentation improvements +- `question` - General questions +- `refactor` - Code cleanup/restructuring + +**Difficulty:** +- `good first issue` - Good for newcomers +- `help wanted` - Community contributions welcome +- `advanced` - Requires deep codebase knowledge + +## Pull Request Review + +### Initial PR Review Checklist + +**Before diving into code:** + +- [ ] Is there an associated approved issue? +- [ ] Does the PR reference the issue number? +- [ ] Is the PR description clear about what changed and why? +- [ ] Did the contributor check the relevant boxes in the PR template? +- [ ] Are there tests? Screenshots (for UI changes)? + +**Red Flags** (may require closing PR): +- No associated issue +- Issue was not assigned to contributor +- PR tries to solve multiple unrelated problems +- Breaking changes without discussion +- Conflicts with project vision + +### Code Review Process + +**1. High-Level Review** + +- Does the approach align with our architecture? +- Is the solution appropriately scoped? +- Are there simpler alternatives? +- Does it follow our design principles? + +**2. Code Quality Review** + +Python: +- [ ] Follows PEP 8 +- [ ] Has type hints +- [ ] Has docstrings +- [ ] Proper error handling +- [ ] No security vulnerabilities + +TypeScript/Frontend: +- [ ] Follows TypeScript best practices +- [ ] Proper component structure +- [ ] No console.logs left in production code +- [ ] Accessible UI components + +**3. Testing Review** + +- [ ] Has appropriate test coverage +- [ ] Tests are meaningful (not just for coverage percentage) +- [ ] Tests pass locally and in CI +- [ ] Edge cases are tested + +**4. Documentation Review** + +- [ ] Code is well-commented +- [ ] Complex logic is explained +- [ ] User-facing documentation updated (if applicable) +- [ ] API documentation updated (if API changed) +- [ ] Migration guide provided (if breaking change) + +### Providing Feedback + +**Positive Feedback** (important!): +```markdown +Thanks for this PR! I really like [specific thing they did well]. + +[Feedback on what needs to change] +``` + +**Requesting Changes:** +```markdown +This is a great start! A few things to address: + +1. **[High-level concern]**: [Explanation and suggested approach] +2. **[Code quality issue]**: [Specific example and fix] +3. **[Testing gap]**: [What scenarios need coverage] + +Let me know if you have questions about any of this! +``` + +**Suggesting Alternative Approach:** +```markdown +I appreciate the effort you put into this! However, I'm concerned about [specific issue]. + +Have you considered [alternative approach]? It might be better because [reasons]. + +What do you think? +``` + +## Common Scenarios + +### Scenario 1: Good Code, Wrong Approach + +**Situation**: Contributor wrote quality code, but solved the problem in a way that doesn't fit our architecture. + +**Response:** +```markdown +Thank you for this PR! The code quality is great, and I can see you put thought into this. + +However, I'm concerned that this approach [specific architectural concern]. In our architecture, we [explain the pattern we follow]. + +Would you be open to refactoring this to [suggested approach]? I'm happy to provide guidance on the specifics. + +Alternatively, if you don't have time for a refactor, I can take over and finish this up (with credit to you, of course). + +Let me know what you prefer! +``` + +### Scenario 2: PR Without Assigned Issue + +**Situation**: Contributor submitted PR without going through issue approval process. + +**Response:** +```markdown +Thanks for the PR! I appreciate you taking the time to contribute. + +However, to maintain project coherence, we require all PRs to be linked to an approved issue that was assigned to the contributor. This is explained in our [Contributing Guide](CONTRIBUTING.md). + +This helps us: +- Ensure work aligns with project vision +- Prevent duplicate efforts +- Discuss approach before implementation + +Could you please: +1. Create an issue describing this change +2. Wait for it to be reviewed and assigned to you +3. We can then reopen this PR or you can create a new one + +Sorry for the inconvenience - this process helps us manage the project effectively. +``` + +### Scenario 3: Feature Request Not Aligned with Vision + +**Situation**: Well-intentioned feature that doesn't fit project goals. + +**Response:** +```markdown +Thank you for this suggestion! I can see how this would be useful for [specific use case]. + +After reviewing against our [design principles](DESIGN_PRINCIPLES.md), we've decided not to include this in the core project because [specific reason - e.g., "it conflicts with our 'Simplicity Over Features' principle" or "it would require dependencies that conflict with our privacy-first approach"]. + +Some alternatives: +- [If applicable] This could be built as a plugin/extension +- [If applicable] This functionality might be achievable through [existing feature] +- [If applicable] You might be interested in [other tool] which is designed for this use case + +We appreciate your contribution and hope you understand. Feel free to check our [roadmap](link) or [open issues](link) for other ways to contribute! +``` + +### Scenario 4: Contributor Ghosts After Feedback + +**Situation**: You requested changes, but contributor hasn't responded in 2+ weeks. + +**After 2 weeks:** +```markdown +Hey there! Just checking in on this PR. Do you have time to address the feedback, or would you like someone else to take over? + +No pressure either way - just want to make sure this doesn't fall through the cracks. +``` + +**After 1 month with no response:** +```markdown +Thanks again for starting this work! Since we haven't heard back, I'm going to close this PR for now. + +If you want to pick this up again in the future, feel free to reopen it or create a new PR. Alternatively, I'll mark the issue as available for someone else to work on. + +We appreciate your contribution! +``` + +Then: +- Close the PR +- Unassign the issue +- Add `help wanted` label to the issue + +### Scenario 5: Breaking Changes Without Discussion + +**Situation**: PR introduces breaking changes that weren't discussed. + +**Response:** +```markdown +Thanks for this PR! However, I notice this introduces breaking changes that weren't discussed in the original issue. + +Breaking changes require: +1. Prior discussion and approval +2. Migration guide for users +3. Deprecation period (when possible) +4. Clear documentation of the change + +Could we discuss the breaking changes first? Specifically: +- [What breaks and why] +- [Who will be affected] +- [Migration path] + +We may need to adjust the approach to minimize impact on existing users. +``` + +## Communication Templates + +### Closing a PR (Misaligned with Vision) + +```markdown +Thank you for taking the time to contribute! We really appreciate it. + +After careful review, we've decided not to merge this PR because [specific reason related to design principles]. + +This isn't a reflection on your code quality - it's about maintaining focus on our core goals as outlined in [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md). + +We'd love to have you contribute in other ways! Check out: +- [Good first issues](link) +- [Help wanted issues](link) +- Our [roadmap](link) + +Thanks again for your interest in Open Notebook! +``` + +### Closing a Stale Issue + +```markdown +We're closing this issue due to inactivity. If this is still relevant, feel free to reopen it with updated information. + +Thanks! +``` + +### Asking for More Information + +```markdown +Thanks for reporting this! To help us investigate, could you provide: + +1. [Specific information needed] +2. [Logs, screenshots, etc.] +3. [Steps to reproduce] + +This will help us understand the issue better and find a solution. +``` + +### Thanking a Contributor + +```markdown +Merged! 🎉 + +Thank you so much for this contribution, @username! [Specific thing they did well]. + +This will be included in the next release. +``` + +## Best Practices + +### Be Kind and Respectful + +- Thank contributors for their time and effort +- Assume good intentions +- Be patient with newcomers +- Explain *why*, not just *what* + +### Be Clear and Direct + +- Don't leave ambiguity about next steps +- Be specific about what needs to change +- Explain architectural decisions +- Set clear expectations + +### Be Consistent + +- Apply the same standards to all contributors +- Follow the process you've defined +- Document decisions for future reference + +### Be Protective of Project Vision + +- It's okay to say "no" +- Prioritize long-term maintainability +- Don't accept features you can't support +- Keep the project focused + +### Be Responsive + +- Respond to issues within 48 hours (even just to acknowledge) +- Review PRs within a week when possible +- Keep contributors updated on status +- Close stale issues/PRs to keep things tidy + +## When in Doubt + +Ask yourself: +1. Does this align with our [design principles](DESIGN_PRINCIPLES.md)? +2. Will we be able to maintain this feature long-term? +3. Does this benefit most users, or just an edge case? +4. Is there a simpler alternative? +5. Would I want to support this in 2 years? + +If you're unsure, it's perfectly fine to: +- Ask for input from other maintainers +- Start a discussion issue +- Sleep on it before making a decision + +--- + +**Remember**: Good maintainership is about balancing openness to contributions with protection of project vision. You're not being mean by saying "no" to things that don't fit - you're being a responsible steward of the project.