From 91b393b3d08d4c385a1d0a79968a411a63e0943b Mon Sep 17 00:00:00 2001 From: Mebin Abraham Date: Thu, 16 Jul 2026 18:31:47 +0100 Subject: [PATCH 1/7] chore: add dev instructions --- Makefile | 5 +- README.md | 95 +++++++++++++++++++++++++++++--- project_template/Makefile.jinja | 5 +- project_template/README.md.jinja | 13 +++++ 4 files changed, 106 insertions(+), 12 deletions(-) diff --git a/Makefile b/Makefile index b69f9bd..1177efa 100644 --- a/Makefile +++ b/Makefile @@ -38,11 +38,12 @@ install-dev: ## Install the dependencies including dev. poetry install .PHONY: megalint -megalint: ## Run the mega-linter. +megalint: ## Run the mega-linter. Use LINTER=NAME to run only one. docker run --platform linux/amd64 --rm \ -v /var/run/docker.sock:/var/run/docker.sock:rw \ -v $(shell pwd):/tmp/lint:rw \ - oxsecurity/megalinter:v9 + $(if $(LINTER),-e ENABLE_LINTERS=$(LINTER),) \ + ghcr.io/oxsecurity/megalinter:v9 .PHONY: update-template-packages update-template-packages: ## Refresh package-manager template files and lockfiles. diff --git a/README.md b/README.md index e382e66..16df160 100644 --- a/README.md +++ b/README.md @@ -429,21 +429,34 @@ There are many alternatives to the tools used in this template, and you may pref - Integrate with the ONS Software Developer Portal. - Ability to update the project with the latest template changes. +--- + ## Development -:TODO: Add instructions for development +Get started with development by running the following commands. +A Makefile is provided to simplify common development tasks. To view all available commands, run: -### Maintainer Commands +```bash +make +``` -Use `make update-template-packages` when you need to refresh the package-manager-specific template files under -`project_template/` after changing the dependency sets or package-manager template configuration. +### Installation -This command regenerates the managed package files for Poetry, Pipenv, and uv, including the lockfiles copied into the -template. It requires the relevant package-manager CLIs to be installed locally: `poetry`, `pipenv`, and `uv`. +Install all dependencies including dev: + +```bash +make install-dev +``` + +Install only production dependencies: + +```bash +make install +``` -### Pre-commit hooks +### Pre-commit Hooks -This repository includes a `.pre-commit-config.yaml` for lightweight repository checks and Python linting with Ruff. +This repository includes a `.pre-commit-config.yaml` for repository hygiene checks and Python linting with Ruff. Install the hooks locally with: @@ -457,6 +470,72 @@ Run the full hook set on demand with: make pre-commit ``` +### Run Tests + +The unit tests are written using the [pytest](https://docs.pytest.org/en/stable/) framework. To run the tests, run: + +```bash +make test +``` + +### Linting and Formatting + +Various tools are used to lint and format the code in this project. + +#### Python + +The project uses [Ruff](https://github.com/astral-sh/ruff) and [pylint](https://pylint.pycqa.org/en/latest/index.html) +for linting and formatting of the Python code. The tools are configured using `pyproject.toml`. + +To lint the Python code, run: + +```bash +make lint +``` + +To auto-format the Python code and fix linting issues, run: + +```bash +make format +``` + +#### MegaLinter (non-Python files) + +[MegaLinter](https://github.com/oxsecurity/megalinter) is used to lint non-Python files in the project (YAML, GitHub +Actions, Shell scripts, etc.). It is configured using `.mega-linter.yml`. + +To run MegaLinter, ensure you have **Docker** installed on your system. + +> Note: If you use Colima for Docker on macOS, run `colima start --edit` and +> set `mountType: virtiofs` in the profile YAML so bind mounts work correctly +> with `make megalint`. + +> Note: The initial run may take some time to download the Docker image. Subsequent executions will be considerably +> faster due to Docker caching. + +To start the linter and automatically fix fixable issues, run: + +```bash +make megalint +``` + +To run only a specific linter, pass the `LINTER` variable: + +```bash +make megalint LINTER=YAML_YAMLLINT +``` + +This maps to MegaLinter's `ENABLE_LINTERS` environment variable. See the +[supported linters list](https://megalinter.io/latest/supported-linters/) for valid names. + +### Maintainer Commands + +Use `make update-template-packages` when you need to refresh the package-manager-specific template files under +`project_template/` after changing the dependency sets or package-manager template configuration. + +This command regenerates the managed package files for Poetry, Pipenv, and uv, including the lockfiles copied into the +template. It requires the relevant package-manager CLIs to be installed locally: `poetry`, `pipenv`, and `uv`. + ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for details. diff --git a/project_template/Makefile.jinja b/project_template/Makefile.jinja index df44558..09d7b0a 100644 --- a/project_template/Makefile.jinja +++ b/project_template/Makefile.jinja @@ -67,11 +67,12 @@ install-dev: ## Install the dependencies including dev. {%- endif %} .PHONY: megalint -megalint: ## Run the mega-linter. +megalint: ## Run the mega-linter. Use LINTER=NAME to run only one. docker run --platform linux/amd64 --rm \ -v /var/run/docker.sock:/var/run/docker.sock:rw \ -v $(shell pwd):/tmp/lint:rw \ - oxsecurity/megalinter:v9 + $(if $(LINTER),-e ENABLE_LINTERS=$(LINTER),) \ + ghcr.io/oxsecurity/megalinter:v9 {% if enable_copier_updates %} .PHONY: copier-update copier-update: ## Update the project using the initial copier template. diff --git a/project_template/README.md.jinja b/project_template/README.md.jinja index c7cd317..19b8c4f 100644 --- a/project_template/README.md.jinja +++ b/project_template/README.md.jinja @@ -158,6 +158,10 @@ configured using the `.mega-linter.yml` file. To run MegaLinter, ensure you have **Docker** installed on your system. +> Note: If you use Colima for Docker on macOS, run `colima start --edit` and +> set `mountType: virtiofs` in the profile YAML so bind mounts work correctly +> with `make megalint`. + > Note: The initial run may take some time to download the Docker image. However, subsequent executions will be > considerably faster due to Docker caching. :rocket: @@ -167,6 +171,15 @@ To start the linter and automatically rectify fixable issues, run: make megalint ``` +To run only a specific linter, pass `LINTER` variable: + +```bash +make megalint LINTER=YAML_YAMLLINT +``` + +This maps to MegaLinter's `ENABLE_LINTERS` environment variable. See the +[supported linters list](https://megalinter.io/latest/supported-linters/) for valid names. + ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for details. From b365978b6add26f27ca288793db87c99b3c07f19 Mon Sep 17 00:00:00 2001 From: Mebin Abraham Date: Thu, 16 Jul 2026 18:49:14 +0100 Subject: [PATCH 2/7] fix: lint --- README.md | 4 ++-- project_template/.github/workflows/ci.yml.jinja | 3 +++ project_template/README.md.jinja | 6 +++--- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 16df160..66fa7d1 100644 --- a/README.md +++ b/README.md @@ -509,9 +509,9 @@ To run MegaLinter, ensure you have **Docker** installed on your system. > Note: If you use Colima for Docker on macOS, run `colima start --edit` and > set `mountType: virtiofs` in the profile YAML so bind mounts work correctly > with `make megalint`. - +> --- > Note: The initial run may take some time to download the Docker image. Subsequent executions will be considerably -> faster due to Docker caching. +> faster due to Docker caching. :rocket: To start the linter and automatically fix fixable issues, run: diff --git a/project_template/.github/workflows/ci.yml.jinja b/project_template/.github/workflows/ci.yml.jinja index 235dfc4..a45bc8f 100644 --- a/project_template/.github/workflows/ci.yml.jinja +++ b/project_template/.github/workflows/ci.yml.jinja @@ -1,5 +1,8 @@ --- name: CI +permissions: + contents: read + pull-requests: write on: # yamllint disable-line rule:truthy push: diff --git a/project_template/README.md.jinja b/project_template/README.md.jinja index 19b8c4f..f1905bb 100644 --- a/project_template/README.md.jinja +++ b/project_template/README.md.jinja @@ -161,9 +161,9 @@ To run MegaLinter, ensure you have **Docker** installed on your system. > Note: If you use Colima for Docker on macOS, run `colima start --edit` and > set `mountType: virtiofs` in the profile YAML so bind mounts work correctly > with `make megalint`. - -> Note: The initial run may take some time to download the Docker image. However, subsequent executions will be -> considerably faster due to Docker caching. :rocket: +> --- +> Note: The initial run may take some time to download the Docker image. Subsequent executions will be considerably +> faster due to Docker caching. :rocket: To start the linter and automatically rectify fixable issues, run: From 8d7782adbf5be084df92e540e3eadc339948ac7b Mon Sep 17 00:00:00 2001 From: Mebin Abraham Date: Thu, 16 Jul 2026 19:28:15 +0100 Subject: [PATCH 3/7] fix: lint --- .mega-linter.yml | 4 ++++ README.md | 12 ++++++------ project_template/.github/workflows/mega-linter.yml | 7 +++++-- project_template/README.md.jinja | 11 +++++------ 4 files changed, 20 insertions(+), 14 deletions(-) diff --git a/.mega-linter.yml b/.mega-linter.yml index 9aee88c..78e7b9b 100644 --- a/.mega-linter.yml +++ b/.mega-linter.yml @@ -42,3 +42,7 @@ YAML_V8R_FILTER_REGEX_EXCLUDE: "dependabot.yml" # Dependabot yaml in SchemaStore # This whitelists GITHUB_TOKEN so zizmor can authenticate with the GitHub API to resolve the uses: clauses in our workflow files. ACTION_ZIZMOR_UNSECURED_ENV_VARIABLES: - GITHUB_TOKEN + +REPOSITORY_KINGFISHER_ARGUMENTS: + - --exclude + - "**/.venv/**" diff --git a/README.md b/README.md index 66fa7d1..208158d 100644 --- a/README.md +++ b/README.md @@ -506,12 +506,12 @@ Actions, Shell scripts, etc.). It is configured using `.mega-linter.yml`. To run MegaLinter, ensure you have **Docker** installed on your system. -> Note: If you use Colima for Docker on macOS, run `colima start --edit` and -> set `mountType: virtiofs` in the profile YAML so bind mounts work correctly -> with `make megalint`. -> --- -> Note: The initial run may take some time to download the Docker image. Subsequent executions will be considerably -> faster due to Docker caching. :rocket: +> [!NOTE] +> +> 1. If you use Colima for Docker on macOS, run `colima start --edit` and set `mountType: virtiofs` in the profile YAML +> so that bind mounts work correctly with `make megalint`. +> 2. The initial run may take some time while the Docker image is downloaded. +> Subsequent runs will be considerably faster due to Docker caching. 🚀 To start the linter and automatically fix fixable issues, run: diff --git a/project_template/.github/workflows/mega-linter.yml b/project_template/.github/workflows/mega-linter.yml index 3a1e131..600e924 100644 --- a/project_template/.github/workflows/mega-linter.yml +++ b/project_template/.github/workflows/mega-linter.yml @@ -152,9 +152,12 @@ jobs: github.event.pull_request.head.repo.full_name == github.repository ) && !contains(github.event.head_commit.message, 'skip fix') + env: + PR_NUMBER: ${{ steps.cpr.outputs.pull-request-number }} + PR_URL: ${{ steps.cpr.outputs.pull-request-url }} run: | - echo "PR Number - ${{ steps.cpr.outputs.pull-request-number }}" - echo "PR URL - ${{ steps.cpr.outputs.pull-request-url }}" + echo "PR Number - $PR_NUMBER" + echo "PR URL - $PR_URL" # Push new commit if applicable # (for now works only on PR from same repository, not from forks) diff --git a/project_template/README.md.jinja b/project_template/README.md.jinja index f1905bb..2e30f68 100644 --- a/project_template/README.md.jinja +++ b/project_template/README.md.jinja @@ -158,12 +158,11 @@ configured using the `.mega-linter.yml` file. To run MegaLinter, ensure you have **Docker** installed on your system. -> Note: If you use Colima for Docker on macOS, run `colima start --edit` and -> set `mountType: virtiofs` in the profile YAML so bind mounts work correctly -> with `make megalint`. -> --- -> Note: The initial run may take some time to download the Docker image. Subsequent executions will be considerably -> faster due to Docker caching. :rocket: +> [!NOTE] +> 1. If you use Colima for Docker on macOS, run `colima start --edit` and set `mountType: virtiofs` in the profile YAML +> so that bind mounts work correctly with `make megalint`. +> 2. The initial run may take some time while the Docker image is downloaded. +> Subsequent runs will be considerably faster due to Docker caching. 🚀 To start the linter and automatically rectify fixable issues, run: From 249f27d8288be38234f930afa78f8804e680726d Mon Sep 17 00:00:00 2001 From: Mebin Abraham Date: Thu, 16 Jul 2026 19:35:58 +0100 Subject: [PATCH 4/7] feat: run megalinter across 4 cores --- .github/workflows/mega-linter.yml | 3 +++ project_template/.github/workflows/mega-linter.yml | 3 +++ 2 files changed, 6 insertions(+) diff --git a/.github/workflows/mega-linter.yml b/.github/workflows/mega-linter.yml index 600e924..54f7866 100644 --- a/.github/workflows/mega-linter.yml +++ b/.github/workflows/mega-linter.yml @@ -40,6 +40,9 @@ env: # Set to simple to avoid external images in generated markdown REPORTERS_MARKDOWN_TYPE: simple + # Run MegaLinter in parallel to speed up the process. GH hosted runners have 4 CPU cores. + PARALLEL_PROCESS_NUMBER: 4 + concurrency: group: "${{ github.head_ref || github.ref }}-${{ github.workflow }}" cancel-in-progress: true diff --git a/project_template/.github/workflows/mega-linter.yml b/project_template/.github/workflows/mega-linter.yml index 600e924..54f7866 100644 --- a/project_template/.github/workflows/mega-linter.yml +++ b/project_template/.github/workflows/mega-linter.yml @@ -40,6 +40,9 @@ env: # Set to simple to avoid external images in generated markdown REPORTERS_MARKDOWN_TYPE: simple + # Run MegaLinter in parallel to speed up the process. GH hosted runners have 4 CPU cores. + PARALLEL_PROCESS_NUMBER: 4 + concurrency: group: "${{ github.head_ref || github.ref }}-${{ github.workflow }}" cancel-in-progress: true From 3a6c2d922f78b97b5c465626b40809559e219079 Mon Sep 17 00:00:00 2001 From: Mebin Abraham Date: Thu, 16 Jul 2026 20:06:20 +0100 Subject: [PATCH 5/7] fix: prettierignore generated file --- project_template/.github/linters/.prettierignore | 1 + project_template/README.md.jinja | 1 + 2 files changed, 2 insertions(+) create mode 100644 project_template/.github/linters/.prettierignore diff --git a/project_template/.github/linters/.prettierignore b/project_template/.github/linters/.prettierignore new file mode 100644 index 0000000..d2bafae --- /dev/null +++ b/project_template/.github/linters/.prettierignore @@ -0,0 +1 @@ +.copier-answers.yml diff --git a/project_template/README.md.jinja b/project_template/README.md.jinja index 2e30f68..5a964a5 100644 --- a/project_template/README.md.jinja +++ b/project_template/README.md.jinja @@ -159,6 +159,7 @@ configured using the `.mega-linter.yml` file. To run MegaLinter, ensure you have **Docker** installed on your system. > [!NOTE] +> > 1. If you use Colima for Docker on macOS, run `colima start --edit` and set `mountType: virtiofs` in the profile YAML > so that bind mounts work correctly with `make megalint`. > 2. The initial run may take some time while the Docker image is downloaded. From b601daa55732b6c6efd6e94da24bf2f863f8d5a2 Mon Sep 17 00:00:00 2001 From: Mebin Abraham Date: Thu, 16 Jul 2026 20:12:16 +0100 Subject: [PATCH 6/7] chore: disable gitleak infavour of betterleaks --- .mega-linter.yml | 1 + project_template/.mega-linter.yml | 1 + 2 files changed, 2 insertions(+) diff --git a/.mega-linter.yml b/.mega-linter.yml index 78e7b9b..5ca03d6 100644 --- a/.mega-linter.yml +++ b/.mega-linter.yml @@ -24,6 +24,7 @@ DISABLE: - SPELL DISABLE_LINTERS: + - REPOSITORY_GITLEAKS # Superseded by REPOSITORY_BETTERLEAKS - REPOSITORY_DEVSKIM - REPOSITORY_TRUFFLEHOG - REPOSITORY_GIT_DIFF diff --git a/project_template/.mega-linter.yml b/project_template/.mega-linter.yml index 9aee88c..62f4864 100644 --- a/project_template/.mega-linter.yml +++ b/project_template/.mega-linter.yml @@ -24,6 +24,7 @@ DISABLE: - SPELL DISABLE_LINTERS: + - REPOSITORY_GITLEAKS # Superseded by REPOSITORY_BETTERLEAKS - REPOSITORY_DEVSKIM - REPOSITORY_TRUFFLEHOG - REPOSITORY_GIT_DIFF From 1b50cbda83d160b11658321a05b7cef1d5e96fe1 Mon Sep 17 00:00:00 2001 From: Mebin Abraham Date: Thu, 16 Jul 2026 22:11:53 +0100 Subject: [PATCH 7/7] fix: correct prettierignore location --- project_template/{.github/linters => }/.prettierignore | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename project_template/{.github/linters => }/.prettierignore (100%) diff --git a/project_template/.github/linters/.prettierignore b/project_template/.prettierignore similarity index 100% rename from project_template/.github/linters/.prettierignore rename to project_template/.prettierignore