NoteDiscovery/CONTRIBUTING.md

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

🚀 How to Contribute

1. Fork and Clone

git clone https://github.com/YOUR_USERNAME/notediscovery.git
cd notediscovery

2. Create a Branch

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

# 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:

git commit -m "Add dark mode toggle to settings"

6. Push and Create a Pull Request

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! ❤️