Contributing to GigQ¶

This guide covers the development setup and contribution process.

Code of Conduct¶

By participating in this project, you agree to adhere to our Code of Conduct. Please treat other contributors with respect and maintain a positive and inclusive environment.

Getting Started¶

Prerequisites¶

To contribute to GigQ, you'll need:

1. Python 3.10 or newer
2. Git
3. A GitHub account

Setting Up Your Development Environment¶

1. Fork the repository on GitHub.

2. Clone your fork to your local machine:

git clone https://github.com/YOUR-USERNAME/gigq.git
cd gigq

1. Create a virtual environment:

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

1. Install the package in development mode:

pip install -e .

1. Install development dependencies:

   pip install -e ".[dev]"
   

Development Workflow¶

Creating a Branch¶

Before making changes, create a branch from the main branch:

git checkout -b feature/your-feature-name

or

git checkout -b bugfix/issue-number-description

Making Changes¶

1. Make your changes to the code.
2. Add tests for any new functionality or bug fixes.
3. Ensure all tests pass:

   pytest
   

4. Check formatting:

   black --check gigq tests
   

Committing Changes¶

1. Stage your changes:

git add .

1. Commit your changes with a descriptive message:

git commit -m "Add feature: description of your feature"

1. Push your changes to your fork:

   git push origin feature/your-feature-name
   

Submitting a Pull Request¶

1. Go to the original GigQ repository on GitHub.
2. Click on "Pull Requests" and then "New Pull Request".
3. Click "compare across forks" and select your fork and branch.
4. Add a title and description for your pull request.
5. Submit the pull request.

Coding Standards¶

Python Style Guide¶

GigQ follows the PEP 8 style guide for Python code. Additionally:

• Use 4 spaces for indentation (no tabs).
• Add docstrings for all modules, classes, and functions.
• Keep line length to a maximum of 88 characters.
• Use descriptive variable names.

Docstrings¶

Use Google-style docstrings:

def function_example(param1, param2):
    """
    A brief description of what the function does.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of the return value

    Raises:
        ExceptionType: When and why this exception is raised
    """

Type Hints¶

Use type hints for function parameters and return values:

def function_with_type_hints(param1: str, param2: int) -> Dict[str, Any]:
    """
    Example function with type hints.
    """
    return {"param1": param1, "param2": param2}

Testing¶

Writing Tests¶

All new features and bug fixes should include tests. GigQ uses Python's built-in unittest framework:

import unittest
from gigq import Job, JobQueue

class TestJobQueue(unittest.TestCase):
    def setUp(self):
        # Setup code
        self.queue = JobQueue(":memory:")

    def test_submit_job(self):
        job = Job(name="test", function=lambda: None)
        job_id = self.queue.submit(job)
        self.assertIsNotNone(job_id)

    def tearDown(self):
        # Cleanup code
        pass

Running Tests¶

Run the entire test suite:

pytest

Run a specific test:

pytest tests/unit/test_job_queue.py::TestJobQueue::test_submit_job

Documentation¶

Updating Documentation¶

GigQ uses MkDocs with the Material theme for documentation. To update documentation:

1. Edit the markdown files in the docs/ directory.
2. Preview your changes locally:

   mkdocs serve
   

3. Ensure your documentation changes are included in your pull request.

Adding Examples¶

If you're adding a new feature, consider adding an example to the examples/ directory to demonstrate its usage. Make sure to update the documentation to reference your example.

Git Commit Messages¶

• Use the present tense ("Add feature" not "Added feature")
• Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
• Limit the first line to 72 characters or less
• Reference issues and pull requests after the first line

Releasing¶

The release process is handled by the project maintainers. If you're interested in helping with releases, please contact one of the maintainers.

Getting Help¶

Open an issue on GitHub if you're stuck or have questions about the contribution process.