Maintenance Guidelines

Welcome to the Maintainer’s Guide for Dijkstra-Edu. As a maintainer, you are a mentor, a community builder, and a steward of our educational mission.

The Maintainer’s Mindset

In Dijkstra-Edu, we prioritize learning and growth over perfection. Our goal is to create a safe space where students and beginners can contribute without fear of judgment.

Be Encouraging: Always start reviews with positive feedback.
Explain the “Why”: Don’t just point out errors; explain the reasoning behind a suggested change.
Patience is Key: Contributors may be new to Git, GitHub, or the technology stack. Guide them through the process.
Lead by Example: Write clean code, maintain clear documentation, and communicate respectfully.

Issue Management

Effective issue management keeps the project organized and helps contributors find work that matches their skill level.

Triaging New Issues

Verify: Ensure the issue is reproducible and clearly described.
Clarify: If information is missing, ask for it politely using an issue template if available.
Categorize: Add appropriate labels to help organize the backlog.

Essential Labels

bug: Something isn’t working as intended.
enhancement: A new feature or improvement.
documentation: Changes to docs or guides.
good first issue: Ideal for beginners; well-defined and relatively small.
help wanted: Open for anyone to pick up.
on hold: Waiting for external factors or further discussion.

Pull Request (PR) Reviews

Reviews are our primary teaching tool. Aim for a balance between maintaining high standards and encouraging contributors.

Review Checklist

Functionality: Does the code do what it’s supposed to do?
Readability: Is the code easy to understand for a newcomer?
Consistency: Does it follow the project’s coding style and file structure?
Documentation: Are new features or changes reflected in the documentation?
Testing: If applicable, are there tests? Do existing tests pass?

Best Practices for Feedback

Use Suggestions: Use GitHub’s “Suggested Changes” feature for minor fixes.
Group Comments: Use PR reviews to group multiple comments into one notification.
Avoid Nitpicking: Focus on logic and architecture. If there are many style issues, point to a style guide or provide a general comment rather than commenting on every line.
The “Merge” Policy: Only merge when CI checks pass and at least one other maintainer (or a senior maintainer) has approved, unless it’s a critical fix.

Repository Health

Maintenance is an ongoing process of keeping the “living room” clean.

Dependency Management: Monitor and update dependencies regularly. Use tools like Dependabot.
Changelog: Maintain a clear CHANGELOG.md or use GitHub Releases to document what has changed.
Security: Promptly address security vulnerabilities flagged by GitHub or other tools.
Documentation Sync: Ensure that as the code evolves, these guidelines and the contributor docs stay up to date.

Community & Communication

Code of Conduct: Enforce the Code of Conduct strictly but fairly.
Inclusivity: Avoid jargon where possible.
Recognition: Publicly thank contributors for their help. A simple “Thanks for the PR!” goes a long way.

Detailed Guides

For a deeper dive into specific maintenance workflows, see: