way_of_working-for-hdi 1.0.0

data/docs/_config.yml

@@ -0,0 +1,90 @@
+---
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole blog, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
+#
+# If you need help with YAML syntax, here are some quick references for you:
+# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
+# https://learnxinyminutes.com/docs/yaml/
+#
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+
+title: HDI Way Of Working
+# email: your-email@example.com
+# description: >- # this means to ignore newlines until "baseurl:"
+#   Write an awesome description for your new site here. You can edit this
+#   line in _config.yml. It will appear in your document head meta (for
+#   Google search results) and in your feed.xml site description.
+# baseurl: "" # the subpath of your site, e.g. /blog
+# url: "" # the base hostname & protocol for your site, e.g. http://example.com
+# twitter_username: jekyllrb
+# github_username:  jekyll
+
+# Build settings
+remote_theme: just-the-docs/just-the-docs@v0.4.0
+plugins:
+  - jekyll-feed
+
+# Exclude from processing.
+# The following items will not be processed, by default.
+# Any item listed under the `exclude:` key here will be automatically added to
+# the internal "default list".
+#
+# Excluded items can be processed by explicitly listing the directories or
+# their entries' file path in the `include:` list.
+#
+exclude:
+  - decisions/adr-template.md
+#   - .sass-cache/
+#   - .jekyll-cache/
+#   - gemfiles/
+#   - Gemfile
+#   - Gemfile.lock
+#   - node_modules/
+#   - vendor/bundle/
+#   - vendor/cache/
+#   - vendor/gems/
+#   - vendor/ruby/
+
+color_scheme: hdi-light
+
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
+aux_links:
+  "HDI Way of Working on GitHub":
+    - "//github.com/healthdatainsight/way_of_working-for-hdi"
+
+favicon_ico: "https://healthdatainsight.org.uk/wp-content/uploads/2020/11/cropped-hdi-favicon-1-32x32.png"
+search_enabled: false
+
+# Footer
+gh_edit_link: true # show or hide edit this page link
+gh_edit_link_text: "Edit this page on GitHub."
+gh_edit_repository: "https://github.com/healthdatainsight/way_of_working-for-hdi" # the github URL for your repo
+gh_edit_branch: main
+gh_edit_source: docs
+gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately

data/docs/_includes/components/sidebar.html

