From f974734f104b986b21ca87cb4e172a5f53d082f6 Mon Sep 17 00:00:00 2001 From: AbhiLohar Date: Wed, 21 Jan 2026 23:01:20 +0530 Subject: [PATCH 1/2] docs: add local development and CI workflow guide to {{ cookiecutter.package_name }} (#2) --- {{ cookiecutter.package_name }}/docs/ci.rst | 180 ++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 {{ cookiecutter.package_name }}/docs/ci.rst diff --git a/{{ cookiecutter.package_name }}/docs/ci.rst b/{{ cookiecutter.package_name }}/docs/ci.rst new file mode 100644 index 0000000..e34aa67 --- /dev/null +++ b/{{ cookiecutter.package_name }}/docs/ci.rst @@ -0,0 +1,180 @@ +.. _ci: + +====================== +Continuous Integration +====================== + +Continuous Integration (CI) is the method by which software is tested and built before deployment to users. +A set of 'jobs' are defined in a ``.yml`` file, roughly taking the flow build - test - deploy. +Each run is built from a clean environment. + +Local Development Workflow +========================== + +Before code is pushed to GitHub, it is expected to pass local quality checks. This ensures that the CI "jobs" defined below have the best chance of succeeding. + +Pre-commit Hooks +---------------- + +This project uses `pre-commit `__ to catch common formatting issues. + +**Common Checks:** + +* **Trim Trailing Whitespace**: Removes unnecessary spaces at the end of lines. +* **Mixed Line Endings**: Ensures all files use Unix-style (LF) line endings. If a check fails here, ensure your editor is set to LF. +* **Ruff/Flake8**: Checks for Python coding style (PEP 8) and syntax errors. + +If a pre-commit check fails, the tool will often fix the file for you. You must then **stage the changed files again** using ``git add`` before you can successfully commit. + +Testing with Tox +---------------- + +`Tox `__ is used to run tests in isolated virtual environments. To run the style checks locally (the same ones run by the CI), use: + +.. code-block:: bash + + tox -e codestyle + +To run the full test suite, simply run: + +.. code-block:: bash + + tox + +Workflows can be set to begin on triggers for example, a ``git push`` or a new tag. + +There are an array solutions for running CI, Open Astronomy recommends `GitHub Actions `__ for projects using GitHub. +GitHub Actions workflows are defined in the ``.github/workflows/`` folder at the root of the repo. +Open Astronomy maintains a `set of tools `__ to make configuring GitHub Actions easier. + +Examples +++++++++ + +Testing +------- + +In order GitHub Actions to run your workflow, it requires; an event to trigger the workflow, one or more jobs to complete and all steps must either run a script or trigger an action. +Looking at this in context: + +.. code-block:: yaml + + name: Run template tests + + on: + push: + pull_request: + workflow_dispatch: + + jobs: + test: + uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1 + with: + envs: | + - linux: py311-test + +In this case the workflow is triggered on a push to a branch, a PR, or a manual trigger of the workflow (`workflow_dispatch`). +The second line of the job defines the name of the job, in this case ``test``, and uses Open Astronomy's pre-defined workflow to run the tests with tox. +The ``envs`` list, defines which tox environments will be run for that job. + +Publishing to PyPI +------------------ + +No Compiled Extensions +###################### + +Python packages should be published on `PyPI `__, which can be automated on CI. +This can improve security (as fewer people need access to publish on PyPI) and make it less effort for maintainers to publish a release. +When we are building and publishing releases to PyPI we only want this to happen on a `git tag `__, as opposed to on every commit. +However, if we only run the build job on tags, we never have a way to test that the job works before we tag a release of our package. +The OpenAstronomy publish workflows will (by default) only publish to PyPI on a tag which starts with `v` (`see here `__). +Therefore, we recommend running the workflow on both push to your default branch (`main`), on tags and on manual runs. + +.. code-block:: yaml + + on: + push: + branches: + - 'main' + tag: + workflow_dispatch: + + jobs: + publish: + uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish_pure_python.yml@v1 + with: + test_extras: test + test_command: pytest --pyargs + secrets: + pypi_token: ${{ secrets.pypi_token }} + +Replace references to `` with the package to be published. + +To publish to PyPI we need a PyPI token, associated with your PyPI account. +`Instructions on creating up your key here `__. +The secret can be stored at `organisation `__ or `repo level `__ in GitHub settings. + +With Compiled Extensions +######################## + +Almost all packages on pypi also have environment specific binaries with all dependencies packaged. +It is expected that a package publishes both a pure python distribution and the binary, see `here for examples `__. + +In this case, in addition to the running the tests, the ``with`` block also includes targets. +'Targets' are the distributions which the binary will be built for, so in this case it would be linux and MacOS 64 bit. +The ``publish`` method from the Open Astronomy GitHub actions packages the module with the dependencies for the specific targets listed + +.. code-block:: yaml + + jobs: + publish: + uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish.yml@v1 + with: + test_extras: test + test_command: pytest --pyargs test_package + targets: | + - linux + - cp3?-macosx_x86_64 + secrets: + pypi_token: ${{ secrets.pypi_token }} + +Putting it all together +####################### + +Combining the above steps reveals a total workflow, build, testing and publishing + +.. code-block:: yaml + + name: package_deployment + + on: + push: + tag: + + jobs: + test: + uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1 + with: + envs: | + - linux: py311 + + publish_python: + uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish_pure_python.yml@v1 + with: + test_extras: test + test_command: pytest --pyargs test_package + secrets: + pypi_token: ${{ secrets.pypi_token }} + + publish_binaries: + uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish.yml@v1 + with: + test_extras: test + test_command: pytest --pyargs test_package + targets: | + - linux + - cp3?-macosx_x86_64 + secrets: + pypi_token: ${{ secrets.pypi_token }} + +The ``.github/workflows/`` directory may contain several workflows such as the above. +Each file may contain different workflows, with different triggers dependent on requirements. \ No newline at end of file From 4f6a072453f0da956a25bf99faf13f1524ebab9d Mon Sep 17 00:00:00 2001 From: AbhiLohar Date: Wed, 21 Jan 2026 23:30:34 +0530 Subject: [PATCH 2/2] style: add newline at end of ci.rst to satisfy pre-commit --- {{ cookiecutter.package_name }}/docs/ci.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{ cookiecutter.package_name }}/docs/ci.rst b/{{ cookiecutter.package_name }}/docs/ci.rst index e34aa67..22d0d3a 100644 --- a/{{ cookiecutter.package_name }}/docs/ci.rst +++ b/{{ cookiecutter.package_name }}/docs/ci.rst @@ -177,4 +177,4 @@ Combining the above steps reveals a total workflow, build, testing and publishin pypi_token: ${{ secrets.pypi_token }} The ``.github/workflows/`` directory may contain several workflows such as the above. -Each file may contain different workflows, with different triggers dependent on requirements. \ No newline at end of file +Each file may contain different workflows, with different triggers dependent on requirements.