Contributing

Contributing to githubauthlib

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

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

1. Fork the repository

2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/githubauthlib.git

3. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # Linux/macOS
   venv\Scripts\activate     # Windows

4. Install development dependencies:

   pip install -r requirements.txt

Development Workflow

1. Create a new branch:

   git checkout -b feature/your-feature-name

2. Make your changes:

   • Write tests for new functionality
   • Update documentation as needed
   • Follow the coding style guidelines

3. Run tests:

   pytest tests/

4. Run code formatting:

   black .
   isort .

5. Run type checking:

   mypy githubauthlib

6. Commit your changes:

   git add .
   git commit -m "feat: Add new feature"

7. Push to your fork:

   git push origin feature/your-feature-name

8. Create a Pull Request

Coding Style Guidelines

• Follow PEP 8 style guide
• Use type hints for all function parameters and return values
• Write docstrings for all public functions and classes
• Keep functions focused and single-purpose
• Use descriptive variable names

Example Function Style

from typing import Optional

def process_data(input_data: str, max_length: Optional[int] = None) -> list[str]:
    """
    Process the input data and return a list of results.

    Args:
        input_data: The data to process
        max_length: Optional maximum length for results

    Returns:
        List of processed strings

    Raises:
        ValueError: If input_data is empty
    """
    if not input_data:
        raise ValueError("Input data cannot be empty")
    
    # Implementation
    return []

Testing Guidelines

1. Write tests for all new functionality
2. Maintain test coverage above 90%
3. Use pytest fixtures for common setup
4. Mock external dependencies
5. Test edge cases and error conditions

Example Test

import pytest
from githubauthlib import get_github_token, GitHubAuthError

def test_get_github_token_success(mock_keychain):
    # Arrange
    mock_keychain.return_value = "valid_token"
    
    # Act
    token = get_github_token()
    
    # Assert
    assert token == "valid_token"

def test_get_github_token_failure(mock_keychain):
    # Arrange
    mock_keychain.side_effect = GitHubAuthError("Failed to access keychain")
    
    # Act & Assert
    with pytest.raises(GitHubAuthError):
        get_github_token()

Documentation Guidelines

1. Update docstrings for any modified functions
2. Keep the README.md up to date
3. Update the wiki for significant changes
4. Include code examples for new features

Commit Message Guidelines

Follow the Conventional Commits specification:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test updates
• chore: Maintenance tasks

Example:

feat: Add Windows credential manager support

- Implement Windows token retrieval
- Add tests for Windows platform
- Update documentation

Pull Request Process

1. Update the README.md with details of changes
2. Update the documentation
3. Add tests for new functionality
4. Ensure all tests pass
5. Update the version number if applicable
6. Request review from maintainers

Release Process

1. Update version in __init__.py
2. Update CHANGELOG.md
3. Create a new release on GitHub
4. Build and upload to PyPI

Getting Help

• Create an issue for bugs or feature requests
• Join the discussion in GitHub Discussions
• Contact the maintainers

Project Structure

githubauthlib/
├── .git/
├── .gitignore
├── README.md
├── LICENSE
├── setup.py
├── requirements.txt
├── githubauthlib/
│   ├── __init__.py
│   └── github_auth.py
├── tests/
│   ├── __init__.py
│   └── test_github_auth.py
└── docs/
    ├── conf.py
    └── index.rst

Additional Resources

• Python Packaging User Guide
• Pytest Documentation
• Type Hints Documentation
• Black Code Style
• isort Import Sorting