KEH Template Repository

This repository is a template for all new Knowledge Exchange Hub (KEH) repositories. It contains the basic structure and files that are common to all KEH repositories, such as CODEOWNERS, sample GitHub Actions workflows, and a README template.

Usage

Creating a New Repository

To use this template when creating a new repository, simply select "Use this template" on GitHub and follow the prompts to create your new repository based on this template. This will ensure that your new repository has the necessary structure and files to maintain consistency across all KEH repositories.

Further Setup

Since this repository is intended for all KEH repositories, it needs some additional setup once you have created your new repository. The steps below outline the necessary customisation and setup:

1. Update the README: Replace the content of the README with information relevant to your project. This should use the template below as a starting point.
2. Update CODEOWNERS: Modify the CODEOWNERS file to chose the appropriate team. The 2 options for KEH are within the file itself.
3. Set up GitHub Actions: This repository has already setup some sample GitHub Actions workflows (i.e. MkDocs related actions and Megalinter). In addition to this, the repository should also have its primary language linter and test workflow set up. Placeholders for these workflows are already in place, so you just need to fill in the details (ci-fmt, ci-test).
4. Setup Repository Settings: The repository should have the following settings configured:
   1. Contributors:
      1. Add keh-dev to the repository with Write access.
      2. Add keh-dev-admin to the repository with Admin access.
   2. Branch Protection Rules:
      1. Within Rules > Rulesets, create a new branch ruleset for the main branch.
      2. Add the following rules to the ruleset:
         1. Add keh-dev-admin to the Bypass List. This is for emergency situations where you need to bypass branch protection rules.
         2. Target the Default Branch (main).
         3. Restrict deletions.
         4. Require a pull request before merging. This should require at least 2 approving reviews.
         5. Block force pushes.
      3. Save the ruleset.
5. Setup Repository for Project Use: Now that the housekeeping is done, you can set up the repository for project use.

Python Specific Setup

When using Python, Poetry has already been setup for dependency management since it is used for documentation.

Ensure that you update the pyproject.toml file to match the needs of your project.

README Template

The below is a template for the README file that should be used for all KEH repositories. This template provides a basic structure and can be customised to fit the specific needs of your project.

Everything above this line should be removed when customising the README for your project.

---

Project Name

Table of Contents

Prerequisites

Makefile

This project uses a Makefile to simplify common tasks. To see the available commands, run:

make all

Running the Project

Deployment

Deployments with Concourse

Manual Deployment

Documentation

This repository uses MkDocs for documentation. The documentation source files are located in the docs directory.

GitHub Actions for Documentation

MkDocs gets deployed to GitHub Pages using GitHub Actions. The workflow for this is located at .github/workflows/deploy-docs.yml. Before deployment, another GitHub Action workflow runs to check that the documentation builds correctly and has no linting or formatting issues. This workflow is located at .github/workflows/ci-docs.yml.

Local Development of Documentation

To run the documentation locally:

1. Install the dependencies for MkDocs.

   poetry install --only docs

2. Run the MkDocs development server.

   poetry run mkdocs serve

Linting and Testing

GitHub Actions

This repository has GitHub Actions workflows set up for linting and testing. The workflows are located at:

• .github/workflows/ci-fmt.yml for linting and formatting checks (primary language).
• .github/workflows/ci-test.yml for running automated tests.
• .github/workflows/ci-docs.yml for checking that the documentation builds correctly and has no linting or formatting issues.
• .github/workflows/megalinter.yml for running MegaLinter, which checks for linting and formatting issues across multiple languages and file types (this is a catch-all linter).
• .github/workflows/deploy-docs.yml for deploying documentation to GitHub Pages.

Running Tests and Linters Locally

Primary Language

MegaLinter

This repository uses MegaLinter for comprehensive linting across multiple languages and file types. We use this so that all additional assets in the repository (e.g. YAML files, Markdown files, etc.) are also linted and checked for formatting issues, without having to set up specific linters for each file type.

To run MegaLinter locally, you can use the following command:

docker run --platform linux/amd64 --rm \
    -v /var/run/docker.sock:/var/run/docker.sock:rw \
    -v $(shell pwd):/tmp/lint:rw \
    oxsecurity/megalinter:v8

Documentation linting and building

This repository uses Markdownlint for linting the documentation. To run Markdownlint locally, you can use the following:

1. Install the dependencies for Markdownlint.

   npm install -g markdownlint-cli

2. Run Markdownlint.

   markdownlint .

   (Optional) Add the --fix flag to automatically fix any linting issues that can be fixed.

   markdownlint . --fix

To test that the documentation builds correctly, you can use the following command:

poetry run mkdocs build

Note: This depends on MkDocs being set up for the repository. Instructions for setting up MkDocs can be found in the Documentation section of this README.