Skip to content

Latest commit

 

History

History
344 lines (222 loc) · 9.62 KB

github-actions-templates.md

File metadata and controls

344 lines (222 loc) · 9.62 KB

Github Actions templates

This repository contains a number of GitHub Actions workflow template files that are copied to a project when running itkdev-docker-compose template:install. Any changes to the workflows should be made in this repository and then the project template must be updated to match the new templates.

Naming conventions

  • A workflow file is named after what it is concerned with, not how it's concerned with it and which tools are actually used, i.e. we have a markdown.yaml file and not a markdownlint.yaml file.
  • Some workflows are specific to a project type, currently drupal or symfony, and these sit in a project type subfolder, e.g. github/workflows/drupal.
  • Some tools require configuration files, and these sit in the config folder. Some tool configuration may be specific to a project type (or make sence only for a specific project type), and these specific config files sit in a project type subfolder, e.g. config/drupal/php/.phpcs.xml.dist and config/drupal/twig/.twig-cs-fixer.dist.php

Templates

The current list of templates is shown in the following sections.

github/workflows/changelog.yaml

Changelog

Checks that changelog has been updated

github/workflows/composer.yaml

Composer

Validates composer.json and checks that it's normalized.

Assumptions

  1. A docker compose service named phpfpm can be run and composer can be run inside the phpfpm service.

  2. ergebnis/composer-normalize is a dev requirement in composer.json:

    docker compose run --rm phpfpm composer require --dev ergebnis/composer-normalize

    Normalize composer.json by running

    docker compose run --rm phpfpm composer normalize

github/workflows/drupal-module/javascript.yaml

Drupal module JavaScript (and TypeScript)

Validates JavaScript files.

Assumptions

  1. A docker compose service named prettier for running Prettier exists.

github/workflows/drupal-module/php.yaml

Drupal module PHP

Checks that PHP code adheres to the Drupal coding standards.

Assumptions

  1. A docker compose service named phpfpm can be run and composer can be run inside the phpfpm service.

  2. drupal/coder is a dev requirement in composer.json:

    docker compose run --rm phpfpm composer require --dev drupal/coder

    Clean up and check code by running

    docker compose run --rm phpfpm vendor/bin/phpcbf
docker compose run --rm phpfpm vendor/bin/phpcs

Note

The template adds .phpcs.xml.dist as a configuration file for PHP_CodeSniffer and this makes it possible to override the actual configuration used in a project by adding a more important configuration file, e.g. .phpcs.xml.

github/workflows/drupal-module/styles.yaml

Drupal module Styles (CSS and SCSS)

Validates styles files.

Assumptions

  1. A docker compose service named prettier for running Prettier exists.

github/workflows/drupal/javascript.yaml

Drupal JavaScript (and TypeScript)

Validates JavaScript files.

Assumptions

  1. A docker compose service named prettier for running Prettier exists.

github/workflows/drupal/php.yaml

Drupal PHP

Checks that PHP code adheres to the Drupal coding standards.

Assumptions

  1. A docker compose service named phpfpm can be run and composer can be run inside the phpfpm service.

  2. drupal/coder is a dev requirement in composer.json:

    docker compose run --rm phpfpm composer require --dev drupal/coder

    Clean up and check code by running

    docker compose run --rm phpfpm vendor/bin/phpcbf
docker compose run --rm phpfpm vendor/bin/phpcs

Note

The template adds .phpcs.xml.dist as a configuration file for PHP_CodeSniffer and this makes it possible to override the actual configuration used in a project by adding a more important configuration file, e.g. .phpcs.xml.

github/workflows/drupal/site.yaml

Drupal

Checks that site can be installed and can be updated (from base branch on pull request).

Assumptions

  1. A docker compose service named phpfpm can be run and composer can be run inside the phpfpm service.
  2. The docker setup contains a database container and other the dependent services and the default settings match connection credentials for these services.
  3. The Drupal site can be installed from existing config.

github/workflows/drupal/styles.yaml

Drupal Styles (CSS and SCSS)

Validates styles files.

Assumptions

  1. A docker compose service named prettier for running Prettier exists.

github/workflows/markdown.yaml

Markdown

Lints Markdown files (**/*.md) in the project.

markdownlint-cli configuration files, .markdownlint.jsonc and .markdownlintignore, control what is actually linted and how.

Assumptions

  1. A docker compose service named markdownlint for running markdownlint (from markdownlint-cli) exists.

github/workflows/symfony/javascript.yaml

Symfony JavaScript (and TypeScript)

Validates JavaScript files.

Assumptions

  1. A docker compose service named prettier for running Prettier exists.

github/workflows/symfony/php.yaml

Symfony PHP

Checks that PHP code adheres to the Symfony coding standards.

Assumptions

  1. A docker compose service named phpfpm can be run and composer can be run inside the phpfpm service. 2. friendsofphp/php-cs-fixer is a dev requirement in composer.json:

    docker compose run --rm phpfpm composer require --dev friendsofphp/php-cs-fixer

    Clean up and check code by running

    docker compose run --rm phpfpm vendor/bin/php-cs-fixer fix
docker compose run --rm phpfpm vendor/bin/php-cs-fixer fix --dry-run --diff

[!NOTE] The template adds .php-cs-fixer.dist.php as a configuration file for PHP CS Fixer and this makes it possible to override the actual configuration used in a project by adding a more important configuration file, .php-cs-fixer.php.

github/workflows/symfony/styles.yaml

Symfony Styles (CSS and SCSS)

Validates styles files.

Assumptions

  1. A docker compose service named prettier for running Prettier exists.

github/workflows/twig.yaml

Twig

Validates Twig files

Assumptions

  1. A docker compose service named phpfpm can be run and composer can be run inside the phpfpm service.

  2. vincentlanglet/twig-cs-fixer is a dev requirement in composer.json:

    docker compose run --rm phpfpm composer require --dev vincentlanglet/twig-cs-fixer

  3. A Configuration file in the root of the project defines which files to check and rules to use.

github/workflows/yaml.yaml

YAML

Validates YAML files.

Assumptions

  1. A docker compose service named prettier for running Prettier exists.

Symfony YAML

Symfony's YAML config files use 4 spaces for indentation and single quotes. Therefore we use a Prettier configuration file, .prettierrc.yaml, to make Prettier format YAML files in the config/ folder like Symfony expects.

Updating template documentation

To update this document, run

task github-actions:documentation:update

GitHub Actions workflow documentation convention

Each workflow file must contain a single documentation block with lines starting with ###, e.g.

### ### The title
###
### This template …
###
### See … for details.

Important

All lines in the documentation block must start with ### and the documentation block consists of all consecutive lines starting with ###.