Skip to content

Commit 2a53df1

Browse files
rimi-itkrimi-itk
committed
More documentation and cleanup
1 parent fca8164 commit 2a53df1

File tree

9 files changed

+160
-16
lines changed

9 files changed

+160
-16
lines changed

‎README.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,14 +47,20 @@ brew install dory
4747
### Templates
4848

4949
The [`templates`](templates/) directory contains templates for adding
50-
the itkdev `docker-compose` setup to new or exiting projects.
50+
the itkdev `docker compose` setup to new or exiting projects.
51+
52+
Run
5153

5254
```sh
53-
rsync -avz templates/<TYPE>/ <PATH TO HTDOCS FOLDER>
55+
itkdev-docker-compose template:install --list
5456
```
5557

56-
Also create an `.env` file beside the `docker-compose.yml` file that contains
57-
`COMPOSE_PROJECT_NAME=<NAME>` to namespace the docker setup for the projekt.
58+
to see a list of all templates.
59+
60+
Run `itkdev-docker-compose template:install drupal-10`, say, to install or update a template in a project.
61+
62+
In addition to the docker compose setup for our projects, installing a template will also add GitHib Actions workflow
63+
files to a project; see [Github Actions templates](docs/github-actions-templates.md) for details.
5864

5965
### Docker commands
6066

‎config/drupal/php/.phpcs.xml.dist‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
1+
<?xml version="1.0"?>
12
<!-- This file is copied from config/drupal/php/.phpcs.xml.dist in https://github.com/itk-dev/devops_itkdev-docker. -->
23
<!-- Feel free to edit the file, but consider making a pull request if you find a general issue with the file. -->
34

4-
<?xml version="1.0"?>
55
<ruleset name="PHP_CodeSniffer">
66
<description>The coding standard.</description>
77

8-
<file>web/*/custom/</file>
8+
<file>web/modules/custom/</file>
9+
<file>web/themes/custom/</file>
910

1011
<!-- Exclude generated files -->
1112
<exclude-pattern>node_modules</exclude-pattern>

‎docs/github-actions-templates.md‎

Lines changed: 63 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
<!-- DO NOT EDIT THIS FILE!
22
3-
It was automatically created by task/scripts/github-documentation-update at Tue Apr 8 13:30:36 CEST 2025.
3+
It was automatically
4+
created by task/scripts/github-documentation-update
5+
based on /app/task/scripts/../templates/github-actions-templates.md
6+
at 2025-04-09T11:29:14+02:00.
47
-->
58
# Github Actions templates
69

@@ -22,6 +25,8 @@ to match the new templates.
2225

2326
## Templates
2427

28+
The current list of templates is shown in the following sections.
29+
2530
---
2631

2732
[github/workflows/changelog.yaml](github/workflows/changelog.yaml)
@@ -59,7 +64,34 @@ Validates composer.json and checks that it's normalized.
5964

6065
[github/workflows/drupal/php.yaml](github/workflows/drupal/php.yaml)
6166

62-
Drupal PHP
67+
### Drupal PHP
68+
69+
Checks that PHP code adheres to the [Drupal coding
70+
standards](https://www.drupal.org/docs/develop/standards).
71+
72+
#### Assumptions
73+
74+
1. A docker compose service named `phpfpm` can be run and `composer` can be
75+
run inside the `phpfpm` service.
76+
2. [drupal/coder](https://www.drupal.org/project/coder) is a dev requirement
77+
in `composer.json`:
78+
79+
``` shell
80+
docker compose run --rm phpfpm composer require --dev drupal/coder
81+
```
82+
83+
Clean up and check code by running
84+
85+
``` shell
86+
docker compose run --rm phpfpm vendor/bin/phpcbf
87+
docker compose run --rm phpfpm vendor/bin/phpcs
88+
```
89+
90+
> [!NOTE]
91+
> The template adds `.phpcs.xml.dist` as [a configuration file for
92+
> PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#using-a-default-configuration-file)
93+
> and this makes it possible to override the actual configuration used in a
94+
> project by adding a more important configuration file, e.g. `.phpcs.xml`.
6395
6496
---
6597

@@ -92,8 +124,10 @@ JavaScript (and TypeScript)
92124
Uses [itkdev/markdownlint](https://hub.docker.com/r/itkdev/markdownlint) to
93125
link all Markdown files (`**/*.md`) in the project.
94126

95-
[markdownlint-cli configuration ### files](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#configuration),
96-
`.markdownlint.jsonc` and `.markdownlintignore` control what is actually linted and how.
127+
[markdownlint-cli configuration
128+
files](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#configuration),
129+
`.markdownlint.jsonc` and `.markdownlintignore`, control what is actually
130+
linted and how.
97131

98132
---
99133

@@ -105,7 +139,7 @@ Styles (CSS and SCSS)
105139

106140
[github/workflows/symfony/php.yaml](github/workflows/symfony/php.yaml)
107141

108-
Symfony PHP
142+
### Symfony PHP
109143

110144
---
111145

@@ -131,3 +165,27 @@ Validates Twig files
131165
in the root of the project defines which files to check and rules to use.
132166

133167
---
168+
169+
## Updating template documentation
170+
171+
To update this document, run
172+
173+
``` shell
174+
task github-actions:documentation:update
175+
```
176+
177+
### GitHub Actions workflow documentation convention
178+
179+
Each workflow file must contain a single documentation block with lines starting with `###`, e.g.
180+
181+
``` markdown
182+
### ### The title
183+
###
184+
### This template …
185+
###
186+
### See … for details.
187+
```
188+
189+
> [!IMPORTANT]
190+
> All lines in the documentation block must start with `###` and the documentation block consists of all consecutive
191+
> lines starting with `###`.

