From 3c8db87f964bb41066664599e1f4651c0f318026 Mon Sep 17 00:00:00 2001 From: Gamosoft Date: Sat, 22 Nov 2025 20:14:25 +0100 Subject: [PATCH] added contributing guide --- CONTRIBUTING.md | 220 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..022983e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,220 @@ +# Contributing to NoteDiscovery + +Thank you for your interest in contributing to NoteDiscovery! 🎉 + +This document provides guidelines and expectations for contributing to the project. Please read through this before submitting pull requests or opening issues. + +## 🤝 Our Philosophy + +NoteDiscovery is designed to be: +- **Lightweight** - Fast, minimal dependencies, quick to deploy +- **Simple** - Easy to understand, maintain, and customize +- **Self-hosted** - Complete control over your data, no external dependencies +- **Privacy-focused** - Your notes stay on your server + +When considering contributions, we prioritize: +1. Maintaining simplicity and ease of use +2. Keeping the codebase maintainable +3. Preserving the lightweight nature of the application +4. Staying true to the self-hosted, privacy-first mission + +## 📋 Before You Start + +### Discuss Major Changes First + +**Before submitting a pull request for a major feature or significant change, please:** + +1. **Open an issue first** to discuss the idea +2. **Wait for feedback** from maintainers +3. **Get approval** before investing time in implementation + +This helps ensure that: +- Your effort isn't wasted if the feature doesn't align with project goals +- We can discuss the best approach together +- Multiple people aren't working on the same thing +- The feature fits well with the existing architecture + +### What Counts as a "Major Change"? + +- New features that add significant functionality +- Changes to core architecture or data models +- New dependencies or significant changes to existing ones +- UI/UX overhauls or major design changes +- Changes to the plugin or theme system architecture +- Breaking changes to the API + +### What Can Be Submitted Directly? + +- Bug fixes +- Documentation improvements +- Small UI tweaks and improvements +- Performance optimizations +- Code quality improvements (refactoring, cleanup) +- New themes (following existing theme structure) +- New plugins (following existing plugin structure) +- Translation/localization updates + +## 🚀 How to Contribute + +### 1. Fork and Clone + +```bash +git clone https://github.com/YOUR_USERNAME/notediscovery.git +cd notediscovery +``` + +### 2. Create a Branch + +```bash +git checkout -b feature/your-feature-name +# or +git checkout -b fix/your-bug-fix +``` + +### 3. Make Your Changes + +- Follow the existing code style +- Write clear, readable code +- Add comments for complex logic +- Test your changes locally +- Update documentation if needed + +### 4. Test Your Changes + +```bash +# Install dependencies +pip install -r requirements.txt + +# Run the application +python run.py + +# Or use Docker +docker-compose up +``` + +### 5. Commit Your Changes + +Write clear, descriptive commit messages: + +```bash +git commit -m "Add dark mode toggle to settings" +``` + +### 6. Push and Create a Pull Request + +```bash +git push origin feature/your-feature-name +``` + +Then create a pull request on GitHub with: +- A clear title and description +- Reference to any related issues +- Screenshots (if UI changes) +- Testing notes + +## 📝 Code Style Guidelines + +### Python + +- Follow PEP 8 style guide +- Use type hints where appropriate +- Keep functions focused and small +- Add docstrings for public functions/classes + +### JavaScript + +- Use modern ES6+ syntax +- Keep functions focused and small +- Comment complex logic + +### General + +- Keep code simple and readable +- Avoid over-engineering +- Prefer explicit over implicit +- Write self-documenting code when possible + +## 🎨 Contributing Themes + +Themes should: +- Follow the existing theme structure (see `themes/` directory) +- Be well-tested across different content types +- Include proper contrast ratios for accessibility +- Be named descriptively (e.g., `ocean-blue.css`, not `theme1.css`) + +## 🔌 Contributing Plugins + +Plugins should: +- Follow the existing plugin structure (see `plugins/` directory) +- Include documentation in `documentation/PLUGINS.md` +- Be optional and not break core functionality if disabled +- Follow the plugin configuration format + +## 📚 Contributing Documentation + +Documentation improvements are always welcome! Please: +- Keep language clear and concise +- Use examples where helpful +- Update related documentation when making changes +- Check for typos and grammar + +## ❓ When PRs Might Not Be Accepted + +Even if your idea is great, a PR might not be accepted if: + +1. **It doesn't align with project goals** - We aim to keep NoteDiscovery lightweight and simple. Features that add significant complexity or dependencies may not fit. + +2. **It wasn't discussed first** - Major changes should be discussed in an issue before implementation. + +3. **It conflicts with existing work** - Sometimes we're already working on similar features or have different plans. + +4. **It's too niche** - Features that only benefit a very small subset of users might be better as plugins. + +5. **It adds unnecessary complexity** - We prefer simple, maintainable solutions over complex ones. + +6. **It breaks backward compatibility** - Without a very good reason, we try to maintain compatibility. + +### What to Do If Your PR Isn't Accepted + +**Don't take it personally!** Here are some options: + +1. **Fork and maintain your own version** - That's the beauty of open source! You can add any features you want in your fork. + +2. **Create a plugin** - Many features can be implemented as plugins without changing core code. + +3. **Revisit later** - Project priorities change. What doesn't fit now might fit later. + +4. **Discuss alternatives** - We're happy to discuss if there's a simpler way to achieve your goal. + +## 🐛 Reporting Bugs + +When reporting bugs, please include: +- Steps to reproduce +- Expected behavior +- Actual behavior +- Environment (OS, Python version, Docker, etc.) +- Error messages or logs +- Screenshots if applicable + +## 💡 Suggesting Features + +When suggesting features: +- Explain the problem you're trying to solve +- Describe your proposed solution +- Discuss alternatives you've considered +- Explain who would benefit from this feature + +## 📞 Getting Help + +- Open an issue for bugs or feature requests +- Check existing issues and documentation first +- Be patient and respectful in discussions + +## 🙏 Thank You! + +Your contributions, whether code, documentation, bug reports, or feature suggestions, are greatly appreciated. Even if a specific PR isn't merged, your ideas and feedback help make NoteDiscovery better. + +--- + +**Remember**: The goal is to build something useful together while keeping the project maintainable and true to its core values. Thank you for understanding! ❤️ +