Decide how to organize CI actions

[brylie]

For context, we have recently refactored this project so there is only a single src/ directory containing all package code.

We currently have three CI actions defined:

• fonts
• vocabulary
• vue-vocabulary

Each of the three CI actions has nearly identical structure:

• on: definitions to determine when the action should run
• env: variables that may no longer be needed
• jobs to execute the following actions
  • setup to install Node.js, cache node modules, and install project dependencies
  • lint (depends on setup) to lint the code
  • unit (depends on setup) to run unit tests
  • build (depends on setup) to run the build process

Not only are there duplicate steps within each of the above jobs (such as installing node and project dependencies), it is likely that we no longer need three separate actions.

So, we should determine how best to reorganize our CI script(s) in order to reduce duplication and resource usage as well as making it clear for developers what parts are breaking when there are errors.

Please discuss and upvote the suggestions below to show your support or add modifications. Likewise, feel free to add other proposals.

[brylie]

One solution would be to consolidate all CI code into a single action, such as continuous_integration.yaml. The CI file would have a structure somewhat like the code below. Note that the code is speculative right now and intended only to illustrate the idea.

continuous-integration.yml

name: Continuous integration

on: # TODO: determine best "on" configuration
  push:
    paths:
      - "packages/**"
      - "scripts/**"
      - "src/**"
    branches:
      - main
  pull_request:
    paths:
      - "packages/**"
      - "scripts/**"
      - "src/**"
    branches:
      - main

env:
  CI: true # is this needed?
  PUPPETEER_SKIP_CHROMIUM_DOWNLOAD: true # is this needed?

jobs:
  setup:
    name: Setup
    defaults:
      run:
        working-directory: "/"
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: "12.16.1"

      - id: cache-node-modules
        name: Cache Node.js modules
        uses: actions/cache@v1
        with:
          path: ~/.npm # npm caches files in ~/.npm
          key: node-${{ hashFiles('**/package-lock.json') }}

      - name: Install dependencies
        if: steps.cache-node-modules.outputs.cache-hit != 'true'
        run: npm install --no-audit

  lint:
    name: Lint
    defaults:
      run:
        working-directory: "/"
    runs-on: ubuntu-latest
    needs: setup

    steps: # will it work to only have the lint step here?
      - name: Run lint
        run: npm run lint

  unit:
    name: Unit tests
    defaults:
      run:
        working-directory: "packages/vocabulary"
    runs-on: ubuntu-latest
    needs: setup

    steps: # Will it work to only have the "run tests" step here?
      - name: Run tests
        run: npm run test:unit

  build:
    name: Build
    defaults:
      run:
        working-directory: "/"
    runs-on: ubuntu-latest
    needs: setup

    steps: # Will it work to only have the "run build" step here?
      - name: Run build
        run: npm run build:storybook

[brylie]

Some pros/cons of this step might be:

Pros

• efficient resource usage, since there is only one setup process that does the heavy lifting
• only one definition file is needed

Cons

• error messages may be a bit more difficult for developers to understand, since the "continuous integration" process consists of lint, unit, and build tasks

[MuluhGodson]

I totally agree, the three scripts I think run the same commands so it will make sense resource-wise to use one file as you suggested. continuous_integration.yaml

For local testing of github actions I am using a package:
https://github.com/nektos/act
It would be helpful as concerns testing the script locally, in case it is made into an issue and assigned.

[brylie]

Alternatively, we can separate the continuous integration scripts along the lines of their purpose, such as

• lint
• unit test
• build

In the above division, we would end up with three files, each demonstrated in a relevant section below.

ci-lint.yml

name: Lint

on: # TODO: determine best "on" configuration
  push:
    paths:
      - "packages/**"
      - "scripts/**"
      - "src/**"
    branches:
      - main
  pull_request:
    paths:
      - "packages/**"
      - "scripts/**"
      - "src/**"
    branches:
      - main

env:
  CI: true # Is this needed?
  PUPPETEER_SKIP_CHROMIUM_DOWNLOAD: true # Is this needed?

