This repository contains best-practice guidance and - where appropriate - policy for Ministry of Justice (MoJ) technology security.
The information ranges from formal content, such as 'you must'-style documents, through to more informal help and suggestions, such as checklists.
The content is used to help build and operate products and services at the MoJ.
The work is performed in the open by intent, and for compliance with principle. There is no specific aim or expectation of re-use of these materials outside of MoJ purposes - but people are welcome to do so if they wish in accordance with the published license.
Note: As a vibrant, dynamic, work-in progress, this material should not necessarily be treated as formal, finished, definitive, or accurate.
This repo is inspired by, and borrows from, GDS's technical guidance site and MoJ's technical guidance.
Content in the main
branch is created in DITA format, and stored in the dita
directory. When a build is required, the builder.ant
script in the buildUtils
directory is run. By default, it creates Markdown, PDF, and EPUB format output. The result output documents are put into a clean docs
directory.
Content in the docs
directory can be built and previewed using Jekyll, and hosted using GitHub Pages. It incorporates HTML, SCSS, JavaScript, and images from GDS's Tech Docs Template, reworked to use Jekyll instead of Middleman.
All commits must be signed.
Information about contributing is provided here.
To preview the site locally, we need to use the terminal.
Install Ruby and Bundler, preferably with a Ruby version manager.
Once you have Ruby and Bundler set up, you can install this project's dependencies by running the following in this directory:
bundle install
The correct way to make changes is by editing the appropriate DITA XML files in the dita
directory. The builder.ant
script in the buildUtils
directory is used to create output content from the DITA source.
Any changes you want to suggest must be created in a branch, and submitted using a pull request when you want them to be reviewed and potentially published.
The tolerated way of making changes is by editing an existing Markdown file in the docs
directory. Be aware that changes made in the docs
directory are non-persistent, and are overwritten by the build process.
We can preview content in the docs
directory, locally, by running this command:
bundle exec jekyll serve --watch
This will create a local web server, probably at http://127.0.0.1:4000
(look for the Server address:
line). This is only accessible on our
own computer, and won't be accessible to anyone else. It's also set up
to automatically update (thanks to --watch
) when we make changes to
the working Markdown files.
Because we're using GitHub Pages, any changes merged into the main
branch docs
directory will be published automatically. Every change should be reviewed
in a pull request, no matter how minor, and we've enabled branch protection to enforce this.
Every time a build run takes place, a working copy of the Intranet material is placed in the intranet folder.
Whenever an Intranet publication is required, the following process is used:
- Create an annotated tag for the repository, using the following template:
git tag -a YYYYMMDD -m "Intranet Snapshot YYYYMMDD"
The YYYYMMDD is the date of the snapshot. For example:git tag -a 20210205 -m "Intranet Snapshot 20210205"
- Upload the tag into GitHub, using the following template:
git push origin YYYYMMDD
For example:git push origin 20210205
- Create a
.zip
file containing the contents of theintranet
folder. - Submit the zip file to the Comms team for publication.
To get a list of the annotated tags, use the command:
git show