@@ -0,0 +1,69 @@
+<div class="side-bar">
+  <div class="site-header">
+    <a href="{{ '/' | relative_url }}" class="site-title lh-tight">{% include title.html %}</a>
+    <a href="#" id="menu-button" class="site-button" aria-label="Open the menu">
+      <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg>
+    </a>
+  </div>
+  <nav aria-label="Main" id="site-nav" class="site-nav">
+    {% assign pages_top_size = site.html_pages
+          | where_exp:"item", "item.title != nil"
+          | where_exp:"item", "item.parent == nil"
+          | where_exp:"item", "item.nav_exclude != true"
+          | size %}
+    {% if pages_top_size > 0 %}
+      {% include nav.html pages=site.html_pages key=nil %}
+    {% endif %}
+    {%- if site.nav_external_links -%}
+      <ul class="nav-list">
+        {%- for node in site.nav_external_links -%}
+          <li class="nav-list-item external">
+            <a href="{{ node.url | absolute_url }}" class="nav-list-link external">
+              {{ node.title }}
+              {% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
+            </a>
+          </li>
+        {%- endfor -%}
+      </ul>
+    {%- endif -%}
+    {% if site.just_the_docs.collections %}
+      {% assign collections_size = site.just_the_docs.collections | size %}
+      {% for collection_entry in site.just_the_docs.collections %}
+        {% assign collection_key = collection_entry[0] %}
+        {% assign collection_value = collection_entry[1] %}
+        {% assign collection = site[collection_key] %}
+        {% if collection_value.nav_exclude != true %}
+          {% if collections_size > 1 or pages_top_size > 0 %}
+            {% if collection_value.nav_fold == true %}
+              <ul class="nav-list nav-category-list">
+                <li class="nav-list-item{% if page.collection == collection_key %} active{% endif %}">
+                  {%- if collection.size > 0 -%}
+                  <a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
+                  {%- endif -%}
+                  <div class="nav-category">{{ collection_value.name }}</div>
+                  {% include nav.html pages=collection key=collection_key %}
+                </li>
+              </ul>
+            {% else %}
+              <div class="nav-category">{{ collection_value.name }}</div>
+              {% include nav.html pages=collection key=collection_key %}
+            {% endif %}
+          {% else %}
+            {% include nav.html pages=collection key=collection_key %}
+          {% endif %}
+        {% endif %}
+      {% endfor %}
+    {% endif %}
+  </nav>
+
+  {% capture nav_footer_custom %}
+    {%- include nav_footer_custom.html -%}
+  {% endcapture %}
+  {% if nav_footer_custom != "" %}
+    {{ nav_footer_custom }}
+  {% else %}
+    <footer class="site-footer">
+      This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.
+    </footer>
+  {% endif %}
+</div>

data/docs/_includes/footer_custom.html

@@ -0,0 +1,3 @@
+<p class="text-small mb-0">
+  Copyright &copy; 2023-2025 Health Data Insight CIC. Distributed by an <a href="https://github.com/healthdatainsight/way_of_working-for-hdi/tree/main/LICENSE.txt">MIT license.</a>
+</p>

data/docs/_sass/color_schemes/hdi-light.scss

@@ -0,0 +1,31 @@
+@import "../custom/a11y-colours";
+
+$body-background-color: $white;
+$body-heading-color: $a11y-darker-grey;
+$body-text-color: $a11y-dark-grey;
+$link-color: $a11y-purple;
+$nav-child-link-color: $grey-dk-100;
+$sidebar-color: $grey-lt-000;
+// $base-button-color: #f7f7f7;
+// $btn-primary-color: $purple-100;
+$code-background-color: $a11y-light-grey;
+$feedback-color: darken($sidebar-color, 3%);
+// $table-background-color: $white;
+// $search-background-color: $white;
+// $search-result-preview-color: $grey-dk-000;
+
+// $body-background-color: $white;
+// $body-heading-color: red;
+// $body-text-color: red;
+// $link-color: red;
+// $nav-child-link-color: red;
+// $sidebar-color: yellow;
+// // $base-button-color: #f7f7f7;
+// // $btn-primary-color: $purple-100;
+// $code-background-color: orange;
+// $feedback-color: red;
+// $table-background-color: red;
+// $search-background-color: red;
+// $search-result-preview-color: red;
+
+// @import "./vendor/OneLightJekyll/syntax";

data/docs/_sass/custom/OneDarkJekyll.scss

@@ -0,0 +1,203 @@
+// Generated with OneDarkJekyll applied to Atom's One Dark Vivid theme
+/* stylelint-disable rule-empty-line-before */
+
+.highlight,
+pre.highlight {
+  background: #31343f;
+  color: #dee2f7;
+}
+.highlight pre {
+  background: #31343f;
+}
+.highlight .hll {
+  background: #31343f;
+}
+.highlight .c {
+  color: #63677e;
+  font-style: italic;
+}
+.highlight .err {
+  color: #960050;
+  background-color: #1e0010;
+}
+.highlight .k {
+  color: #e19ef5;
+}
+.highlight .l {
+  color: #a3eea0;
+}
+.highlight .n {
+  color: #dee2f7;
+}
+.highlight .o {
+  color: #dee2f7;
+}
+.highlight .p {
+  color: #dee2f7;
+}
+.highlight .cm {
+  color: #63677e;
+  font-style: italic;
+}
+.highlight .cp {
+  color: #63677e;
+  font-style: italic;
+}
+.highlight .c1 {
+  color: #63677e;
+  font-style: italic;
+}
+.highlight .cs {
+  color: #63677e;
+  font-style: italic;
+}
+.highlight .ge {
+  font-style: italic;
+}
+.highlight .gs {
+  font-weight: 700;
+}
+.highlight .kc {
+  color: #e19ef5;
+}
+.highlight .kd {
+  color: #e19ef5;
+}
+.highlight .kn {
+  color: #e19ef5;
+}
+.highlight .kp {
+  color: #e19ef5;
+}
+.highlight .kr {
+  color: #e19ef5;
+}
+.highlight .kt {
+  color: #e19ef5;
+}
+.highlight .ld {
+  color: #a3eea0;
+}
+.highlight .m {
+  color: #eddc96;
+}
+.highlight .s {
+  color: #a3eea0;
+}
+.highlight .na {
+  color: #eddc96;
+}
+.highlight .nb {
+  color: #fdce68;
+}
+.highlight .nc {
+  color: #fdce68;
+}
+.highlight .no {
+  color: #fdce68;
+}
+.highlight .nd {
+  color: #fdce68;
+}
+.highlight .ni {
+  color: #fdce68;
+}
+.highlight .ne {
+  color: #fdce68;
+}
+.highlight .nf {
+  color: #dee2f7;
+}
+.highlight .nl {
+  color: #fdce68;
+}
+.highlight .nn {
+  color: #dee2f7;
+}
+.highlight .nx {
+  color: #dee2f7;
+}
+.highlight .py {
+  color: #fdce68;
+}
+.highlight .nt {
+  color: #f9867b;
+}
+.highlight .nv {
+  color: #fdce68;
+}
+.highlight .ow {
+  font-weight: 700;
+}
+.highlight .w {
+  color: #f8f8f2;
+}
+.highlight .mf {
+  color: #eddc96;
+}
+.highlight .mh {
+  color: #eddc96;
+}
+.highlight .mi {
+  color: #eddc96;
+}
+.highlight .mo {
+  color: #eddc96;
+}
+.highlight .sb {
+  color: #a3eea0;
+}
+.highlight .sc {
+  color: #a3eea0;
+}
+.highlight .sd {
+  color: #a3eea0;
+}
+.highlight .s2 {
+  color: #a3eea0;
+}
+.highlight .se {
+  color: #a3eea0;
+}
+.highlight .sh {
+  color: #a3eea0;
+}
+.highlight .si {
+  color: #a3eea0;
+}
+.highlight .sx {
+  color: #a3eea0;
+}
+.highlight .sr {
+  color: #7be2f9;
+}
+.highlight .s1 {
+  color: #a3eea0;
+}
+.highlight .ss {
+  color: #7be2f9;
+}
+.highlight .bp {
+  color: #fdce68;
+}
+.highlight .vc {
+  color: #fdce68;
+}
+.highlight .vg {
+  color: #fdce68;
+}
+.highlight .vi {
+  color: #f9867b;
+}
+.highlight .il {
+  color: #eddc96;
+}
+.highlight .gu {
+  color: #75715e;
+}
+.highlight .gd {
+  color: #f92672;
+}
+.highlight .gi {
+  color: #a6e22e;
+}

data/docs/_sass/custom/a11y-colours.scss

@@ -0,0 +1,4 @@
+$a11y-dark-grey: #55525a;
+$a11y-darker-grey: #46434a;
+$a11y-light-grey: #f5f6fa;
+$a11y-purple: #573fb4;

data/docs/_sass/custom/color-scheme-shims.scss

@@ -0,0 +1,66 @@
+// $body-background-color
+// $body-heading-color
+.site-title {
+  color: $body-heading-color;
+}
+
+// $body-text-color
+.site-footer {
+  color: $body-text-color;
+}
+
+// $link-color
+.nav-list .nav-list-item .nav-list-expander {
+  color: $link-color;
+}
+
+.main-content .anchor-heading svg {
+  color: $link-color;
+}
+
+// $nav-child-link-color
+.nav-list .nav-list-item > .nav-list .nav-list-item .nav-list-link {
+  color: $nav-child-link-color;
+}
+
+// $sidebar-color
+// $base-button-color
+// $btn-primary-color
+// $code-background-color
+// $feedback-color
+// $table-background-color
+// $search-background-color
+// $search-result-preview-color
+
+// $highlight-background-color
+p.highlight, blockquote.highlight {
+  background: $highlight-background-color;
+  color: $body-heading-color;
+}
+
+// $important-background-color
+p.important, blockquote.important {
+  background: $important-background-color;
+  color: $body-heading-color;
+}
+
+p.note, blockquote.note {
+  background: $note-background-color;
+  color: $body-heading-color;
+}
+
+// footer p {
+//   color: $a11y-dark-grey;
+// }
+
+// div.highlight {
+//   background: $a11y-light-grey;
+
+//   code {
+//     color: $a11y-dark-grey;
+//   }
+// }
+
+// .language-plaintext {
+//   color: $a11y-dark-grey !important;
+// }

data/docs/_sass/custom/custom.scss

@@ -0,0 +1,60 @@
+// {% if site.logo %}
+// $logo: "{{ site.logo | relative_url }}";
+// {% endif %}
+// @import "./support/support";
+// @import "./color_schemes/light";
+// {% unless include.color_scheme == "light" %}
+// @import "./color_schemes/{{ include.color_scheme }}";
+// {% endunless %}
+// @import "./custom/setup";
+// @import "./modules";
+// {% include css/callouts.scss.liquid color_scheme = include.color_scheme %}
+// {% include css/custom.scss.liquid %}
+
+@import "./color-scheme-shims";
+
+@media (prefers-color-scheme: dark) {
+  @import "./a11y-colours";
+  // @import "./support/support";
+
+  // $body-background-color: $grey-dk-300;
+  $body-background-color: black;
+  $body-heading-color: $grey-lt-000;
+  $body-text-color: $grey-lt-300;
+  $link-color: #a48dff;
+  $nav-child-link-color: $grey-dk-000;
+  $sidebar-color: #0d1117;
+  // $base-button-color: $grey-dk-250;
+  // $btn-primary-color: $blue-200;
+  $code-background-color: #31343f; // OneDarkJekyll default for syntax-one-dark-vivid
+  $code-linenumber-color: #dee2f7; // OneDarkJekyll .nf for syntax-one-dark-vivid
+  // $feedback-color: darken($sidebar-color, 3%);
+  $feedback-color: #0d1117;
+  $table-background-color: #111013;
+  // $search-background-color: $grey-dk-250;
+  // $search-result-preview-color: $grey-dk-000;
+  $border-color: $grey-dk-200;
+
+  @import "OneDarkJekyll"; // this is the one-dark-vivid atom syntax theme
+
+  $highlight-background-color: #3d3d2c;
+  $important-background-color: #132844;
+  $note-background-color: #211f41;
+
+  // Modules
+  @import "./base";
+  @import "./layout";
+  // @import "./content"; // contains a second charset
+  @import "./navigation";
+  // @import "./typography";
+  // @import "./labels";
+  // @import "./buttons";
+  // @import "./search";
+  @import "./tables";
+  @import "./code";
+  // @import "./utilities/utilities";
+  // @import "./print";
+  // @import "./skiptomain";
+
+  @import "./color-scheme-shims";
+}

data/docs/_sass/custom/setup.scss

@@ -0,0 +1,3 @@
+$highlight-background-color: #fffbe7 !default;
+$important-background-color: #d7e6fe !default;
+$note-background-color: #e3ddfd !default;

data/docs/decisions/0000-use-markdown-any-decision-records.md

@@ -0,0 +1,30 @@
+---
+nav_order: 0
+parent: Decision Records
+---
+# Use Markdown Any Decision Records
+
+## Context and Problem Statement
+
+We want to record any decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields.
+Which format and structure should these records follow?
+
+## Considered Options
+
+* [MADR](https://adr.github.io/madr/) 3.0.0 – The Markdown Any Decision Records
+* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
+* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
+* Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+* Formless – No conventions for file format and structure
+
+## Decision Outcome
+
+Chosen option: "MADR 3.0.0", because
+
+* Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+* MADR allows for structured capturing of any decision.
+* The MADR format is lean and fits our development style.
+* The MADR structure is comprehensible and facilitates usage & maintenance.
+* The MADR project is vivid.

data/docs/decisions/0001-adoption-of-an-off-the-shelf-code-of-conduct.md

@@ -0,0 +1,34 @@
+---
+nav_order: 1
+parent: Decision Records
+
+status: accepted
+date: 2023-01-04
+---
+# Adoption of an off-the-shelf Code of Conduct
+
+## Context and Problem Statement
+
+We want an explicit and documented code of conduct to support people collaborating with us on our projects. We need contributors to understand the code and enforcement policy.
+Which one should we adopt?
+
+## Considered Options
+
+* [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) v2.1
+* [Citizen Code of Conduct](https://github.com/stumpsyn/policies/blob/master/citizen_code_of_conduct.md)
+* Formless – No conventions for code of conduct
+
+## Decision Outcome
+
+Chosen option: "Contributor Covenant", because
+
+* It is used by tens of thousands of repos on GitHub, and is therefore likely the most recognised code of conduct of contributors.
+* It contains enforcement guidelines and is well maintained.
+* Citizen Code of Conduct hasn't been touched since 2018.
+
+### Consequences
+
+* Good, because it prevents us from needing to write one from scratch
+* Neutral, because teams need to discuss the implications of adopting the code of conduct
+* Neutral, because teams need to thoroughly read the [enforcement guidelines](https://www.contributor-covenant.org/version/2/1/code_of_conduct/#enforcement-guidelines) section of the code
+* Neutral, because teams need to set up and monitor an enforcement contact method.

data/docs/decisions/0002-use-megalinter-for-linting-common-file-formats.md

@@ -0,0 +1,41 @@
+---
+# Configuration for the Jekyll template "Just the Docs"
+nav_order: 2
+parent: Decision Records
+
+status: accepted
+date: 2023-01-05
+---
+# Use MegaLinter for linting common file formats
+
+## Context and Problem Statement
+
+We want to consistently manage the running of a large number of linters against our codebase containing a wide range of file formats, providing projects with a preconfigured GitHub Action.
+
+We also want to store our standard linter configurations centrally, so that contributors can comment on, and propose changes to, our coding standards. With coding standards we can move more quickly between projects. There are several tools which orchestrate this task. Which one should we adopt?
+
+## Considered Options
+
+* [Super-Linter](https://github.com/github/super-linter) for all languages, formats and tools.
+* [MegaLinter](https://megalinter.io/) is an Open-Source tool for CI/CD workflows that analyzes the consistency of your code, IAC, configuration, and scripts in your repository sources, to ensure all your projects sources are clean and formatted whatever IDE/toolbox is used by their developers, powered by OX Security.
+* Roll-our-own solution.
+* Have no conventions for common approach to linting.
+
+## Decision Outcome
+
+Chosen option: "MegaLinter", because:
+
+* The differences between MegaLinter and Super-Linter are [well documented](https://megalinter.io/latest/mega-linter-vs-super-linter), but having used both on this project first had, MegaLinter was more than 8 time faster in linting the project on my local machine than Super-Linter.
+* The ability to enable/disable linters allows us to take a more bespoke approach where the standard linter isn't adequate. E.g. The Ruby linter, Rubocop, contained in the Docker container, doesn't have access to the Rails linting we would adopt to adhere to the existing NDRS standard.
+
+Initially we will lint bash, c++, c#, coffeescript, dart, go, java, javascript, jsx, kotlin, make, python, R, rust, scala, SQL, swift, typescript, tsx, css, sass, html, json, markdown, xml, yaml, github actions, ansible, ARM, cloudformation, kubernetes, openapi, puppet and terraform files.
+
+These have been chosen as an initial list where they have been, are or could be used in projects both internally and with partner organisations.
+
+### Consequences
+
+* Good, because we can spend less time writing a bespoke orchestration tool that would have to manage all the different output formats from all the different linters.
+* Good, because we get secret scanning, security scanning of Infrastructure-as-Code code and dependency scanning as well as style checking.
+* Neutral, because where a particular coding style has been adopted for a particular language, it can be adopted here.
+* Neutral, because the rake task to run MegaLinter abstracts away any complexity with using Docker. Contributors only need to have Docker installed.
+* Bad, because developers will need to adapt to the standard coding style, if it is unfamiliar to them.

data/docs/decisions/0003-use-keep-a-changelog-v1-1-as-the-format-for-changelogs.md

@@ -0,0 +1,40 @@
+---
+# Configuration for the Jekyll template "Just the Docs"
+nav_order: 3
+parent: Decision Records
+
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+date: 2023-01-31
+---
+# Use keep a changelog v1.1 as the format for changelogs
+
+## Context and Problem Statement
+
+There is enormous variation in the way changelogs are written. We want to adopt a standardised approach that enables them to be read by other contributors and be machine readable for conversion to HTML for end-users. We want one that isn't a dump of version control commit logs.
+
+Which should we choose?
+
+## Considered Options
+
+* [keep a changelog v1.1.0](https://keepachangelog.com/en/1.1.0/)
+* [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator#github-changelog-generator-)
+* [GNU changelog style guide](https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs)
+* Roll-our-own solution.
+* Have no conventions for common approach to changelogs.
+
+## Decision Outcome
+
+Chosen option: "keep a changelog", because
+
+* It is an accessible format, both for people and tooling.
+* It is a human-written, plain English summary of changes, not a commit log dump.
+* It has a well defined structure that makes automation easier.
+* GNU changelog style is inadequate.
+
+### Consequences
+
+* Good, because we can programatically create a template changelog for the first time on new and existing projects
+* Good, because scaffolds the changes needed when we tag a new release
+* Good, because we can provide helpers (using existing tooling) than convert the changelog into HTML for inclusion in an end user system
+* Bad, because, unlike fully automated tools like github-changelog-generator, effort is required to turn commit messages into plain English.