Developing the Data Platform

This guide will help you set up your development environment, including GitHub and your local machine.

Repository Standards

All our repositories include a development container configuration. Usage is mandatory for our engineering teams as it provides an isolated environment for each project with the required tooling and configuration for consistent development.

Additionally, all our repositories include a baseline set of GitHub Actions:

• CodeQL Analysis
• Dependency Review
• OpenSSF Scorecard (only if it’s a public repository)
• pre-commit Updater
• Spell Check
• Super Linter
• Zizmor

They also include the following supporting configuration:

The contents of these files may differ by repository, depending on the programming languages or frameworks used.

• .editorconfig
• .pre-commit-config.yaml
• .prettierignore
• cspell.json

We require Git commit signing for all repositories.

GitHub Setup

You’ll need to create your own GitHub account. Follow GitHub’s documentation if you don’t already have one.

In accordance with GitHub’s Terms of Service, don’t create multiple accounts.

The Ministry of Justice doesn’t provision or manage your GitHub account.

We can’t assist in recovering your account, so you must take measures to ensure you can recover it without our support. These include:

• Saving your 2FA recovery codes
• Having a valid personal recovery email address associated with your account

After creating a GitHub account, join the Ministry of Justice’s GitHub organisation.

During your onboarding, you’ll be added to the appropriate teams via ministryofjustice/data-platform-access.

Machine Setup

This documentation applies only to macOS.

Requirements

Most required software is available via Homebrew, but that’s outside the scope of this document.

• 1Password
  • Available in the Self Service app
• Visual Studio Code
  • Available in the Self Service app
• Dev Containers extension (ms-vscode-remote.remote-containers)
  • Available in the Visual Studio Code Marketplace (Dev Containers extension)
• Docker Desktop
  • Available from Docker (Docker Desktop for Mac)
• GitHub CLI
  • Available from GitHub (GitHub CLI)

SSH Setup

We recommend using 1Password to manage SSH keys.

You can manage SSH credentials locally on macOS or via 1Password:

• macOS

  • Generating a new SSH key and adding it to the ssh-agent
  • Adding a new SSH key to your GitHub account
  • SSH commit signature verification

• 1Password

  • Request access via Operations Engineering
  • Follow 1Password’s “Getting started” documentation to complete the setup

Once you’ve configured SSH, you can authenticate with GitHub and sign your commits.

GitHub CLI Setup

To authenticate the GitHub CLI with your GitHub account, run the following command:

gh auth login --git-protocol ssh --hostname github.com --skip-ssh-key --web

Follow the prompts to complete authentication.

Interacting with Repositories

Cloning Repositories

You can clone repositories using the GitHub CLI or Git directly. Using the GitHub CLI:

gh repo clone ministryofjustice/data-platform

or using Git:

git clone git@github.com:ministryofjustice/data-platform.git

Once you’ve cloned a repository, open it in Visual Studio Code. You’ll be prompted to reopen the folder in a development container.

For example:

Open in Dev Container

Alternatively, you can open a repository directly in a development container using the “Open in Dev Container” button found in each repository’s readme.

For example:

To reopen a closed development container, you can either:

• Use the Command Palette (Cmd+Shift+P), run “Remote Explorer: Focus on Dev Containers View”, then Option+click the container and select the arrow icon to open it.
• Use the “Open in Dev Container” button in the readme again.

Development Workflow

We follow GitHub flow, a branch-based development workflow. For more information, refer to GitHub’s documentation on GitHub flow.

Pull Requests

While working on a task, you can create a pull request in draft mode to solicit early feedback and collaboration.

When your work’s ready for review, convert the pull request from draft to ready for review. Ensure that all checks pass and that you’ve addressed any feedback before merging.

Provide a clear and concise description of the changes in the pull request, along with relevant context or screenshots. The pull request title should accurately reflect the changes.

Each repository may have its own contributing guidelines, so make sure to review those too.

AI Assisted Coding

The Ministry of Justice has enabled GitHub Copilot Enterprise. You can request access via this form.

There’s published guidance on using GitHub Copilot that you should read and understand before using these tools.

Microsoft also publish guidance on using GitHub Copilot in Visual Studio Code.