From 0137381ecc57fbd213ba271a46164ea121d5528c Mon Sep 17 00:00:00 2001
From: Steve Marshall <steve@stevemarshall.com>
Date: Thu, 24 Aug 2017 12:30:12 +0100
Subject: [PATCH 1/2] Document how we store source code

---
 standards/storing-source-code.md | 37 ++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 standards/storing-source-code.md

diff --git a/standards/storing-source-code.md b/standards/storing-source-code.md
new file mode 100644
index 0000000..3f413ed
--- /dev/null
+++ b/standards/storing-source-code.md
@@ -0,0 +1,37 @@
+---
+expires: 2018-01-31
+---
+# Storing source code
+
+All our source code is open by default, and stored on well-known,
+public code hosting services. At the MOJ, we use GitHub.
+
+We follow the principles set out in the service manual for managing the
+code that we write:
+
+- [use version control](https://www.gov.uk/service-manual/technology/maintaining-version-control-in-coding)
+- [make source code open](https://www.gov.uk/service-manual/technology/making-source-code-open-and-reusable)
+
+You should keep secrets separate from source code, and keep them private.
+
+## GitHub
+
+New repositories for products and services live in the
+[ministryofjustice organisation](https://github.com/ministryofjustice)
+on GitHub.
+
+You can use your personal GitHub account (but you should [add your MOJ
+email address to your account](https://help.github.com/articles/adding-an-email-address-to-your-github-account/),
+and maybe [use that for notifications](https://help.github.com/articles/managing-notification-emails-for-organizations/)).
+Ask the Digital Service Desk or a member of the webops team to add you
+to the organisation. Our GitHub organisation requires that you use
+two-factor authorisation.
+
+Repositories should be clearly named, and have an appropriate licence
+and enough documentation that someone new can get started with the
+project.
+
+If the repository contains secrets rather than code, make it private
+and restrict the people who have access to it. Discuss with the
+security engineering team whether you should encrypt the contents of
+the repository.

From ba078e6f565041a3ae2e1ef7cb8fc5f766866c05 Mon Sep 17 00:00:00 2001
From: Steve Marshall <steve@stevemarshall.com>
Date: Thu, 24 Aug 2017 15:00:37 +0100
Subject: [PATCH 2/2] Autogenerate the list of standards on the homepage

Rather than having to manually manage and update the list of standards
on the homepage, it would be nice if we can get Jekyll to do it for us.

To do that, we first mark everything in `/standards/` as a standard
from Jekyll's config. We can then filter `site.pages` to just get those
items, group them by their `category`, and render the list of standards
with appropriate headings.

Unfortunately, the headings generated here are rendered using Liquid
and so don't render correctly in the table of contents sidebar. This is
because we're unable (so far as I can tell) to parse the Liquid tags
before running `markdownify`. To avoid rendering garbage headings,
then, we apply the [`{:.no_toc}` Kramdown
attribute](https://kramdown.gettalong.org/converter/html.html#toc)
(which excludes them from) the table of contents.

This also adds an appropriate category to `storing-source-code.md`, and
adds an example to the index.
---
 _config.yml                      |  7 +++++++
 index.md                         | 21 +++++++++++++++++++++
 standards/storing-source-code.md |  1 +
 3 files changed, 29 insertions(+)

diff --git a/_config.yml b/_config.yml
index fc8b346..3194f22 100644
--- a/_config.yml
+++ b/_config.yml
@@ -1,3 +1,10 @@
 title: MOJ technical guidance
 
 permalink: pretty
+
+defaults:
+  -
+    scope:
+      path: "standards"
+    values:
+      standard: true
diff --git a/index.md b/index.md
index c968b29..5430bd9 100644
--- a/index.md
+++ b/index.md
@@ -7,6 +7,26 @@ has made for the products we operate.
 It complements the [Service Manual](https://www.gov.uk/service-manual),
 which covers service design more broadly.
 
+## Standards
+
+{% assign standards = site.pages
+  | where: "standard", true
+  | group_by: "category" %}
+
+{% for standard_group in standards %}
+{% if standard_group.name != "" %}
+### {{ standard_group.name }}
+{:.no_toc}
+{% else %}
+### General standards
+{:.no_toc}
+{% endif %}
+
+{% for standard in standard_group.items %}
+- [{{ standard.title }}]({{ standard.url }})
+{% endfor %}
+{% endfor %}
+
 ## Adding new guidance
 
 Create a new Markdown file that follows this pattern, add a link to it
@@ -14,6 +34,7 @@ from this page, and make a pull request:
 
 ```markdown
 ---
+category: The broader area this fits into
 expires: yyyy-mm-dd (6 months from now)
 ---
 # Thing you're writing a standard about
diff --git a/standards/storing-source-code.md b/standards/storing-source-code.md
index 3f413ed..8973888 100644
--- a/standards/storing-source-code.md
+++ b/standards/storing-source-code.md
@@ -1,4 +1,5 @@
 ---
+category: Building software
 expires: 2018-01-31
 ---
 # Storing source code