Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
180 lines (126 loc) · 7.26 KB

CONTRIBUTING.md

File metadata and controls

180 lines (126 loc) · 7.26 KB
Raw

Contributing to Poxy

Firstly: thanks! Any help is greatly appreciated.

For most situations the easiest way for you to contribute is to simply let me know what's going on:

  • Reporting issues or requesting features: Issues
  • Chat: Gitter

If you'd like to contribute more directly via a pull request, see below.

Pull Requests

Getting started

A prerequisite of working on Poxy with the intention of making a pull request is to have it installed as 'editable' from a clone of the repository:

git clone <your poxy fork>
cd poxy
pip install -e '.[dev]'

The [dev] extra pulls in pytest and ruff (matching the versions CI uses).

Running the tests

pytest

There are two kinds of test:

  • Unit tests (tests/test_units.py) cover the pure helper functions. They need neither Doxygen nor network access, run in a fraction of a second, and are the project's primary safety net.
  • Convergence tests (tests/test_snapshots.py) build each project under tests/test_* and compare the (sanitized) HTML/XML against the canonical expected_html / expected_xml trees. These require Doxygen on your PATH and are skipped automatically if it isn't found.

A core goal of poxy is to act as a man-in-the-middle between Doxygen and m.css, detecting and ironing out the differences between Doxygen versions. So the golden is poxy's desired, version-independent output, and CI runs the convergence tests against the full Doxygen matrix, expecting every version to reproduce it exactly.

A divergence on some Doxygen version is therefore a normalisation gap in poxy to be fixed - not a test to be relaxed. Re-bless the goldens (poxy --update-tests) only deliberately, using the reference Doxygen version documented in .github/workflows/ci.yaml.

Code style

It's Python. I'm primarily a C++ programmer. I really don't care that much. The codebase is linted and formatted with ruff (config in pyproject.toml); CI enforces both. Before pushing:

ruff check src tests
ruff format src tests

I'm not too fussy though. I'm unlikely to reject a PR on the basis of style unless you do something truly horrendous.

Versioning and releases

The version lives in a single place: the VERSION file at the repo root, a bare major.minor.patch triplet. setuptools reads it at build time, and at runtime poxy reads it back from the same file (falling back to the installed package metadata when running from a wheel rather than a checkout).

Releases are automated and maintainer-only. Bumping VERSION on main is what cuts a release: CI tags v<version>, and that tag triggers the publish workflow that uploads to PyPI.

The practical upshot for a PR: don't touch VERSION (nor add release headings to CHANGELOG.md). I bump it myself when cutting a release, so a PR that also bumps it just invites a merge conflict or an accidental publish.

Developer subcommands

A nontrivial amount of the Poxy codebase + assets are assembled from external sources or generated programmatically. Depending on what part of the application you're working on you may need to use one or more hidden developer-only subcommands to update these components or perform other tasks.

Using one or more developer subcommands will cause Poxy to execute their tasks and exit, without performing a regular documentation build. You may need to combine them together and then perform a regular Poxy invocation:

poxy --update-emoji --update-styles && poxy

They can appear in any order. The set of available commands is described below.

Updating m.css

If there are new upstream changes in m.css that you wish to incorporate into the poxy repository:

poxy --update-mcss <path/to/mcss/root>

ℹ️ Notes:

  • Development iteration on Poxy tends to happen more frequently than it does on the upstream mosra/m.css (because the maintainer of that project is very busy), so the one bundled in Poxy is based on my own fork (marzer/m.css). I intermittently make pull requests of my own to contribute back, though!

Updating the built-in fonts

Poxy pre-caches the Google Fonts used in documentation builds so that end-users do not need to make external HTTP requests for these. These rarely change, but if you need to update them:

poxy --update-fonts

ℹ️ Notes:

  • --update-fonts is implied by --update-mcss.

Updating the built-in CSS stylesheets

If you've made changes to any of the .css files in data/css:

poxy --update-styles

This will regenerate the amalgamated poxy.css that is shipped with documentation builds.

ℹ️ Notes:

  • --update-styles is implied by --update-mcss and --update-fonts.
  • While iterating on styles you ⚠️do not⚠️ need to fully regenerate the styles + rebuild some documentation to see your changes! That would be monumentally annoying. Instead you should use theme_sandbox/index.html, which uses the original version of poxy.css (the one that uses @import), not the amalgamated one.

Updating the emoji database

Poxy allows users to inject emoji into their documents by name using [emoji <name>], where <name> is derived from GitHub's Emoji API (e.g. [emoji tada] is equivalent to :tada:). This data is stored in the repository in an internal 'emoji database' file which needs to be regenerated occasionally (e.g. when new versions of Unicode are published):

poxy --update-emoji

Updating the test reference outputs

Each of the 'projects' in /tests/ has a set of reference outputs in expected_html and/or expected_xml. These are the 'blessed' versions of whatever the test is assessing, and must be regenerated when changes are made that impact the generated HTML or XML:

poxy --update-tests   # equivalently: pytest --regenerate

⚠️ Note: the golden is poxy's canonical version-independent output. Re-bless deliberately, and only using the reference Doxygen version (see .github/workflows/ci.yaml). Re-blessing on a different version bakes that version's quirks into the golden and masks the very normalisation gaps the convergence tests exist to catch.