builderadmin
/
NoteDiscovery
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity
NoteDiscovery/CONTRIBUTING.md

6.4 KiB
Raw Blame History

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

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