Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
135 lines (89 loc) · 3.99 KB

CONTRIBUTING.md

File metadata and controls

135 lines (89 loc) · 3.99 KB

Contributing to APM

Thank you for considering contributing to APM! This document outlines the process for contributing to the project.

Code of Conduct

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

How to Contribute

Reporting Bugs

Before submitting a bug report:

  1. Check the GitHub Issues to see if the bug has already been reported.
  2. Update your copy of the code to the latest version to ensure the issue hasn't been fixed.

When submitting a bug report:

  1. Use our bug report template.
  2. Include detailed steps to reproduce the bug.
  3. Describe the expected behavior and what actually happened.
  4. Include any relevant logs or error messages.

Suggesting Enhancements

Enhancement suggestions are welcome! Please:

  1. Use our feature request template.
  2. Clearly describe the enhancement and its benefits.
  3. Provide examples of how the enhancement would work.

Development Process

  1. Fork the repository.
  2. Create a new branch for your feature/fix: git checkout -b feature/your-feature-name or git checkout -b fix/issue-description.
  3. Make your changes.
  4. Run tests: uv run pytest tests/unit tests/test_console.py -x
  5. Ensure your code follows our coding style (we use Black and isort).
  6. Commit your changes with a descriptive message.
  7. Push to your fork.
  8. Submit a pull request.

Pull Request Process

  1. Fill out the PR template — describe what changed, why, and link the issue.
  2. Ensure your PR addresses only one concern (one feature, one bug fix).
  3. Include tests for new functionality.
  4. Update documentation if needed.
  5. PRs must pass all CI checks before they can be merged.

Issue Triage

Every new issue is automatically labeled needs-triage. Maintainers review incoming issues and:

  1. Accept — remove needs-triage, add accepted, and assign a milestone.
  2. Prioritize — optionally add priority/high or priority/low.
  3. Close — if it's a duplicate (duplicate) or out of scope, close with a comment explaining why.

Labels used for triage: needs-triage, accepted, needs-design, priority/high, priority/low.

Development Environment

This project uses uv to manage Python environments and dependencies:

# Clone the repository
git clone <this-repo-url>
cd apm

# Install all dependencies (creates .venv automatically)
uv sync --extra dev

Testing

We use pytest for testing with pytest-xdist for parallel execution. After completing the setup above:

# Run the unit test suite (recommended — matches CI, fast)
uv run pytest tests/unit tests/test_console.py -x

# Run a specific test file (fastest, use during development)
uv run pytest tests/unit/path/to/relevant_test.py -x

# Run the full test suite (includes integration & acceptance tests)
uv run pytest

# Run with verbose output
uv run pytest tests/unit -x -v

Tests run in parallel automatically (-n auto is configured in pyproject.toml). To force serial execution, add -n0.

If you don't have uv available, you can use a standard Python venv and pip:

# create and activate a venv (POSIX / WSL)
python -m venv .venv
source .venv/bin/activate

# install this package in editable mode and test deps
pip install -U pip
pip install -e .[dev]

# run unit tests
pytest tests/unit tests/test_console.py -x

Coding Style

This project follows:

  • PEP 8 for Python style guidelines
  • We use Black for code formatting and isort for import sorting

You can run these tools with:

uv run black .
uv run isort .

Documentation

If your changes affect how users interact with the project, update the documentation accordingly.

License

By contributing to this project, you agree that your contributions will be licensed under the project's MIT License.

Questions?

If you have any questions, feel free to open an issue or reach out to the maintainers.

Thank you for your contributions!