Skip to content

MIGRATION.md

Latest commit

 

History

History
99 lines (76 loc) · 3.5 KB

MIGRATION.md

File metadata and controls

99 lines (76 loc) · 3.5 KB
Raw

Migration guide

The new repository was designed after inspecting these existing repositories:

  • compas-actions.build
  • compas-actions.docs
  • compas-actions.docversions
  • compas-actions.ghpython_components
  • compas-actions.publish

It does not preserve their input surface. Migrate one workflow at a time and keep the old repositories available until all consumers have moved.

Build and test

Replace one compas-actions.build step with the ci action. The caller keeps the matrix because a composite action runs on one selected runner:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python: ["3.10", "3.11", "3.12", "3.13"]
    steps:
      - uses: compas-dev/compas-actions/ci@v1
        with:
          python-version: ${{ matrix.python }}
          invoke-tasks: lint test
          check-import: true

Use setup-python and normal run: invoke ... steps when a repository needs custom steps between environment setup and its checks.

Pull requests

Replace Zomzog/changelog-checker with pr-checks. The unified action checks the pull request diff directly and supports the same skip-label policy without requiring a GitHub token or a legacy Node action:

- uses: compas-dev/compas-actions/pr-checks@v1
  with:
    changelog-path: CHANGELOG.md
    skip-label: no changelog

Releases

compas-actions.publish combined unrelated trust boundaries. Replace it with:

  1. A caller-owned manual workflow that invokes release-pr with an explicit SemVer component and opens a reviewable release/vX.Y.Z pull request.
  2. release-check, called from PR checks and from the main push workflow, to validate and detect the merged version change.
  3. prepare-release, called from a read-only job, which builds and uploads workflow artifacts.
  4. A caller-owned pypa/gh-action-pypi-publish job using OIDC.
  5. github-release, called from a contents: write job only after PyPI succeeds.

The release PR preserves a manually written Keep a Changelog file. The merge strategy does not affect versioning because the release is detected from the version configuration and changelog in the merged tree, not commit messages.

Generated files belong in an invoke pre-build task. Pass their paths through release-assets; the preparation job builds once and uploads package and extra artifacts once each. The PyPI and GitHub release jobs download only what they need.

Do not pass a PyPI token. Configure a Trusted Publisher on PyPI and make its workflow and environment names exactly match the caller.

Documentation

compas-actions.docs and compas-actions.docversions are replaced by the docs action. Sphinx sites must migrate to MkDocs before using the new repository.

Grasshopper components

compas-actions.ghpython_components is replaced by ghpython-components. Only Rhino 8 CPython components are supported. The action is self-contained for installing the standalone ghpython_componentizer package and must run on Windows after Python has been installed. The package downloads the required Grasshopper assembly itself.

Versioning and rollout

Use @main only during the initial test period. Once the interfaces settle:

  1. create v1.0.0;
  2. maintain a movable v1 branch or tag for low-friction consumers;
  3. use readable version tags consistently in calling workflows;
  4. migrate a small pure-Python package first, then a package with pre-build assets, MkDocs, Conda, and finally Rhino components.