Contribution Guidelines

Great that you are ready to contribute! Development happens on GitHub: sosw/sosw.

Release cycle

  • We follow both the Semantic Versioning pattern and PEP440 recommendations where they comply.

  • Branches for planned staging versions follow the pattern X_Y_Z (Major_Minor_Micro), e.g. 3_0_1.

  • Make your pull request against the closest staging branch — the one with the smallest version after the latest release, of either the current or the next Minor.

  • Pushes to staging branches automatically publish release candidates to TestPyPI.

  • Merges to master are automatically packaged and published to PyPI — master is the release.

  • Keep your branch up to date with the branch you are making a PR to.

Example: if the latest released version on PyPI is 3.4.0, the open staging branches are 3_4_1 and 3_5_0. A bugfix PR goes to 3_4_1; a new feature to 3_5_0.

Development setup

git clone https://github.com/YOUR_FORK/sosw.git && cd sosw

# Either pipenv:
pipenv sync --dev && pipenv shell

# ... or plain pip in any virtual environment:
pip install boto3 pytest pytest-cov -r docs/requirements.txt

The package itself depends only on boto3; everything else is for tests and docs. All metadata lives in pyproject.toml (there is no setup.py).

Code style

We follow PEP8 with the repository-specific details below. CI and review enforce them.

  • Maximum line width: 120 characters.

  • Both classes and functions/methods are padded with two empty lines.

  • Dictionary values are vertically aligned.

  • Single quotes for regular strings and keys; double quotes for logging and exception messages.

  • Logging uses % formatting, never f-strings: logger.info("Got %s", thing).

  • Imports at the top of the module, grouped: full core, full custom, partial core, partial custom; alphabetical within each group.

  • No try/except: pass around business logic — fail fast and loud.

  • Data fields are snake_case. Every file ends with exactly one trailing newline.

  • Docstrings in Sphinx-friendly reST (:param x:, :rtype:) — see the Documentation Convention.

Tests

The unit suite is explicitly registered in sosw/test/suite_unit.py: every new test file must be imported there and added to the suite, following the existing pattern — orphan test files do not run in CI.

pytest sosw/test/suite_unit.py

Rules of the suite:

  • Pure unit tests only: mock boto3 (patch('boto3.client'), patch.object(Processor, 'get_config')) — no network, no real AWS. The whole suite runs in a few seconds.

  • Set os.environ['STAGE'] = 'test' and os.environ['autotest'] = 'True' before importing sosw modules in a test file.

  • Test files live in sosw/test/unit/ and sosw/components/test/unit/.

Coverage bar: 100%. CI runs the suite with --cov=sosw and fails below the enforced threshold (.coveragerc excludes the test directories themselves):

pytest sosw/test/suite_unit.py --cov=sosw --cov-report=term-missing
Test Coverage

Continuous integration

GitHub Workflows run on every pull request:

  • Tests (run-unittests.yml) — the unit suite on a Python 3.12 / 3.13 / 3.14 matrix (all the supported versions), plus a coverage job enforcing the threshold on Python 3.14.

  • Docs (docs-builder-action.yaml) — strict Sphinx build; any warning fails the build.

  • TestPyPI (publish-to-test-pypi.yml) — publishes release candidates from X_Y_Z staging branches.

  • PyPI (publish-to-pypi.yml) — publishes from master.

  • Publish Docs (publish-docs.yml) — publishes the built docs to this documentation site automatically on every push to master (OIDC-assumed AWS role, no static keys); a manual dispatch offers a dry-run mode.

Building the docs

pip install -r docs/requirements.txt
python -m sphinx -W -a -b html docs sosw-rtd

# View at http://localhost:8000
(cd sosw-rtd && python -m http.server)

The -W flag mirrors CI: warnings are errors. Fix them, do not silence them.

Pull request checklist

  • Your branch is up to date with the staging branch you target.

  • pytest sosw/test/suite_unit.py passes, new code is covered, new test files are registered in suite_unit.py.

  • python -m sphinx -W -a -b html docs sosw-rtd passes if you touched docs or docstrings.

  • The code follows the style rules above.

  • Open the PR against the appropriate X_Y_Z staging branch (not master).

Guidelines for creating PRs from forks are in the GitHub documentation.