Maintainers’ Guide¶

This document outlines essential guidelines for maintaining the gstore project. It provides instructions for testing, building, and deploying the package, as well as managing CI workflows.

Overview¶

The gstore project is a CLI tool for synchronizing GitHub repositories. It is managed via poetry and adheres to modern Python packaging standards. This guide assumes familiarity with GitHub Actions, poetry, and common Python development workflows.

Key configurations:

Python Versions Supported: 3.9, 3.10, 3.11, 3.12
Build Tool: poetry
Primary Dependencies: pygithub, gitpython
Documentation Tool: sphinx
Linting Tools: flake8, pylint

Testing the Project¶

Unit tests and coverage reporting are managed using pytest and coverage.

Running Tests Locally¶

Install dependencies:

$ poetry install --with=testing

Execute tests:

$ coverage run -m pytest ./gstore ./tests
$ coverage combine
$ coverage report

CI Workflow¶

Tests are executed automatically on supported platforms and Python versions. See the configuration in .github/workflows/ci.yml (ci).

Building the Package¶

The gstore package is distributed in wheel and sdist formats.

Local Build¶

Install build dependencies:

$ poetry install --only=build

Build the package:

$ poetry build

CI Workflow¶

The build workflow in .github/workflows/build.yml ensures the package is built and verified across multiple Python versions (build).

Documentation Management¶

Documentation is written using sphinx and built into HTML and other formats.

Building Documentation Locally¶

Install documentation dependencies:

$ poetry install --only=docs

Build the documentation:

$ sphinx-build --nitpicky --show-traceback --fail-on-warning --builder html docs docs/_build/html

Validate doctests:

$ sphinx-build --builder doctest docs docs/_build/doctest
$ python -m doctest README.rst

CI Workflow¶

The docs workflow automatically builds and validates documentation on pushes and pull requests. See .github/workflows/docs.yml (docs).

Linting and Code Quality Checks¶

Code quality is enforced using flake8 and pylint.

Running Locally¶

Install linting dependencies:

$ poetry install --with=testing

Execute linting:

$ flake8 ./
$ pylint ./gstore

CI Workflow¶

The lint workflow in .github/workflows/lint.yml ensures all pushes and pull requests meet quality standards (lint).

Release Process¶

The release process involves version tagging and package publishing to PyPI.

Steps for Release¶

Update the version in pyproject.toml according to semantic versioning.
Update CHANGELOG.rst.
Update the version in gstore/__init__.py.
Tag the version using git and push tag to GitHub.
Build and publish the package:

$ poetry build
$ poetry publish

CI Workflow¶

The build workflow ensures the package is valid before publishing. Tags matching the pattern vX.Y.Z trigger additional checks (build).

Continuous Integration and Deployment¶

CI/CD is managed via GitHub Actions, with workflows for:

Testing: Ensures functionality and compatibility across platforms.
Linting: Maintains code quality.
Documentation: Validates and builds project documentation.
Building: Verifies the package’s integrity.

Useful CI Commands¶

Validate the pyproject.toml file:

$ poetry check

Test installation of the built package:

$ pip install dist/*.whl
$ gstore --version