====================== Continuous Integration ====================== SpacePy uses `GitHub Actions `_ for continuous integration. Most of the relevant information is checked into the repository: the configuration file `CI.yml `_ manages the CI process, which ultimately runs `the unit tests `_. However a few elements of the setup are not in the repository and are documented here. This may be useful if this ever has to be set up in the future, or if you want to run SpacePy CI tests on your fork before opening a pull request. .. contents:: :local: Initial run =========== A workflow cannot be run `until it has been run once against the default branch `_ (``main``). This makes it somewhat hard to test the workflow before merging; in SpacePy this was handled by merging a tiny workflow first (PR `496 `_). Once this first run has been made, updated versions of the workflow can be run from topic branches. It will show up under the ``Actions`` tab of a repository and the branch to use can be selected. It is also possible to specify a branch `by using the REST API `_; you will need `an access token `_ with ``workflow`` scope. Merging rules ============= PRs require CI to pass before merging; this is managed with a `branch protection rule `_ (``Settings`` from the tab at the top of a repository, ``Branches`` from the left menu.) The relevant choices is "Require status checks to pass before merging." Every variant of the unit testing job (``test (2.7, ubuntu-18.04...`` etc.) will be in the list of checks; leave these alone and select only the ``All tests`` job. The name of this won't change and it will always depend on *all* the jobs in the workflow. "Require branches to be up to date" should *not* be selected; this encourages merging rather than our preferred rebase, and the tests will run against a (temporary) merge regardless. Rerunning CI on a PR ==================== There is no way to manually trigger a workflow run on a pull request. SpacePy's CI workflow is set up to `trigger the workflow `_ when a PR is marked ready for review, so one way to force a run is to mark the PR as a draft, and then as ready again. Note that a PR will not trigger the CI `if there is a merge conflict `_. Cacheing ======== Dependencies for CI are stored in two caches: one for all pip dependencies, and one for the NASA CDF library. This minimizes CI time use for building dependencies. Caches expire weekly (the week begins at 00 Monday, UTC). Caches can also be force-expired by incrementing the versions in ``ci.yml`` for the pip and/or CDF cache. Unfortunately this does require pushing a commit. Usage ===== SpacePy administrators can view the usage minutes, storage (for caches), etc. on our `billing page `_. -------------------------- :Release: |version| :Doc generation date: |today|