‎github/workflows/drupal/php.yaml‎

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,51 @@
22
# github/workflows/drupal/php.yaml in
33
# https://github.com/itk-dev/devops_itkdev-docker if need be.
44

5-
### Drupal PHP
5+
### ### Drupal PHP
6+
###
7+
### Checks that PHP code adheres to the [Drupal coding
8+
### standards](https://www.drupal.org/docs/develop/standards).
9+
###
10+
### #### Assumptions
11+
###
12+
### 1. A docker compose service named `phpfpm` can be run and `composer` can be
13+
### run inside the `phpfpm` service.
14+
### 2. [drupal/coder](https://www.drupal.org/project/coder) is a dev requirement
15+
### in `composer.json`:
16+
###
17+
### ``` shell
18+
### docker compose run --rm phpfpm composer require --dev drupal/coder
19+
### ```
20+
###
21+
### Clean up and check code by running
22+
###
23+
### ``` shell
24+
### docker compose run --rm phpfpm vendor/bin/phpcbf
25+
### docker compose run --rm phpfpm vendor/bin/phpcs
26+
### ```
27+
###
28+
### > [!NOTE]
29+
### > The template adds `.phpcs.xml.dist` as [a configuration file for
30+
### > PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#using-a-default-configuration-file)
31+
### > and this makes it possible to override the actual configuration used in a
32+
### > project by adding a more important configuration file, e.g. `.phpcs.xml`.
33+
34+
name: PHP
35+
36+
env:
37+
COMPOSE_USER: root
38+
39+
on:
40+
pull_request:
41+
push:
42+
43+
jobs:
44+
coding-standards:
45+
name: PHP - Check Coding Standards
46+
runs-on: ubuntu-latest
47+
steps:
48+
- uses: actions/checkout@v4
49+
- run: |
50+
docker network create frontend
51+
docker compose run --rm phpfpm composer install
52+
docker compose run --rm phpfpm vendor/bin/phpcs

‎github/workflows/markdown.yaml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,10 @@
77
### Uses [itkdev/markdownlint](https://hub.docker.com/r/itkdev/markdownlint) to
88
### link all Markdown files (`**/*.md`) in the project.
99
###
10-
### [markdownlint-cli configuration ### files](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#configuration),
11-
### `.markdownlint.jsonc` and `.markdownlintignore` control what is actually linted and how.
10+
### [markdownlint-cli configuration
11+
### files](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#configuration),
12+
### `.markdownlint.jsonc` and `.markdownlintignore`, control what is actually
13+
### linted and how.
1214

1315
name: Markdown
1416

‎github/workflows/symfony/php.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
# github/workflows/symfony/php.yaml in
33
# https://github.com/itk-dev/devops_itkdev-docker if need be.
44

5-
### Symfony PHP
5+
### ### Symfony PHP

‎task/scripts/config-headers-update‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ for f in $(find config -type f); do
2424
comment_start='// '
2525
comment_end=''
2626
elif [[ "$f" =~ \.xml(\.dist)?$ ]]; then
27+
comment_prefix='<?xml version="1.0"?>'
2728
comment_start='<!-- '
2829
comment_end=' -->'
2930
fi

‎task/scripts/github-documentation-update‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,10 @@ mkdir -p "$(dirname "$output_file_name")"
2727
cat >> "$output_file_name" <<EOF
2828
<!-- DO NOT EDIT THIS FILE!
2929
30-
It was automatically created by ${BASH_SOURCE[0]} at $(date).
30+
It was automatically
31+
created by ${BASH_SOURCE[0]}
32+
based on ${template_file_name}
33+
at $(date --iso-8601=seconds).
3134
-->
3235
EOF
3336

‎task/templates/github-actions-templates.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,32 @@ to match the new templates.
1818

1919
## Templates
2020

21+
The current list of templates is shown in the following sections.
22+
2123
<!--insert:templates:here-->
2224

2325
---
26+
27+
## Updating template documentation
28+
29+
To update this document, run
30+
31+
``` shell
32+
task github-actions:documentation:update
33+
```
34+
35+
### GitHub Actions workflow documentation convention
36+
37+
Each workflow file must contain a single documentation block with lines starting with `###`, e.g.
38+
39+
``` markdown
40+
### ### The title
41+
###
42+
### This template …
43+
###
44+
### See … for details.
45+
```
46+
47+
> [!IMPORTANT]
48+
> All lines in the documentation block must start with `###` and the documentation block consists of all consecutive
49+
> lines starting with `###`.

0 commit comments

Comments
 (0)