Skip to content

Latest commit

 

History

History
182 lines (110 loc) · 4.47 KB

MAINTAINERS.rst

File metadata and controls

182 lines (110 loc) · 4.47 KB

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

This 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
  • Build Tool: poetry
  • Primary Dependencies: pygithub, gitpython
  • Documentation Tool: sphinx
  • Testing Tools: pytest, coverage
  • 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
$ twine check dist/*

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

  1. Update the version in pyproject.toml according to semantic versioning.
  2. Update CHANGELOG.rst.
  3. Update the version in gstore/__init__.py.
  4. Tag the version using git and push tag to GitHub.
  5. 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