From 22a581a11512475526ecc9c94cd5671090564a26 Mon Sep 17 00:00:00 2001 From: James McKinney <26463+jpmckinney@users.noreply.github.com> Date: Tue, 26 Nov 2024 22:19:36 -0500 Subject: [PATCH] docs: Mention reusable workflows. Remove maintenance steps for workflows that are always reused. --- docs/docker/build.rst | 26 ++++++++++++++++++-------- docs/docker/samples/docker.yml | 21 ++++++++++++++++++++- docs/javascript/index.rst | 12 ++++++++++++ docs/javascript/samples/js.yml | 11 +++++++---- docs/python/ci.rst | 16 ++-------------- docs/python/i18n.rst | 4 ++-- docs/python/layout.rst | 2 +- docs/python/linting.rst | 4 +++- docs/python/packages.rst | 22 +++++++++++++--------- docs/services/admin.rst | 4 ++-- docs/shell/index.rst | 20 +++++++++++++------- docs/shell/samples/shell.yml | 13 +++++++++++-- 12 files changed, 104 insertions(+), 51 deletions(-) diff --git a/docs/docker/build.rst b/docs/docker/build.rst index c14ecda..2a3d450 100644 --- a/docs/docker/build.rst +++ b/docs/docker/build.rst @@ -1,12 +1,29 @@ Continuous integration ====================== -Create a ``.github/workflows/docker.yml`` file. +Create a ``.github/workflows/docker.yml`` file. As a base, use: + +.. literalinclude:: samples/docker.yml + :language: yaml + +.. tip:: + + In most cases, you can reuse either the `docker-single `__ or `docker-django `__ workflow. For example: + + .. code-block:: yaml + + jobs: + docker: + uses: open-contracting/.github/.github/workflows/docker-single.yml@main .. note:: This assumes there is already a :doc:`"CI" workflow <../python/ci>` that runs tests on the ``main`` branch. +.. note:: + + The `docker/build-push-action `__ step uses `BuildKit `__ by default. + If you need to build multiple images, then for each image: #. Include a ``docker/build-push-action`` step. @@ -17,13 +34,6 @@ If you need to build multiple images, then for each image: #. Add a suffix to the repository name under the ``tags`` key. -.. literalinclude:: samples/docker.yml - :language: yaml - -.. note:: - - The `docker/build-push-action `__ step uses `BuildKit `__ by default. - .. The following would simplify the workflow somewhat. However, it would not work when building multiple images, producing an inconsistent approach across repositories. diff --git a/docs/docker/samples/docker.yml b/docs/docker/samples/docker.yml index d2c1bec..bceb76b 100644 --- a/docs/docker/samples/docker.yml +++ b/docs/docker/samples/docker.yml @@ -7,4 +7,23 @@ on: - completed jobs: docker: - uses: open-contracting/.github/.github/workflows/docker-single.yml@main + if: ${{ github.event.workflow_run.conclusion == 'success' }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + # https://github.com/docker/login-action#github-container-registry + - uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + # https://github.com/docker/setup-buildx-action#usage + - uses: docker/setup-buildx-action@v3 + # https://github.com/docker/build-push-action#usage + - uses: docker/build-push-action@v6 + with: + push: true + tags: | + ghcr.io/${{ github.repository }}:latest + cache-from: type=gha + cache-to: type=gha,mode=max diff --git a/docs/javascript/index.rst b/docs/javascript/index.rst index c475b06..0cdbe6b 100644 --- a/docs/javascript/index.rst +++ b/docs/javascript/index.rst @@ -164,6 +164,18 @@ Create a ``.github/workflows/js.yml`` file. As a base, use: .. literalinclude:: samples/js.yml :language: yaml +.. tip:: + + In most cases, you can reuse the `js `__ workflow. For example: + + .. code-block:: yaml + + jobs: + lint: + uses: open-contracting/.github/.github/workflows/js.yml@main + with: + filenames: path/to/file.js + Reference --------- diff --git a/docs/javascript/samples/js.yml b/docs/javascript/samples/js.yml index 5fcd193..9bfcacc 100644 --- a/docs/javascript/samples/js.yml +++ b/docs/javascript/samples/js.yml @@ -1,7 +1,10 @@ name: Lint JavaScript on: [push, pull_request] jobs: - lint: - uses: open-contracting/.github/.github/workflows/js.yml@main - with: - filenames: path/to/file.js + build: + if: ${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: biomejs/setup-biome@v2 + - run: biome ci --indent-style=space --line-width=119 . diff --git a/docs/python/ci.rst b/docs/python/ci.rst index e7186cf..af50692 100644 --- a/docs/python/ci.rst +++ b/docs/python/ci.rst @@ -5,8 +5,8 @@ Continuous integration Workflows for: - - Linting :doc:`Python`, :ref:`JavaScript` and :ref:`shell scripts` - - :ref:`Releasing packages` + - Linting :ref:`Python`, :ref:`JavaScript` and :ref:`shell scripts` + - :ref:`Releasing packages` - :ref:`Checking translations` - :ref:`Checking accessibility` @@ -291,12 +291,6 @@ Find ``ci.yml`` files without ``lint.yml`` files, and vice versa: find . \( -name lint.yml \) -exec bash -c 'if [[ -z $(find $(echo {} | cut -d/ -f2) -name ci.yml) ]]; then echo {}; fi' \; find . \( -name ci.yml \) ! -path '*/node_modules/*' -exec bash -c 'if [[ -z $(find $(echo {} | cut -d/ -f2) -name lint.yml) ]]; then echo {}; fi' \; -Find and compare ``lint.yml`` files: - -.. code-block:: bash - - find . -name lint.yml -exec bash -c 'sha=$(shasum {} | cut -d" " -f1); if [[ ! "9773a893d136df0dc82deddedd8af8563969c04a 9222eac95ab63f3c2d983ba3cf4629caea53a72e fc3eff616a7e72f41c96e48214d244c9058dbc83 953ef7f0815d49226fd2d05db8df516fff2e3fdb dfe1c0d1fbdb18bb1e2b3bcfb1f0c10fe6b06bc4" =~ $sha ]]; then echo -e "\n\033[0;32m{}\033[0m"; echo $sha; cat {}; fi' \; - Find and compare ``pypi.yml`` files: .. code-block:: bash @@ -309,12 +303,6 @@ Find repositories for Python packages but without ``pypi.yml`` files: find . -name pyproject.toml ! -path '*/node_modules/*' -exec bash -c 'if grep classifiers {} > /dev/null && [[ -z $(find $(echo {} | cut -d/ -f2) -name pypi.yml) ]]; then echo {}; fi' \; -Find and compare ``i18n.yml`` files: - -.. code-block:: bash - - find . -name i18n.yml -exec bash -c 'echo $(shasum {} | cut -d" " -f1) {}' \; - Find repositories with ``LC_MESSAGES`` directories but without ``i18n.yml`` files: .. code-block:: bash diff --git a/docs/python/i18n.rst b/docs/python/i18n.rst index f88c7ba..bba6cfa 100644 --- a/docs/python/i18n.rst +++ b/docs/python/i18n.rst @@ -111,12 +111,12 @@ Repositories that support multiple locales should test that translation files ar Create a ``.github/workflows/i18n.yml`` file. -For a Django application, use the following. Change the ``python-version`` to match the version used to compile the :doc:`requirements_dev.txt file`. +For a Django application, reuse the `i18n-django `__ workflow. Change the ``python-version`` to match the version used to compile the :doc:`requirements_dev.txt file`. .. literalinclude:: ../../cookiecutter-django/{{cookiecutter.project_slug}}/.github/workflows/i18n.yml :language: yaml -For a Babel project, adapt: +For a Babel project, reuse the `i18n-babel `__ workflow. Change the ``command`` as needed: .. literalinclude:: samples/i18n/babel.yml :language: yaml diff --git a/docs/python/layout.rst b/docs/python/layout.rst index c656c89..319a9e7 100644 --- a/docs/python/layout.rst +++ b/docs/python/layout.rst @@ -59,7 +59,7 @@ Packages .. note:: - We don't use the `src/ layout `__ (`more `__). In practice, we rarely encounter the problems it solves, and our use of :ref:`check-manifest` and `test_requirements.py `__ guard against those problems. + We don't use the `src/ layout `__ (`more `__). In practice, we rarely encounter the problems it solves, and our use of `check-manifest `__ and `test_requirements.py `__ guard against those problems. Modules ------- diff --git a/docs/python/linting.rst b/docs/python/linting.rst index d396c5e..3c4e93d 100644 --- a/docs/python/linting.rst +++ b/docs/python/linting.rst @@ -103,7 +103,9 @@ To avoid pushing commits that fail formatting or linting checks, new projects sh Continuous integration ---------------------- -Create a ``.github/workflows/lint.yml`` file. The :doc:`django` and :doc:`Pypackage` Cookiecutter templates contain default workflows. +Create a ``.github/workflows/lint.yml`` file. + +The :doc:`django` and :doc:`Pypackage` Cookiecutter templates contain default workflows. .. seealso:: diff --git a/docs/python/packages.rst b/docs/python/packages.rst index 4fb93ef..294923c 100644 --- a/docs/python/packages.rst +++ b/docs/python/packages.rst @@ -75,21 +75,25 @@ The template reads the documentation from a ``README.rst`` file. To convert a `` :doc:`Python documentation guide` -.. _python-package-release-process: +Publish releases +---------------- -Release process ---------------- +.. _pypi-ci: + +Continuous integration +~~~~~~~~~~~~~~~~~~~~~~ -.. admonition:: One-time setup +To publish tagged releases to PyPI, create a ``.github/workflows/pypi.yml`` file: - To publish tagged releases to PyPI, create a ``.github/workflows/pypi.yml`` file: +.. literalinclude:: ../../cookiecutter-pypackage/{{cookiecutter.repository_name}}/.github/workflows/pypi.yml + :language: yaml - .. literalinclude:: ../../cookiecutter-pypackage/{{cookiecutter.repository_name}}/.github/workflows/pypi.yml - :language: yaml +The *open-contracting* organization sets the ``PYPI_API_TOKEN`` `organization secret `__ to the API token of the *opencontracting* `PyPI user `__, and ``TEST_PYPI_API_TOKEN`` to that of the *opencontracting* Test PyPI user. - The *open-contracting* organization sets the ``PYPI_API_TOKEN`` `organization secret `__ to the API token of the *opencontracting* `PyPI user `__, and ``TEST_PYPI_API_TOKEN`` to that of the *opencontracting* Test PyPI user. +After publishing the first release to PyPI, :ref:`add additional owners `. - After publishing the first release to PyPI, :ref:`add additional owners `. +Release process +~~~~~~~~~~~~~~~ #. Ensure that you are on an up-to-date ``main`` branch: diff --git a/docs/services/admin.rst b/docs/services/admin.rst index da319b5..c7b78c0 100644 --- a/docs/services/admin.rst +++ b/docs/services/admin.rst @@ -172,7 +172,7 @@ Third-party sysadmins can be added with "Global Administrator" access. PyPI ---- -For each package, there should be a minimum of two `Owner `__ users from OCP, including the `opencontracting `__ user, whose API token is used in `pypi.yml workflows `__. +For each package, there should be a minimum of two `Owner `__ users from OCP, including the `opencontracting `__ user, whose API token is used in `pypi.yml workflows `__. Only users who are reasonably expected to upload releases should have the Maintainer role. @@ -204,7 +204,7 @@ Third-party sysadmins can be added with "Member" access. Test PyPI --------- -For each package, the `opencontracting `__ user can be the single Owner, whose API token is used in `pypi.yml workflows `__. +For each package, the `opencontracting `__ user can be the single Owner, whose API token is used in `pypi.yml workflows `__. Transifex --------- diff --git a/docs/shell/index.rst b/docs/shell/index.rst index d37b9cc..2e95bc5 100644 --- a/docs/shell/index.rst +++ b/docs/shell/index.rst @@ -69,11 +69,23 @@ And: Continuous integration ---------------------- -Create a ``.github/workflows/shell.yml`` file with: +Create a ``.github/workflows/shell.yml`` file. As a base, use: .. literalinclude:: samples/shell.yml :language: yaml +.. tip:: + + In most cases, you can reuse the `shell `__ workflow. For example: + + .. code-block:: yaml + + jobs: + lint: + uses: open-contracting/.github/.github/workflows/shell.yml@main + with: + ignore: file.sh + Maintenance ~~~~~~~~~~~ @@ -83,12 +95,6 @@ Find repositories with shell scripts but without ``shell.yml`` files: find . \( -path '*/script/*' -o -name '*.sh' \) ! -path '*/.mypy_cache/*' ! -path '*/node_modules/*' ! -path '*/vendor/*' -exec bash -c 'if [[ -z $(find $(echo {} | cut -d/ -f2) -name shell.yml) ]]; then echo {}; fi' \; -Find and compare ``shell.yml`` files: - -.. code-block:: bash - - find . -name shell.yml -exec bash -c 'echo $(shasum {} | cut -d" " -f1) {}' \; - Reference --------- diff --git a/docs/shell/samples/shell.yml b/docs/shell/samples/shell.yml index dfdb0ac..77aee1c 100644 --- a/docs/shell/samples/shell.yml +++ b/docs/shell/samples/shell.yml @@ -1,5 +1,14 @@ name: Lint Shell on: [push, pull_request] jobs: - lint: - uses: open-contracting/.github/.github/workflows/shell.yml@main + build: + if: ${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: | + sudo apt update + sudo apt install devscripts shellcheck shfmt + - run: checkbashisms $(shfmt -f .) + - run: shellcheck $(shfmt -f .) + - run: shfmt -d -i 4 -sr $(shfmt -f .)