chore: add dev instructions + megalinter tweaks

.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

.mega-linter.yml

@@ -24,6 +24,7 @@ DISABLE:
   - SPELL
 
 DISABLE_LINTERS:
+  - REPOSITORY_GITLEAKS # Superseded by REPOSITORY_BETTERLEAKS
   - REPOSITORY_DEVSKIM
   - REPOSITORY_TRUFFLEHOG
   - REPOSITORY_GIT_DIFF
@@ -42,3 +43,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/**"

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.

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]
+>
+> 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:
+
+```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.

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:

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
@@ -152,9 +155,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)

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

project_template/.prettierignore

@@ -0,0 +1 @@
+.copier-answers.yml

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.

project_template/README.md.jinja

@@ -158,15 +158,28 @@ configured using the `.mega-linter.yml` file.
 
 To run MegaLinter, ensure you have **Docker** installed on your system.
 
-> 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]
+>
+> 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:
 
 ```bash
 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.