Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
308 lines (221 loc) · 7.63 KB

CONTRIBUTING.md

File metadata and controls

308 lines (221 loc) · 7.63 KB
Raw

Contributing to Custom Functions

Thank you for your interest in contributing to Custom Functions! 🎉

This document provides guidelines and instructions for contributing. Please take a moment to read through it before making your first contribution.

Table of Contents

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. Please read it before contributing.

Getting Started

Prerequisites

  • Python 3.12 or higher
  • pip (Python package manager)
  • Git

Development Setup

  1. Fork the Repository

    • Click the "Fork" button at the top right of the repository page
    • Clone your fork locally:
    git clone https://github.com/YOUR_USERNAME/My_simple_functions.git
cd My_simple_functions

  2. Set Up Remote Upstream

    git remote add upstream https://github.com/coderooz/My_simple_functions.git

  3. Create a Virtual Environment

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  4. Install Dependencies

    pip install -e ".[dev]"
pip install flake8 black isort pytest pytest-cov

  5. Create a Branch

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

How to Contribute

Types of Contributions

We welcome various types of contributions:

  • 🐛 Bug Fixes: Fix issues reported in the issue tracker
  • ✨ New Features: Add new functionality or handlers
  • 📝 Documentation: Improve README, docstrings, or comments
  • 🧪 Tests: Add or improve test coverage
  • ⚡ Performance: Optimize existing code
  • 🔧 Refactoring: Improve code structure without changing behavior
  • 🔒 Security: Fix security vulnerabilities

Finding Issues to Work On

  • Look for issues labeled good first issue for beginner-friendly tasks
  • Check help wanted for areas where we need assistance
  • Always comment on an issue before starting work to avoid duplicate efforts

Pull Request Process

  1. Ensure your code follows the coding standards (see below)
  2. Add or update tests for your changes
  3. Update documentation if necessary
  4. Run the test suite and ensure all tests pass
  5. Update CHANGELOG.md with your changes
  6. Submit a Pull Request using the PR template

PR Checklist

  • Code follows project style guidelines
  • Self-review completed
  • Code is commented where necessary
  • Documentation updated
  • No new warnings generated
  • Tests added/updated and passing
  • CHANGELOG.md updated

Review Process

  • Project maintainers will review your PR
  • Address any requested changes
  • Once approved, a maintainer will merge your PR

Coding Standards

We use the following tools to maintain code quality:

  • Black: Code formatter
  • isort: Import sorter
  • flake8: Linter
  • mypy: Type checker (optional)

Running Formatters and Linters

# Format code with Black
black .

# Sort imports with isort
isort .

# Run flake8 linter
flake8 .

# Run all checks
black . && isort . && flake8 .

Python Style Guidelines

  • Follow PEP 8 style guide
  • Use type hints where possible
  • Write descriptive variable and function names
  • Keep functions focused and single-purpose
  • Maximum line length: 120 characters

Example Function Structure

def example_function(param1: str, param2: int = 10) -> dict:
    """Brief description of what the function does.
    
    Args:
        param1: Description of param1
        param2: Description of param2 (default: 10)
    
    Returns:
        Description of return value
    
    Raises:
        ValueError: When param1 is empty
    """
    if not param1:
        raise ValueError("param1 cannot be empty")
    
    # Implementation
    result = {"key": param1, "count": param2}
    return result

Testing Guidelines

Running Tests

# Run all tests
pytest

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

# Run specific test file
pytest tests/test_datahandler.py

# Run with verbose output
pytest -v

Writing Tests

  • Place tests in the tests/ directory
  • Name test files as test_<module_name>.py
  • Use descriptive test function names: test_<function>_<scenario>
  • Test both normal cases and edge cases
  • Mock external dependencies when appropriate

Example Test

import pytest
from custom_functions.DataHandler import DataHandler

def test_timestamp_returns_string():
    """Test that timestamp returns a formatted string."""
    result = DataHandler.timestamp()
    assert isinstance(result, str)

def test_timestamp_custom_format():
    """Test timestamp with custom format."""
    result = DataHandler.timestamp(format="%Y-%m-%d")
    assert len(result) == 10

Documentation

Good documentation is essential. When contributing:

  • Update README.md if adding new features
  • Add docstrings to all public functions and classes
  • Update inline comments for complex logic
  • Include usage examples in docstrings

Docstring Format

We use Google-style docstrings:

def my_function(param1: str) -> bool:
    """One-line summary.
    
    Detailed description of what the function does,
    its behavior, and any important notes.
    
    Args:
        param1: Description of parameter
        
    Returns:
        Description of return value
        
    Raises:
        ExceptionType: When condition occurs
    """

Commit Messages

We follow Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples

feat(DataHandler): add JSON parsing utility
fix(FileHandler): handle empty file edge case
docs: update README with new installation instructions
test(DbHandler): add tests for createTb method

Issue Reporting

Before Creating an Issue

  1. Check existing issues to avoid duplicates
  2. Use the appropriate issue template
  3. Provide as much context as possible

Issue Templates

Community

Recognition

All contributors will be recognized in:

  • The CHANGELOG.md
  • The README.md contributors section
  • GitHub's contributors page

Thank you for contributing to Custom Functions! 🙏

Author: Ranit Saha
Website: https://coderooz.in