Skip to content

Commit 3e30132

Browse files
rimi-itkrimi-itk
committed
More documentation and cleanup
1 parent 0bd7408 commit 3e30132

File tree

9 files changed

+158
-16
lines changed

9 files changed

+158
-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: 62 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
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 created at 2025-04-09T11:40:57+02:00
4+
by task/scripts/github-documentation-update
5+
based on /app/task/scripts/../templates/github-actions-templates.md
46
-->
57
# Github Actions templates
68

@@ -22,6 +24,8 @@ to match the new templates.
2224

2325
## Templates
2426

27+
The current list of templates is shown in the following sections.
28+
2529
---
2630

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

6064
[github/workflows/drupal/php.yaml](github/workflows/drupal/php.yaml)
6165

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

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

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.
126+
[markdownlint-cli configuration
127+
files](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#configuration),
128+
`.markdownlint.jsonc` and `.markdownlintignore`, control what is actually
129+
linted and how.
97130

98131
---
99132

@@ -105,7 +138,7 @@ Styles (CSS and SCSS)
105138

106139
[github/workflows/symfony/php.yaml](github/workflows/symfony/php.yaml)
107140

108-
Symfony PHP
141+
### Symfony PHP
109142

110143
---
111144

@@ -131,3 +164,27 @@ Validates Twig files
131164
in the root of the project defines which files to check and rules to use.
132165

133166
---
167+
168+
## Updating template documentation
169+
170+
To update this document, run
171+
172+
``` shell
173+
task github-actions:documentation:update
174+
```
175+
176+
### GitHub Actions workflow documentation convention
177+
178+
Each workflow file must contain a single documentation block with lines starting with `###`, e.g.
179+
180+
``` markdown
181+
### ### The title
182+
###
183+
### This template …
184+
###
185+
### See … for details.
186+
```
187+
188+
> [!IMPORTANT]
189+
> All lines in the documentation block must start with `###` and the documentation block consists of all consecutive
190+
> 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: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,9 @@ 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 created at $(date --iso-8601=seconds)
31+
by ${BASH_SOURCE[0]}
32+
based on ${template_file_name}
3133
-->
3234
EOF
3335

‎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)