Contributing to PyNAS

We welcome contributions to PyNAS! This guide will help you get started with contributing to the project.

Getting Started

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/your-username/PyNAS.git
cd PyNAS

Create a virtual environment:

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

Install development dependencies using PDM (recommended):
```
pdm install
```
Or using pip:
```
pip install -e ".[dev]"
```

Development Setup

The project uses several tools for development:

PDM for dependency management (recommended)
pytest for testing
black for code formatting
flake8 for linting
mypy for type checking

Installing Dependencies with PDM

PDM is the recommended package manager:

pdm install

This will install all dependencies including development tools.

Installing with pip (Alternative)

If you don’t have PDM installed:

pip install pdm

Then install the project dependencies:

pdm install

Code Style

We follow PEP 8 and use several tools to maintain code quality:

Formatting

We use black for code formatting:

black pynas/
black tests/

Linting

We use flake8 for linting:

flake8 pynas/
flake8 tests/

Type Checking

We use mypy for type checking:

mypy pynas/

Running Tests

We use pytest for testing. Run the test suite with:

pytest

Run tests with coverage:

pytest --cov=pynas

Run specific test files:

pytest tests/test_population.py

Testing Guidelines

Write tests for all new functionality
Maintain high test coverage (>90%)
Use descriptive test names
Follow the AAA pattern (Arrange, Act, Assert)
Mock external dependencies

Example test structure:

def test_population_initialization():
    """Test that Population initializes correctly with given parameters."""
    # Arrange
    config = PopulationConfig(
        population_size=10,
        generations=5
    )

    # Act
    population = Population(config)

    # Assert
    assert len(population.individuals) == 10
    assert population.generation == 0

Documentation

Documentation is built using Sphinx. To build the documentation locally:

cd docs/
make html

The documentation will be available in docs/build/html/.

Documentation Guidelines

Use Google-style docstrings
Include type hints in function signatures
Provide examples in docstrings where appropriate
Update documentation when adding new features

Example docstring:

def evolve_population(self, generations: int) -> Population:
    """Evolve the population for a specified number of generations.

    Args:
        generations: Number of generations to evolve.

    Returns:
        The evolved population.

    Raises:
        ValueError: If generations is not positive.

    Example:
        >>> population = Population(config)
        >>> evolved = population.evolve_population(10)
        >>> print(f"Generation: {evolved.generation}")
    """

Contributing Workflow

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes
- Write code following the style guidelines
- Add tests for new functionality
- Update documentation as needed

Run quality checks:

# Format code
black pynas/ tests/

# Check linting
flake8 pynas/ tests/

# Run type checking
mypy pynas/

# Run tests
pytest

Commit your changes:

git add .
git commit -m "Add feature: brief description"

Push to your fork:

git push origin feature/your-feature-name

Create a Pull Request on GitHub

Pull Request Guidelines

Use descriptive titles that explain what the PR does
Provide a detailed description including:
- What changes were made
- Why the changes were necessary
- Any breaking changes
- How to test the changes
Link to relevant issues using keywords like “Fixes #123”
Ensure all CI checks pass
Request review from maintainers

Example PR description:

## Summary

This PR adds support for custom fitness functions in the optimization module.

## Changes

- Added `CustomFitnessFunction` class
- Updated `Optimizer` to accept custom fitness functions
- Added comprehensive tests
- Updated documentation

## Testing

- All existing tests pass
- Added new tests for custom fitness functions
- Manual testing with example custom function

Fixes #45

Code Review Process

All contributions go through code review:

Automated checks run on all PRs (tests, linting, type checking)
Manual review by maintainers
Address feedback if requested
Merge once approved

What We Look For

Correctness: Does the code work as intended?
Testing: Are there adequate tests?
Documentation: Is the code well-documented?
Style: Does it follow our coding standards?
Performance: Are there any performance implications?

Issue Reporting

When reporting issues, please include:

Clear description of the problem
Steps to reproduce the issue
Expected vs actual behavior
Environment information (OS, Python version, etc.)
Code snippets or minimal examples

Use the issue templates when available.

Feature Requests

For feature requests, please:

Search existing issues to avoid duplicates
Provide clear use cases for the feature
Explain the expected behavior
Consider implementation complexity

Types of Contributions

We welcome various types of contributions:

Code Contributions

Bug fixes
New features
Performance improvements
Code refactoring

Documentation

API documentation improvements
Tutorial additions
Example code
README updates

Testing

Additional test cases
Test infrastructure improvements
Performance benchmarks

Community

Answering questions in issues
Reviewing pull requests
Participating in discussions

Release Process

Releases follow semantic versioning (SemVer):

Major version (X.0.0): Breaking changes
Minor version (X.Y.0): New features, backward compatible
Patch version (X.Y.Z): Bug fixes, backward compatible

License

By contributing to PyNAS, you agree that your contributions will be licensed under the project’s license.

Getting Help

If you need help:

Check the documentation first
Search existing issues on GitHub
Create a new issue for questions
Join discussions in the community

Thank you for contributing to PyNAS! 🚀