docs/7-DEVELOPMENT/maintainer-guide.md
This guide is for project maintainers to help manage contributions effectively while maintaining project quality and vision.
1. Initial Triage (within 24-48 hours)
Add appropriate labels:
bug, enhancement, documentation, etc.good first issue for beginner-friendly tasksneeds-triage until reviewedhelp wanted if you'd welcome community contributionsQuick assessment:
2. Initial Response
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?
[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:
4. Issue Assignment
If the contributor checked "I am a developer and would like to work on this":
For Accepted Issues:
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:
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:
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.
Priority:
priority: critical - Security issues, data loss bugspriority: high - Major functionality brokenpriority: medium - Annoying bugs, useful featurespriority: low - Nice to have, edge casesStatus:
needs-triage - Not yet reviewed by maintainerneeds-info - Waiting for more information from reporterneeds-discussion - Requires community/team discussionready - Approved and ready to be worked onin-progress - Someone is actively working on thisblocked - Cannot proceed due to external dependencyType:
bug - Something is brokenenhancement - New feature or improvementdocumentation - Documentation improvementsquestion - General questionsrefactor - Code cleanup/restructuringDifficulty:
good first issue - Good for newcomershelp wanted - Community contributions welcomeadvanced - Requires deep codebase knowledgeBefore diving into code:
Red Flags (may require closing PR):
1. High-Level Review
2. Code Quality Review
Python:
TypeScript/Frontend:
3. Testing Review
4. Documentation Review
Positive Feedback (important!):
Thanks for this PR! I really like [specific thing they did well].
[Feedback on what needs to change]
Requesting Changes:
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:
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?
Situation: Contributor wrote quality code, but solved the problem in a way that doesn't fit our architecture.
Response:
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!
Situation: Contributor submitted PR without going through issue approval process.
Response:
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.
Situation: Well-intentioned feature that doesn't fit project goals.
Response:
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 or open issues for other ways to contribute!
Situation: You requested changes, but contributor hasn't responded in 2+ weeks.
After 2 weeks:
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:
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:
help wanted label to the issueSituation: PR introduces breaking changes that weren't discussed.
Response:
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.
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
- Help wanted issues
- Our roadmap
Thanks again for your interest in Open Notebook!
We're closing this issue due to inactivity. If this is still relevant, feel free to reopen it with updated information.
Thanks!
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.
Merged!
Thank you so much for this contribution, @username! [Specific thing they did well].
This will be included in the next release.
Ask yourself:
If you're unsure, it's perfectly fine to:
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.