From 087f10cb52da6b0041e2c69a6d83da568e7c3360 Mon Sep 17 00:00:00 2001 From: msteslov Date: Mon, 25 May 2026 11:24:00 +0300 Subject: [PATCH 1/3] Add Markdown documentation linting Signed-off-by: msteslov --- .github/workflows/basic.yml | 12 ++++++++++++ .rumdl.toml | 25 +++++++++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 .rumdl.toml diff --git a/.github/workflows/basic.yml b/.github/workflows/basic.yml index c97d25071b..ea02a8bff9 100644 --- a/.github/workflows/basic.yml +++ b/.github/workflows/basic.yml @@ -34,6 +34,18 @@ jobs: - name: Validate CBOM run: scripts/validate_cbom.sh + markdownlint: + name: Check Markdown documentation + needs: [workflowcheck] + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # pin@v4 + - name: Install rumdl + run: python3 -m pip install --user rumdl==0.2.4 + - name: Ensure Markdown conventions are upheld + run: ~/.local/bin/rumdl check --config .rumdl.toml --respect-gitignore --exclude "build,**/build" . + upstreamcheck: name: Check upstream code is properly integrated needs: [workflowcheck] diff --git a/.rumdl.toml b/.rumdl.toml new file mode 100644 index 0000000000..7e7b1ddf60 --- /dev/null +++ b/.rumdl.toml @@ -0,0 +1,25 @@ +[global] +# Keep the initial lint configuration focused on Markdown rules that match the +# existing documentation style and do not require unrelated documentation churn. +enable = [ + "MD001", # heading-increment + "MD004", # ul-style + "MD011", # no-reversed-links + "MD014", # commands-show-output + "MD018", # no-missing-space-atx + "MD019", # no-multiple-space-atx + "MD020", # no-missing-space-closed-atx + "MD021", # no-multiple-space-closed-atx + "MD023", # heading-start-left + "MD026", # no-trailing-punctuation + "MD027", # no-multiple-space-blockquote + "MD028", # no-blanks-blockquote + "MD035", # hr-style + "MD037", # no-space-in-emphasis + "MD039", # no-space-in-links + "MD042", # no-empty-links + "MD043", # required-headings + "MD044", # proper-names + "MD045", # no-alt-text + "MD048", # code-fence-style +] From bd0cf7112a6807dc644f6d8cb39fddccf455bc10 Mon Sep 17 00:00:00 2001 From: "Ganyu (Bruce) Xu" Date: Mon, 13 Jul 2026 11:51:13 -0400 Subject: [PATCH 2/3] Pin rumdl==0.2.18, add pip hash Signed-off-by: Ganyu (Bruce) Xu --- .github/workflows/basic.yml | 3 ++- requirements-dev.txt | 8 ++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 requirements-dev.txt diff --git a/.github/workflows/basic.yml b/.github/workflows/basic.yml index ea02a8bff9..36d491c410 100644 --- a/.github/workflows/basic.yml +++ b/.github/workflows/basic.yml @@ -42,7 +42,8 @@ jobs: - name: Checkout code uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # pin@v4 - name: Install rumdl - run: python3 -m pip install --user rumdl==0.2.4 + run: | + python3 -m pip install --user -r requirements-dev.txt - name: Ensure Markdown conventions are upheld run: ~/.local/bin/rumdl check --config .rumdl.toml --respect-gitignore --exclude "build,**/build" . diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000000..31dc6174ee --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,8 @@ +rumdl==0.2.18 \ + --hash=sha256:796720b8756baeebf9a976be0cf619441aa7757e72dd9832f62b752b72f70cdd \ + --hash=sha256:c9c033a722f64b71093c30f795587184321641d612354d1ead75d0145f970148 \ + --hash=sha256:aef55096d0320227fa07bbac049190b63c4a856cfbccee5286517e67c942d6ef \ + --hash=sha256:78bdd91166fa54c30ff1f83648fb1f371b5f25534eb4ec9e0c997b649996faa6 \ + --hash=sha256:c7721883781adfcca7204f2a9d45deacd7a663b0402fb043c240f5b90f36c113 \ + --hash=sha256:fe5c778e7b3e0a0ac5cca891c0668be649a9d228b6d231ed7f59b5726929457e \ + --hash=sha256:17e21e25ee8c95e7a7881585e28eb52c8ccb6c18bda3707eef475b0e221debcc From f960f16a8906a95c22df5aa027fef79c3b241939 Mon Sep 17 00:00:00 2001 From: "Ganyu (Bruce) Xu" Date: Mon, 13 Jul 2026 13:09:16 -0400 Subject: [PATCH 3/3] Add markdown linter to pre-commit hook Signed-off-by: Ganyu (Bruce) Xu --- .githooks/pre-commit | 8 ++++++++ CONTRIBUTING.md | 13 +++++++++++++ 2 files changed, 21 insertions(+) create mode 100755 .githooks/pre-commit diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100755 index 0000000000..eb0c414632 --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,8 @@ +#!/bin/bash + +if ! command -v rumdl >/dev/null 2>&1; then + echo "Error: rumdl not found. Please install using requirements-dev.txt" >&2 + exit 1 +fi + +rumdl check --config .rumdl.toml --respect-gitignore --exclude "build,**/build" . diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5633897d8e..f6a09cf283 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,6 +45,19 @@ LIBOQS_DIR= ./scripts/format_code.sh ``` This script has been tested on x86\_64 Ubuntu and arm64 macOS. Contributions for other platforms are welcome and appreciated! +### Git hooks + +This project uses git hooks to automatically run linters and formatters. Git +hooks are stored under `.githooks/`. After cloning this repository, you can +point git to use these hooks by setting `core.hooksPath`: + +```bash +git config core.hooksPath .githooks +``` + +> `core.hooksPath` is available in git 2.9 or newer; for older versions of git, +> please manually set up symlinks or copy the hooks into `.git/hooks`. + ### Public and internal APIs Public API functions are marked with the `OQS_API` keyword. These functions are made available to users of the library.