jobs:
  setup:
    name: Setup
    defaults:
      run:
        working-directory: "/"
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: "12.16.1"

      - id: cache-node-modules
        name: Cache Node.js modules
        uses: actions/cache@v1
        with:
          path: ~/.npm # npm caches files in ~/.npm
          key: node-${{ hashFiles('**/package-lock.json') }}

      - name: Install dependencies
        run: npm install --no-audit

  lint:
    name: Lint
    defaults:
      run:
        working-directory: "/"
    runs-on: ubuntu-latest
    needs: setup

    steps: # Will this work as expected with only the "run lint" step?
      - name: Run lint
        run: npm run lint

ci-test.yml

name: Unit test

on: # TODO: determine best "on" configuration
  push:
    paths:
      - "packages/**"
      - "scripts/**"
      - "src/**"
    branches:
      - main
  pull_request:
    paths:
      - "packages/**"
      - "scripts/**"
      - "src/**"
    branches:
      - main

env:
  CI: true # Is this needed?
  PUPPETEER_SKIP_CHROMIUM_DOWNLOAD: true # Is this needed?

jobs:
  setup:
    name: Setup
    defaults:
      run:
        working-directory: "/"
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: "12.16.1"

      - id: cache-node-modules
        name: Cache Node.js modules
        uses: actions/cache@v1
        with:
          path: ~/.npm # npm caches files in ~/.npm
          key: node-${{ hashFiles('**/package-lock.json') }}

      - name: Install dependencies
        run: npm install --no-audit

  unit:
    name: Unit tests
    defaults:
      run:
        working-directory: "packages/fonts"
    runs-on: ubuntu-latest
    needs: setup

    steps: # Will this work with only the "run tests" step?
      - name: Run tests
        run: npm run test:unit

ci-build.yml

name: Build

on: # TODO: determine best "on" configuration
  push:
    paths:
      - "packages/**"
      - "scripts/**"
      - "src/**"
    branches:
      - main
  pull_request:
    paths:
      - "packages/**"
      - "scripts/**"
      - "src/**"
    branches:
      - main

env:
  CI: true # Is this needed?
  PUPPETEER_SKIP_CHROMIUM_DOWNLOAD: true # Is this needed?

jobs:
  setup:
    name: Setup
    defaults:
      run:
        working-directory: "/"
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: "12.16.1"

      - id: cache-node-modules
        name: Cache Node.js modules
        uses: actions/cache@v1
        with:
          path: ~/.npm # npm caches files in ~/.npm
          key: node-${{ hashFiles('**/package-lock.json') }}

      - name: Install dependencies
        run: npm install --no-audit

  build:
    name: Build
    defaults:
      run:
        working-directory: "/"
    runs-on: ubuntu-latest
    needs: setup

    steps: # Will this work with only the "run build" step defined?
      - name: Run build
        run: npm run build:storybook

[MuluhGodson]

how about one of the scripts is designated to run when all the other scripts are called.
say a script that has to run everytime like the ci-test.yml (assuming the test are all functional). The dependencies and environment can be prepared here. Then the other scripts just carry out their core functions without having to install the same dependencies over again. Just a thought

[brylie]

Two possibilities might be to use artifacts or cache objects that can be shared across actions.

[brylie]

The shared script would reduce code duplication but not resource usage. I.e. the script would run in all three actions, installing node and project dependencies each time.

[brylie]

In any case, we can optimize code/resource usage as a follow-up task. The initial step would be to refactor the CI process into three parts (outlined above) and clarify some of the questions in code comments.

[MuluhGodson]

https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobs

Looking at Githubs documentation on actions, I'm not sure we can have an action without a job. I will certainly have to do more research.

[MuluhGodson]

I think I may be able to further optimize the CI scripts to further reduce over-using resources which may also be able to close #973

[brylie]

Yeah, that was my understanding too, which was one of the cons of separating the tasks into separate workflows.

[MuluhGodson]

well. i have already removed the setup actions from all the files and tested them locally. So if you wish, you could open a PR for that and I just push the changes.

[brylie]

Sure, that sounds like a good improvement.

[MuluhGodson]

Okay that's great. I will be waiting for the issue request to submit a PR

[brylie]

https://github.com/creativecommons/vocabulary/issues/984