Skip to content

Latest commit

 

History

History
95 lines (67 loc) · 2.86 KB

CONTRIBUTING.md

File metadata and controls

95 lines (67 loc) · 2.86 KB
Raw

How To Contribute

Thank you for considering contributing to anycastd! This document intends to make contribution more accessible while aligning expectations. Please don't hesitate to open issues and PRs regardless if anything is unclear.

By contributing to anycastd, you agree that your code will be licensed under the terms of the Apache-2.0 License without any additional terms or conditions.

Getting Started

To gain an overview of anycastd, please read the README.

General Guidelines

  • Contributions of all sizes are welcome, including single line grammar / typo fixes.
  • For new features, documentation and tests are a requirement.
  • Please use appropriate PR titles as we squash on merge.
  • Changes must pass CI. PRs with failing CI will be treated as drafts unless you explicitly ask for help.
  • Simplicity is a core objective of anycastd. Please open an issue before working on a new feature to discuss it.

Development Environment

Devcontainer

For users of IDEs with support for devcontainers, it's usage is recommended.

Other

Ensure you have Python 3.11 or greater with recent versions of uv and just in your environment.

Coding Standards

All tests need to pass before a PR can be merged. Using just to lint your code and run tests before creating a PR is advised to avoid being reprimanded by CI.

$ just
uv lock --locked
Resolved 54 packages in 3ms
uv run ruff check src tests
All checks passed!
uv run ruff format --check src tests
57 files already formatted
uv run mypy src
Success: no issues found in 30 source files
...

Since some integration tests use real dependencies, docker is required to run them. If docker is not available in your environment, those tests will be skipped and only run in CI.

Linting

anycastd uses ruff for uniform (black) formatting in addition to basic linting and enforcement of best practices, as well as mypy for static type checks.

Tests

  • A high code coverage should be maintained. New functionality requires new tests.

  • Write your asserts as actual == expected for convention.

    assert result == expected

  • Use the Given When Then pattern.

    # Given
expected = 42  # setup required state
# When
result = f_being_tested()  # run the code being tested
# Then
assert result == expected  # confirm expectations

    When writing more complicated tests, use spacing to distinguish the different sections.

    executor = Executor()
to_echo = "Hello, World!"

process = await executor.create_subprocess_exec(
    "echo", to_echo
)
stdout, stderr = await process.communicate()

assert stdout == to_echo.encode() + b"\n"
assert stderr == b""