added contributing guide
This commit is contained in:
Gamosoft
parent
6b2ca6a8de
commit
3c8db87f96
|
|
@ -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! ❤️
|
||||
|
||||
Loading…
Reference in New Issue