Merge branch 'main' into python

.github/workflows/lint.yml

@@ -7,17 +7,9 @@ jobs:
   lint:
     name: Lint markdown
     runs-on: ubuntu-latest
+    continue-on-error: true
     steps:
       - name: Checkout
         uses: actions/checkout@v3
-      - name: Setup ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: '3.0'
-          bundler-cache: true
-      - name: install MDL
-        run: gem install mdl -v 0.12.0
-      - name: Lint README
-        run: mdl README.md
-      - name: Lint docs
-        run: (cd docs && mdl .)
+      - name: Lint
+        run: bash lint.sh

README.md

@@ -13,22 +13,26 @@ This is currently work in progress.
 
 Do **not** modify the `gh-pages` branch directly!
 
+### Introducing a new section
+
+* Make a feature branch on this repository or a fork
+* If it does not yet exist, create a new markdown file for your section and
+  create the content (if necessary, also create the necessary folder structure)
+* Make the necessary changes to the table of contents and/or
+  [navigation configuration](./mkdocs.yml)
+* `Optional but recommended`: Make a pull request, and set it to draft mode.
+  Find at least one reviewer and assign them to the PR. Use Slack or face to
+  face discussion to get confirmation.
+* Add a link to the PR (or branch if there is no PR (yet)) to the source document
+
 ### Make or request changes to an existing section
 
 * Edit the section that you want to work on in a fork or separate branch.
-* When done, create a pull request.
+* When done, create a pull request. If you are the 'owner' of the section, find
+  a reviewer and assign them. If not, assign the owner as the reviewer.
 
 You may also create an issue and assign it to the owner of the relevant section.
 
-### Introducing a new section
-
-* Make an issue that describes the work, assign to yourself
-* Make a feature branch on this repository or a fork
-* Create a new markdown file for your section and create the content
-* Create the necessary folder structure if necessary
-* Make the necessary changes to the tabe of contents and/or [navigation configuration](./mkdocs.yml)
-* When ready to be reviewed, create a pull request
-
 ## Building and deploying
 
 Build and deploy via [MkDocs](https://www.mkdocs.org), using

docker/mdl/Dockerfile

@@ -0,0 +1,5 @@
+FROM alpine:3.19
+RUN apk add ruby git
+RUN gem install mdl -v 0.13.0
+ENTRYPOINT [ "mdl" ]
+CMD [ "" ]

docs/.mdlrc

@@ -1,2 +1,2 @@
 git_recurse true
-rules "~MD002", "~MD013", "~MD036"
+rules "~MD002", "~MD013", "~MD036"

docs/index.md

@@ -1,3 +1,5 @@
+# Home
+
 ## About the handbook
 
 This is work in progress!
@@ -6,7 +8,10 @@ This is work in progress!
 
 ## Contributing to the handbook
 
-For instructions, see the [GitHub repository](https://github.com/clarin-eric/handbook-development).
+Please read and follow the [meta guidelines](./meta-guidelines.md)!
+
+For further instructions, see the
+[GitHub repository](https://github.com/clarin-eric/handbook-development).
 
 ----
 [![Publication to GitHub Pages](https://github.com/clarin-eric/handbook-development/actions/workflows/publish.yml/badge.svg)](https://github.com/clarin-eric/handbook-development/actions/workflows/publish.yml)

docs/meta-guidelines.md

@@ -0,0 +1,53 @@
+# Meta guidelines
+
+This section presents some guidelines for the writing and maintenance
+of this handbook.
+
+## Scope
+
+The development handbook is aimed to give guidelines and best practices for the
+development process. Strictly operational matters should be avoided
+here, and rather be included in the [operational handbook](https://clarin-eric.github.io/handbook-operations/).
+
+As a rule of thumb, the following distinction can be kept in mind:
+
+* 👉 Anything that (also) happens on your **local machine** `SHOULD` be done in
+  line with the development handbook.
+* 👉 Anything that (also) happens in the **infrastructure** (in a broad sense?),
+  or where **roles & responsibilities** come into play,
+  `SHOULD` be done according to the operational handbook.
+
+Note that most processes involve both development and operational aspects.
+
+## Structure
+
+* 👉 Each page `MUST` have a level 1 heading (`#`) for the title of the section
+  or chapter
+* 👉 Level 2 headings (`##`) `MUST` be used for the main sections and use lower
+  level headings for subsections
+* 👉 Each page `SHOULD` include a short introduction describing its scope and context
+
+## Style
+
+* 👉 Mark concrete guidelines with the 👉 emoji
+* {TODO: Marking of policies, hints?}
+* 👉 Sets of related guidelines `SHOULD` be enumerated using **unordered lists**
+  (as used here)
+* 👉 Important keywords `MAY` be highlighted using `**` emphasis markup
+* 👉 Use `MAY`, `SHOULD` and `MUST` and use code markup for these using backticks
+* 👉 References `SHOULD` be placed in footnotes. Use the footnote markup that is
+  supported in both GitHub and mkdocs via the footnotes plugin, and requires usage
+  of a specific syntax[^FOOTNOTES].
+* 👉 Links that are not references `MAY` be rendered as regular inline links (see
+  below for an example)
+* 👉 The markdown for each page `MUST` pass linting with
+  [markdownlint](https://github.com/markdownlint/markdownlint) (see rules[^RULES]).
+   * TODO: hint about CI and local linting
+
+## Content
+
+* 👉 References to information sources and other relevant related resources `SHOULD`
+  be included where applicable. Use footnotes as described above.
+
+[^FOOTNOTES]: [GitHub blog: "Footnotes now supported in Markdown fields"](https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/)
+[^RULES]: [Markdownlint repository: `docs/RULES.md`](https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md)

lint.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+set -euo pipefail
+SCRIPT_DIR="$(cd -P -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+
+echo "Linting README" \
+	&& bash "${SCRIPT_DIR}/mdl.sh" 'README.md' \
+	&& echo "Linting docs" \
+	&& export WORKDIR="${SCRIPT_DIR}/docs" \
+	&& find "${WORKDIR}" -type f -name '*.md'| xargs bash "${SCRIPT_DIR}/mdl.sh"

mdl.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -euo pipefail
+SCRIPT_DIR="$(cd -P -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+
+echo "Building mdl image"
+docker build --quiet --tag 'mdl:latest' "${SCRIPT_DIR}/docker/mdl"
+
+docker run --rm --name markdown_lint \
+	-v "${SCRIPT_DIR}:${SCRIPT_DIR}" -w "${WORKDIR:-$(pwd -P)}" \
+	'mdl:latest' "$@"

mkdocs.yml

@@ -31,7 +31,7 @@ extra_css:
   - stylesheets/clarin-colours.css
 
 nav:
-  - Home: index.md
+  - 'Home': index.md
   - 'General guidelines':
     - 'Documentation': general-guidelines/documentation.md
     - 'Logging': general-guidelines/logging.md