allaun/Research-Stack
1
0
Fork 0
mirror of https://github.com/allaunthefox/Research-Stack.git synced 2026-07-31 03:05:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
Research-Stack/4-Infrastructure/NoDupeLabs/docs/guides/CONTRIBUTING.md

8 KiB
Raw Blame History

Contributing to NoDupeLabs

Thank you for your interest in contributing to NoDupeLabs! This document provides guidelines for contributing to the project.

Table of Contents

Code of Conduct

This project adheres to a code of conduct that promotes a welcoming and inclusive environment. By participating, you agree to uphold this code.

How to Contribute

Ways to Contribute

  1. Code Contributions: Implement new features, fix bugs, improve performance
  2. Documentation: Improve existing documentation, write tutorials, update API docs
  3. Testing: Write tests, improve test coverage, fix flaky tests
  4. Bug Reports: Report issues, provide reproduction steps
  5. Feature Requests: Suggest new features, provide use cases
  6. Code Reviews: Review pull requests, provide constructive feedback

Getting Started

  1. Fork the repository
  2. Clone your fork
  3. Create a feature branch
  4. Make your changes
  5. Test thoroughly
  6. Submit a pull request

Development Setup

Prerequisites

  • Python 3.9+
  • Git
  • pip
  • Virtual environment (recommended)

Setup Instructions

# Clone the repository
git clone https://github.com/allaunthefox/NoDupeLabs.git
cd NoDupeLabs

# Create and activate virtual environment (PEP 668 compliant)
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate  # Windows

# Verify you're in the virtual environment
# (pip will now install to .venv, not system Python)
which pip  # Should show .venv/bin/pip

# Install package with dev dependencies (includes pytest, hypothesis, coverage)
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Note: The --break-system-packages flag is NOT needed when using a virtual environment. The venv module creates an isolated environment that bypasses PEP 668 externally-managed restrictions.

Running the Project

# Run the main application
python -m nodupe.core.main --help

# Run tests
pytest

# Run with coverage
pytest --cov=nodupe --cov-report=html

Coding Standards

Python Style

  • Follow PEP 8 style guide
  • Use 4 spaces for indentation
  • Maximum line length: 120 characters
  • Use descriptive variable and function names
  • Follow snake_case naming convention

Type Annotations

  • Use Python type hints for all functions and methods
  • Use typing module for complex types
  • Ensure all code passes mypy strict type checking

Code Formatting

  • Use black for code formatting
  • Use isort for import sorting
  • Configure your editor to run these tools automatically

Documentation

  • Use Google-style docstrings
  • Document all public functions, classes, and methods
  • Include examples where appropriate
  • Keep documentation up-to-date with code changes

Testing Requirements

Test Coverage

  • Minimum 80% line coverage for new code
  • Minimum 70% branch coverage for new code
  • All tests must pass before submitting a pull request
  • Write unit tests, integration tests, and end-to-end tests as appropriate

Test Structure

  • Unit tests in tests/core/ for core functionality
  • Integration tests in tests/integration/ for system-level testing
  • Plugin tests in tests/plugins/ for plugin-specific functionality
  • Use pytest framework with appropriate markers

Test Examples

def test_example_function():
    """Test example function with various inputs."""
    # Test normal case
    result = example_function("input")
    assert result == "expected_output"

    # Test edge cases
    with pytest.raises(ValueError):
        example_function("invalid_input")

Documentation Standards

Documentation Structure

  • Use Markdown format for all documentation
  • Follow the existing documentation structure and style
  • Use clear, concise language
  • Include code examples where helpful
  • Keep documentation up-to-date with implementation

Documentation Types

  1. API Documentation: Auto-generated from docstrings
  2. User Guides: Step-by-step instructions for users
  3. Developer Guides: Technical documentation for contributors
  4. Architecture Documentation: System design and patterns
  5. Release Notes: Changes and updates for each release

Documentation Updates

  • Update documentation when adding new features
  • Update documentation when changing existing functionality
  • Update documentation when fixing bugs that affect usage
  • Keep documentation in sync with code changes

Pull Request Process

Before Submitting

  1. Ensure all tests pass
  2. Ensure code follows style guidelines
  3. Ensure type checking passes
  4. Update documentation as needed
  5. Add tests for new functionality
  6. Update changelog if significant changes

Submitting a Pull Request

  1. Push your changes to your fork
  2. Open a pull request to the main repository
  3. Provide a clear title and description
  4. Reference any related issues
  5. Include screenshots if UI changes
  6. Request review from maintainers

Pull Request Requirements

  • All tests must pass
  • Code must follow style guidelines
  • Type checking must pass
  • Documentation must be updated
  • Tests must be added for new functionality
  • Coverage must not decrease
  • At least one approval from maintainers

Issue Reporting

Bug Reports

When reporting bugs, please include:

  1. Clear description of the issue
  2. Steps to reproduce
  3. Expected behavior
  4. Actual behavior
  5. Environment information (OS, Python version, etc.)
  6. Screenshots if applicable
  7. Log files if applicable

Feature Requests

When requesting features, please include:

  1. Clear description of the feature
  2. Use cases and benefits
  3. Proposed implementation (if known)
  4. Examples or mockups (if applicable)
  5. Related issues or discussions

Community Guidelines

Communication

  • Be respectful and professional
  • Use inclusive language
  • Provide constructive feedback
  • Be open to different perspectives
  • Follow the project's code of conduct

Collaboration

  • Work together on issues and features
  • Help review pull requests
  • Share knowledge and expertise
  • Mentor new contributors
  • Participate in discussions

Recognition

  • Contributions are valued and appreciated
  • Significant contributors may be invited to join the core team
  • Contributions are recognized in release notes
  • Contributors are listed in project documentation

Development Workflow

Branching Strategy

  • main: Stable production-ready code
  • develop: Integration branch for features
  • feature/*: Feature development branches
  • bugfix/*: Bug fix branches
  • release/*: Release preparation branches

Commit Messages

  • Use clear, descriptive commit messages
  • Follow conventional commit format
  • Reference issues when applicable
  • Keep commits focused and atomic

Code Reviews

  • All changes require code review
  • Reviews should be constructive and helpful
  • Address review comments promptly
  • Multiple iterations may be needed
  • Final approval from maintainers required

Getting Help

Resources

  • Project documentation
  • Issue tracker
  • Discussion forums
  • Community chat
  • Developer guides

Support

  • Check existing issues before reporting
  • Provide detailed information when asking for help
  • Be patient with responses
  • Help others when you can

License

By contributing to NoDupeLabs, you agree that your contributions will be licensed under the Apache 2.0 license.

Thank you for contributing to NoDupeLabs! Your contributions help make this project better for everyone.

For questions or additional guidance, please refer to the project documentation or contact the maintainers.