Skip to content

Best practice for development of CI configurations

Jump to bottom
Andrew Nelson edited this page Mar 20, 2023 · 2 revisions

Developing and debugging CI configurations can be trying, and use up a lot of CI resources. These are some guidelines for streamlining work on CI setup.

Try and replicate what you do in the job on a local machine

A lot of CI configurations use Linux. On your local computer use Docker to run the same container as would be used in the CI. Docker containers can run a wide variety of Linux OSs, and docker desktop can be used to emulate different architectures as well. For example:

docker run -it --platform=linux/arm64 ubuntu:22.04

can start up a Linux ARM instance, even if your local computer is x86_64.

Start off with Linux

As just mentioned, it's easy to run Linux containers locally using Docker desktop. Get as much of the CI job working on Linux as you can, then extend to macOS/Win. You'll be able to iron out most of your mistakes with a setup that's cheap and easy to knockdown and recreate when you make mistakes.

Submit PRs against your fork first.

In line with best practice you should fork the main scipy repository first, then clone your fork to your local computer.

  • create a feature branch that you'll be working on.
  • Commit the changes (with an appropriate message) and push the feature branch to your fork on Github.
  • Once you're happy create a PR against your fork! This way you'll be using CI resources associated with your fork, not the CI resources used by the scipy/scipy repository. This will allow you to iterate much faster, and not create noise on the main scipy repository.
  • You may have to change lines like this:
if: "github.repository == 'scipy/scipy' || github.repository == ''"

to something like:

if: "github.repository == 'andyfaff/scipy' || github.repository == ''"

in order for CI to run on your fork. These are guard lines that are added to many CI configurations so that CI runs don't occur on personal forks. You will need to revert these changes before eventually submitting your PR against scipy/scipy. Only change these lines in the CI configurations you're working on.

  • You may need to edit the repository settings for your fork to enable CI to run. This is CI provider dependent.

  • You can prevent individual CIs from running by including text in your commit message. These include using one or more of: [skip ci] [skip cirrus] [skip circle] [skip ci] [skip actions]. Look at what CI runs occur on the PR against your fork and figure out which ones you don't need to run.

  • when you're happy that the CI is running well in the PR against your fork (e.g. andyfaff/scipy), and everything is green, then submit a PR against scipy/scipy. Given that multiple commits may occur as you iterate, it's often a good idea to squash commits before you submit the PR.

Clone this wiki locally