Update and classify a batch of design documents

The design documents imported from designs.apertis.org need to be
classified and moved into the structure implemented for documents on the
new website. The content of the documents also need minor edits to ensure
a good look and feel as well as the addition of notes to explain the
context of some documents (such as noting that certain concept documents
have been implemented since they were written and when that occurred).

This commit contains conversion of an initial batch of design documents.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

content/designs/canterbury-legacy-application-framework.md → content/architecture/canterbury-legacy-application-framework.md

@@ -11,11 +11,9 @@ outputs = [ "html", "pdf-in",]
 date = "2019-12-13"
 +++
 
-# The Canterbury legacy application framework
-
 Apertis currently ships with a custom application framework based on the
 Canterbury app manager which is in the process of being phased out in favor of
-upstream components like Flatpak, see the[application framework]( {{< ref "application-framework.md" >}} )
+upstream components like Flatpak, see the [application framework]( {{< ref "application-framework.md" >}} )
 document for more details.
 
 Flatpak and Canterbury cover the core tasks of an application framework:
@@ -152,7 +150,7 @@ profiles for each applications can carefully reviewing them.
 
 Flatpak instead lets application authors specify in the application manifest a
 set of special high-level permissions. The Flatpak approach has been analysed
-in more detail in the original[permissions]( {{< ref "permissions.md" >}} ) document which already
+in more detail in the original [permissions]( {{< ref "permissions.md" >}} ) document which already
 described the use-cases for the permissions mechanism in the context of the
 Apertis application framework.
 

content/designs/case-for-moving-to-debian.md → content/architecture/case-for-moving-to-debian.md

@@ -10,6 +10,11 @@ outputs = [ "html", "pdf-in",]
 date = "2019-10-23"
 +++
 
+{{% notice note %}}
+This document provides the analysis and rationale for migrating to Debian as the projects upstream distribution.
+This change was completed in late-2018 and as such all releases since `v2019` have been based on Debian.
+{{% /notice %}}
+
 # Why was Apertis based on the Debian/Ubuntu ecosystem
 
 At the beginning of Apertis, a few platforms were considered for the base of Apertis: MeeGo, Tizen, OpenEmbedded Core, Debian and Ubuntu. A choice of Debian/Ubuntu ecosystem was based on Debian being ‘one of the oldest and largest (most inclusive of OSS packages), and one of the first Linux distributions to feature an ARM port’, providing ‘a very solid distribution baseline’ and ‘a high degree of robustness against the involvement or not of individual contributing companies’, while Ubuntu bases on Debian but adds value important for Apertis (see below). Another point against the other alternatives (e.g. OpenEmbedded Core) was that Collabora and Bosch have already invested into Open Build System infrastructure, while Yocto/OpenEmbedded has its own build infrastructure and tools not compatible with OBS.

content/designs/encrypted-updates.md → content/architecture/encrypted-updates.md

@@ -10,10 +10,6 @@ outputs = [ "html", "pdf-in",]
 date = "2020-06-11"
 +++
 
-# Encrypted updates
-
-## Introduction
-
 The encryption of the update file makes accessing its contents more difficult for bystanders, but doesn't necessarily protect from more resourceful attackers that can extract the decryption key from the user-owned device.
 
 The bundle encryption is done using the loop device with standard/proven kernel facilities for de/encryption (e.g. dm-crypt/LUKS). This allows the mechanism to be system agnostic (not tied to OSTree bundles), and can be used to ship updates to multiple components at once by including multiple files in the bundle.  
@@ -23,71 +19,71 @@ LUKS is the standard for Linux hard disk encryption. It provides secure manageme
 
 The authenticity of the update is checked by verifying the OSTree signature as dm-crypt utilises symmetric cryptography which can't be used to ensure trust as the on-device key can be used to encrypt malicious files, not just decrypt them.
 
-## Threat model
+# Threat model
 
-### Objectives
+## Objectives
   1. end-users can download updates from the product website and apply them offline to the device via a USB key or SD card
   2. only official updates should be accepted by the device
   3. the contents of the updates should not be easily extracted, increasing the effort required for an attacker and providing some protection for the business' intellectual property  
 
-### Properties
+## Properties
   1. **integrity**: the device should only accept updates which have not been altered  
   2. **authenticity**: the device should only accept updates coming from the producer
   3. **confidentiality**: the contents of the updates should not be disclosed
 
-### Threats
+## Threats
   1. Alice owns a device and wants to make it run her own software
   2. Emily owns a device and Alice wants to have her own software on Emily's device
   3. Vincent develops a competing product and wants to gain insights into the inner workings of the device
 
-### Mitigations
+## Mitigations
   1. **integrity**: the update is checksummed, causing alteration to be detectable
   2. **authenticity**: the update is signed with a private key by the vendor and the device only accepts updates with a signature matching one of the public keys in its trusted set
   3. **confidentiality**: the update is encrypted with a symmetric key (due to technology limitations public key decryption is not available)
 
-### Risks and impacts
+## Risks and impacts
 
-#### the private key for signing is leaked
-##### Impact
+### the private key for signing is leaked
+#### Impact
   * the private key allows Alice to generate updates that can be accepted by all devices
 
-##### Mitigations
+#### Mitigations
   * the private key is only needed on the vendor infrastructure producing the updates
   * the chance of leaks is minimized by securing the infrastructure and ensuring that access to the key is restricted as much as possible
   * public keys for the leaked private keys should be revoked
   * multiple public keys should be trusted on the device, so if one is revoked updates can be rolled out using a different key
   * keys should not be re-used across products to compartimentalize them against leaks
 
-#### the private key for signing is lost
-##### Impact
+### the private key for signing is lost
+#### Impact
   * updates can't be generated if no private key matching the on-device public ones is available
 
-##### Mitigations
+#### Mitigations
   * if multiple public keys are trusted on the device, the private key used can be rotated if another private key is still available
   * backup private keys should be stored securely in different locations
 
-#### the symmetric key for encryption/decryption is leaked
-##### Impact
+### the symmetric key for encryption/decryption is leaked
+#### Impact
   * Alice has access to all symmetric keys stored in bundles encrypted with the leaked key
   * the symmetric key allows Alice to generate updates that can be decrypted by devices
 
-##### Mitigations
+#### Mitigations
   * due to its symmetric nature, the secret key has to be available on both the vendor infrastructure and on each device
   * secure enclave technologies can help use the symmetric key for decryption without exposing the key in any way
   * if secure enclave is not available the key has to be stored on the device and can be extracted via physical access
   * if the key can't be provisioned in the factory the key has to be provisioned via unencrypted updates, from which an attacker can extract the keys without physical access to the device
   * multiple decryption keys must be provisioned, to be able to rotate them in case of leaks
 
-#### the symmetric key for encryption/decryption is lost
-##### Impact
+### the symmetric key for encryption/decryption is lost
+#### Impact
   * encrypted updates can't be generated for devices only using this symmetric key
 
-##### Mitigations
+#### Mitigations
   * given that the key has to be available on each device, the chance of losing the encryption/decryption key is small
   * if multiple decryption keys are provisioned on the device, the encryption key can be rotated
   * if all keys are lost or corrupted on the device, it will not be possible to decrypt bundles on USB/SDCard and so to update the device using this method.
 
-## Key infrastructure
+# Key infrastructure
 
 LUKS is able to manage up to 8 key slots, any of the 8 different keys can be used to decrypt the update bundle.
 This can allow a bundle to be read using a main key or fallback key(s), and/or by different devices with a different subsets of the used keys.
@@ -99,25 +95,25 @@ Random keys for bundle encryption can be generated using:
 head -c128 /dev/random | base64 --wrap=0
 ```
 
-### How keys can be stored on devices
+## How keys can be stored on devices
   - Keys can be stored in separated files, located in read-only part of the filesystem: `/usr/share/apertis-update-manager/`
   - In future versions, keys may be stored using the secure-boot-verified key storage system
 
-### How keys can be deployed to devices
+## How keys can be deployed to devices
   - Keys stored in the filesystem can be deployed by the normal update mechanism
 
-### When new keys should be generated
+## When new keys should be generated
 New keys should be generated:
  - for new products
  - when a key has been compromised
 
-### How the build pipeline can fetch the keys
+## How the build pipeline can fetch the keys
   - As for the signing key, the key(s) used to encrypt the static delta bundle should be passed to the encryption script GitLab CI/CD variable(s)
 
-### How multiple keys can be used for key rotations
+## How multiple keys can be used for key rotations
   - When the keys are stored on the filesystem, key rotation will not provide any benefit as the leak of one key implies the leak of the others
   - When the keys will be stored using the secure-boot-verified key storage system, the encrypted updates will be generated wih non-leaked keys and will remove the leaked keys while adding the new keys to the secure-boot-verified key storage system, so the number of available keys remain the same
 
-### How to handle the leak of a key to the public and how that impacts future updates
+## How to handle the leak of a key to the public and how that impacts future updates
   - If the keys are stored on the filesystem, the leak of one key implies the leak of the others
   - If the keys are stored using the secure-boot-verified key storage system, the next update should be signed with a key that hasn't been leaked and the update should revoke the leaked key

content/designs/long-term-reproducibility.md → content/architecture/long-term-reproducibility.md

@@ -43,7 +43,7 @@ while the runtime behavior is not affected.
 
 # Apertis artefacts and release channels
 
-As described in the[release flow]( {{< ref "release-flow.md" >}} ) document, at any given time Apertis
+As described in the [release flow]( {{< ref "release-flow.md" >}} ) document, at any given time Apertis
 has multiple active release channels to both provide a stable foundation for
 product teams and also give them full visibility on the latest developments.
 
@@ -277,7 +277,7 @@ matching git tag.
 Other files capture other pieces of information that can be useful to reproduce
 builds. For instance the `build-url` point to the full log of the build where
 the recipe commit hash and the Docker image hash can be identified, however in
-the[implementation plan]( {{< ref "#implementation-plan" >}} ) section a few improvements are described to make
+the [implementation plan]( {{< ref "#implementation-plan" >}} ) section a few improvements are described to make
 that information easier to retrieve and use.
 
 ## Package builds

content/designs/secure-boot.md → content/architecture/secure-boot.md

@@ -10,10 +10,6 @@ outputs = [ "html", "pdf-in",]
 date = "2019-10-23"
 +++
 
-# Apertis secure boot
-
-## Introduction
-
 For both privacy and security reasons it is important for modern devices to
 ensure that the software running on the device hasn't been tampered with. In
 particular any tampering with software early in the boot sequence will be hard
@@ -28,7 +24,7 @@ them. This document discusses how that aspect of the various technologies works
 on a high-level and how this can be introduced into Apertis.
 
 
-## Boot sequence
+# Boot sequence
 
 To understand how secure boot works first one has to understand how booting
 works. From a high-level perspective a CPU is a very simple beast, it needs to
@@ -99,7 +95,7 @@ the boot sequence and will load/start the code for each of the cells it runs.
 For this document we'll only look at securing the booting of the main (Linux
 running) processor without a hypervisor.
 
-## Secure boot sequence
+# Secure boot sequence
 
 The main objective for a secure boot process is to ensure all code that gets
 executed by the processor is trusted. As each of the stages described in the
@@ -124,7 +120,7 @@ most systems to fully verify all of the root filesystem at boot time as this
 simply would take far too long. As such the form of protection described
 thus far only gets applied up to the point the Linux kernel starts loading.
 
-## Threat models
+# Threat models
 
 To understand what a secure boot system really secures it's important to look
 at the related threat models. As a first step we can distinguish between
@@ -135,7 +131,7 @@ intended. As with any software security vulnerabilities can invalidate the
 protection given. While in most cases these can be patches as issues become
 known, for ROM code this is impossible without a hardware change.
 
-### offline attacks
+## offline attacks
 
 * Attack: Replace any of the boot stages on device storage (physical access
           required)
@@ -158,7 +154,7 @@ known, for ROM code this is impossible without a hardware change.
 * Impact: Full control of the device as far as the kernel allows.
 * Mitigation: No protection from the above mechanisms.
 
-### online attacks
+## online attacks
 
 * Attack: Gain enough access to replace any of the boot stages on device storage
 * Impact: Depending on the boot stage the attacker can get full control
@@ -172,7 +168,7 @@ known, for ROM code this is impossible without a hardware change.
 * Mitigation: No protection from the above mechanisms.
 
 
-## Signing and signing infrastructure
+# Signing and signing infrastructure
 
 To securely boot a device it is assumed all the various boot stages have some kind
 of signature which can be validate by previous stages. Which by extension also
@@ -209,7 +205,7 @@ limited e.g. on i.MX6 device one can *one-time* program up to four acceptable
 keys and each of those can be flagged as revoked, but it's impossible to add
 more or replace any keys.
 
-## Apertis secure boot integration
+# Apertis secure boot integration
 
 Integrating secure boot into Apertis really exists out of two parts. The first
 part is to ensure all boot stages have the ability to verify. The second part
@@ -232,7 +228,7 @@ production build to test on development devices. This in turn means that the
 signing tools and implementation need to support signing outside the build
 process which is normally supported.
 
-## Apertis secure boot implementation steps
+# Apertis secure boot implementation steps
 
 As the whole process is somewhat device specific implementation of a secure
 boot flow for Apertis should be done on a device per device basis. The best
@@ -242,7 +238,7 @@ well supported by upstream components. Furthermore an initial PoC for the early
 boot stages was already done for the NXP Sabre Auto boards which are based on
 the same SoC.
 
-## SabreLite secure boot preparation
+# SabreLite secure boot preparation
 
 The [good introduction into HAB (High Assurance Boot)](https://boundarydevices.com/high-assurance-boot-hab-dummies/)
 is prepared by Boundary Devices, also there are some [documentation](https://github.com/u-boot/u-boot/blob/master/doc/imx/habv4/introduction_habv4.txt)
@@ -340,7 +336,7 @@ step below! This is irreversible operation:
 => fuse prog 0 6 0x2
 ```
 
-## Secure boot in the U-Boot package for Sabrelite
+# Secure boot in the U-Boot package for Sabrelite
 
 The U-Boot bootloader must be configured with the option `CONFIG_SECURE_BOOT`
 to enable support of HAB (High Assurance Boot) support on i.MX6 platform.
@@ -360,7 +356,7 @@ and this ensures that only verified initial system will be started.
 All other format types like zImage, as well as other boot methods are
 prohibited on fully secured device when "closed" mode is enabled or emulated.
 
-## Sign U-Boot bootloader such that the ROM can verify
+# Sign U-Boot bootloader such that the ROM can verify
 
 To sign the U-Boot for SabreLite we need `cst` tool installed in the system
 and the [Apertis development keys repository](https://gitlab.apertis.org/infrastructure/apertis-imx-srk) need to be checked out. Please use the [csf/csf_uboot.txt](https://gitlab.apertis.org/infrastructure/apertis-imx-srk/-/blob/master/csf/csf_uboot.txt) file
@@ -398,7 +394,7 @@ appended to original `u-boot.imx` binary:
 cat u-boot.imx csf_uboot.bin > u-boot.imx.signed
 ```
 
-### Sign U-Boot bootloader for loading via USB serial downloader
+## Sign U-Boot bootloader for loading via USB serial downloader
 
 In case if something goes wrong and the system does not boot anymore
 it is still possible to boot with the help of [USB serial downloaders](https://community.nxp.com/docs/DOC-95604),
@@ -430,7 +426,7 @@ sh mod_4_mfgtool.sh set_dcd_addr u-boot.imx
 cat u-boot.imx csf_uboot.bin > u-boot.imx.signed_usb
 ```
 
-## Sign kernel images for U-Boot to load
+# Sign kernel images for U-Boot to load
 
 After the successful startup of U-Boot we need to load the Linux kernel,
 initramfs and DTB file into the memory. All these bits must be verified before
@@ -443,7 +439,7 @@ The signing procedure for kernel images is split into 2 parts:
 - preparation of the kernel image in FIT format
 - sign FIT image
 
-### FIT image creation
+## FIT image creation
 
 [U-Boot documentation](https://github.com/u-boot/u-boot/tree/master/doc/uImage.FIT)
 contains a lot of details and examples how to create FIT images
@@ -513,7 +509,7 @@ Created:         Fri Mar 13 02:23:33 2020
 CSF Processed successfully and signed data available in vmlinuz.itb
 ```
 
-### Signing the FIT image
+## Signing the FIT image
 
 Now it is time to sign the produced image. The procedure is similar to
 signing U-Boot with additional step -- we need to add the **IVT**
@@ -571,7 +567,7 @@ $ cst -i vmlinuz-pad-ivt.csf -o vmlinuz-pad-ivt.bin
 CSF Processed successfully and signed data available in vmlinuz-pad-ivt.bin
 ```
 
-## Signing bootloader and kernel from the image build pipeline
+# Signing bootloader and kernel from the image build pipeline
 
 Starting with v2021dev1 Apertis uses single signed FIT kernel image for OSTree-based
 systems. The signed version of U-Boot is a part of U-Boot installer.
@@ -618,7 +614,7 @@ withCredentials([ file(credentialsId: csf_csf_key, variable:  'CSF_CSFKEY'),
 }
 ```
 
-### U-Boot signing
+## U-Boot signing
 
 To sign the U-Boot the script [scripts/sign-u-boot.sh](https://gitlab.apertis.org/infrastructure/apertis-image-recipes/-/blob/apertis/v2021dev1/scripts/sign-u-boot.sh)
 has been added. It automatically generates the CSF configuration
@@ -633,7 +629,7 @@ image](https://gitlab.apertis.org/infrastructure/apertis-image-recipes/-/blob/ap
     script: scripts/sign-u-boot.sh "${ROOTDIR}/deb-binaries/usr/lib/u-boot/{{ $target }}/u-boot.imx"
 ```
 
-### FIT image creation and signing
+## FIT image creation and signing
 
 The FIT image is more complex. So for Apertis we use 2 scripts:
 - the [`scripts/generate_signed_fit_image.py` script](https://gitlab.apertis.org/infrastructure/apertis-image-recipes/-/blob/apertis/v2021dev1/scripts/generate_signed_fit_image.py)
@@ -655,6 +651,6 @@ by the [OSTree commit recipe](https://gitlab.apertis.org/infrastructure/apertis-
 **NB**: this action must be done prior to ostree commit action
 to add the signed FIT kernel into OSTree repository for OTA upgrades.
 
-## As next steps the following could be undertaken:
+# As next steps the following could be undertaken:
 * Integration of PCKS#11 support in the signing process to support HSM devices
 * Automated testing of secure boot if possible

content/designs/application-framework.md → content/concepts/application-framework.md

 +++
-title = "Application Framework"
+title = "The next-gen Apertis application framework"
 short-description = "Ecosystem, Security, Compositor, Audio Management, Agents, Flatpak, and much more"
 weight = 100
 aliases = [
@@ -11,8 +11,6 @@ outputs = [ "html", "pdf-in",]
 date = "2019-10-23"
 +++
 
-# The next-gen Apertis application framework
-
 As a platform, Apertis needs a vibrant ecosystem to thrive, and one of the
 foundations of such ecosystem is being friendly to application developers and
 product teams. Product teams and application developers are more likely to

content/designs/automated-license-compliance.md → content/concepts/automated-license-compliance.md

@@ -10,7 +10,6 @@ outputs = [ "html", "pdf-in",]
 date = "2020-06-05"
 +++
 
-# Automated License Compliance
 
 A Linux system such as those assembled by Apertis contain components licensed under many different licenses.
 These various licenses impose different conditions and it is important to understand to a good degree of fidelity the terms under which each component is provided.
@@ -39,7 +38,7 @@ To achieve this 2 main steps need to be taken:
 
 We recommend to integrate these steps into our CI pipelines to provide early detection of any change to the licensing status of each package. Extending our CI pipelines will also enable developers to learn about new issues and to solve them during the merge request development flow.
 
-## License scanners
+# License scanners
 
 There are various proprietary and open source tools which can help with tracking the licensing terms that apply to the pieces of software from which Apertis is built.
 The following tools are examples of those that can help to achieve the first of the steps outlined above:
@@ -58,7 +57,7 @@ The following tools are examples of those that can help to achieve the first of
 Due to the open source nature of the Apertis project, we intend to utilize an open source tool for license compliance rather than a proprietary solution.
 Given the traction, community, and Linux Foundation involvement, our suggestion of open source tool for license scanning is FOSSology.
 
-### FOSSology
+## FOSSology
 
 FOSSology is a server based tool which provides a web front-end that is able to scan through source code (and to a degree binaries) provided to it, finding license statements and texts.
 To achieve this FOSSology employs a number of different scanning techniques to identify potential licenses, including using matching to known license texts and keywords.
@@ -71,7 +70,7 @@ It is possible to export and import reports which contain the licensing decision
 FOSSology is backed by the Linux Foundation, it appears to have an active user and developer base and a significant history.
 As such, it is felt that this tool is likely to be maintained for the foreseeable future and thus a good choice for integration into the Apertis workflow.
 
-### CI Pipeline integration
+## CI Pipeline integration
 
 In order to avoid manual tasks the license detection should be integrated into the CI process.
 FOSSology provides a [REST API](https://www.fossology.org/get-started/basic-rest-api-calls/) to enable such integration.
@@ -86,7 +85,7 @@ In some cases, to achieve the fine grained licensing information desired, the li
 Once an initial pass of all Apertis components had been made we would expect missing license information to result in an error, as such errors would be as a result of new matches being found, which would need to be resolved in FOSSology before CI would complete without an error.
 The generated report should be saved in the Debian metadata archive so that it is available for the following processing.
 
-## Binary to source file mapping
+# Binary to source file mapping
 
 Now that we have a way to determine the licensing of the source files, we need a way to determine which of these source files were used in each binary.
 Compilers store information in the binaries it outputs, that can be used by a debugger to pause execution of a process at a point corresponding to a selected line of source code.
@@ -96,7 +95,7 @@ Executable binaries in Linux are generally stored in the [Executable and Linkabl
 By parsing this information, the source files that were used to generate each binary can be determined.
 Combining this with the licensing information provided in the licensing report, a mapping can be made between each binary and it's associated licenses.
 
-### CI Pipeline integration
+## CI Pipeline integration
 
 Apertis uses the Open Build Service (OBS) platform to build the binary packages in a controlled manner across several architectures and releases.
 OBS utilizes `dpkg-buildpackage` behind the scenes to build each package.
@@ -123,14 +122,14 @@ The terms of the various licenses may be considered [compatible](https://en.wiki
 For example, a binary derived from source code licensed with the GPLv2 license and other source code licensed with the MIT license, the terms of both apply to the binary, though as the terms of the MIT license will be met if the binary is used in accordance with the terms of the GPLv2, then handling the binary as though it was licensed under the GPLv2 will ensure the terms of both are met.
 Not all possible combinations of licenses work out this way and thus why it is important to ensure that licensing is properly tracked.
 
-## Binary Licensing Reporting
+# Binary Licensing Reporting
 
 The approach each project using Apertis takes with regards to the reporting of licensing information should be driven by how this information is to be utilized, i.e. some projects may wish to parse the license information and present it in a single BOM file in HTML, XML or human readable text.
 
 For the images provided by the Apertis project, we plan to combine the reports saved in `/usr/share/doc/<package>/` into a single parsable file.
 Should it be required to provide some tool with which to interrogate the licensing which applies to the binary packages, the SPDX files can be imported into FOSSology.
 
-### CI Pipeline integration
+## CI Pipeline integration
 
 Apertis utilizes [Debos](https://github.com/go-debos/debos) in its image generation pipeline.
 There is an existing tool available for the merging of SPDX documents.

content/designs/op-tee.md → content/concepts/op-tee.md

 +++
-title = "OP-TEE integration"
+title = "Integration of OP-TEE in Apertis"
 short-description = "Discussing and detailing an approach to the integration of OP-TEE as a Trusted execution environment"
 weight = 100
 aliases = [
@@ -10,7 +10,6 @@ outputs = [ "html", "pdf-in",]
 date = "2020-04-09"
 +++
 
-# Integration of OP-TEE in Apertis
 
 Some projects that wish to use Apertis have a requirement for strong security measures to be available in order to implement key system level functionality.
 A typical use case is enabling the decryption of protected content in such a way that doesn't allow the owner of the device doing the decryption to access the decryption keys.
@@ -29,7 +28,7 @@ Some platforms provide a mechanism to enable a secure, trusted environment or "[
 A TEE runs on the application processor, but with mechanisms in place to isolate the code or data of the two running systems (the TEE and the main OS) from each other.
 ARM provides an implementation of such security mechanisms, known as [ARM TrustZone](https://developer.arm.com/ip-products/security-ip/trustzone), mainly on Cortex-A processors.
 
-## System Architecture
+# System Architecture
 
 ![](/images/op-tee_architecture.svg)
 

content/designs/coding_conventions.md → content/policies/coding_conventions.md

@@ -10,6 +10,13 @@ outputs = [ "html", "pdf-in",]
 date = "2019-10-25"
 +++
 
+{{% notice info %}}
+This document specifically relates to software which is or has been created for
+the Apertis project. It is important that any code added to an existing project
+utilises the coding conventions as used by that project, maintaining
+consistency across that projects codebase.
+{{% /notice %}}
+
 Coding conventions is a nebulous topic, covering code formatting and whitespace,
 function and variable naming, namespacing, use of common GLib coding patterns,
 and other things. Since C is quite flexible, this document mostly consists of a
@@ -176,7 +183,7 @@ following GObject conventions:
 
 ## Modularity
 
-[Modularity](http://en.wikipedia.org/wiki/Modular_programming)Modularity],
+[Modularity](http://en.wikipedia.org/wiki/Modular_programming),
 [encapsulation](http://en.wikipedia.org/wiki/Encapsulation_%28object-oriented_programming%29)
 and [loose coupling](http://en.wikipedia.org/wiki/Loose_coupling) are core
 computer science concepts which are necessary for development of maintainable

content/designs/hwpack-requirements.md → content/policies/hwpack-requirements.md

@@ -11,35 +11,31 @@ outputs = [ "html", "pdf-in",]
 date = "2019-11-28"
 +++
 
-# HWpack Requirements
-
-##  Introduction
-
 This documentation covers the requirements and considerations that should be taken into account when implementing "hardware packs" for the Apertis project.
 
-## Concepts
+# Concepts
 
 This section briefly covers the concepts and expectations of the Apertis platform.
 
-### Image Building Stages
+## Image Building Stages
 
 Apertis images are built from binary packages, packaged in the `.deb` format. Building these packages is expected to be carried out from source by the Apertis infrastructure, ensuring all packages dependencies are properly described and reducing the risk of unexpected dependencies.
 
 The selection and packaging of these packages are predominantly driven by the needs of the two main process steps required to create images, known as the `OSpack` and `HWpack`.
 
-#### OSpack
+### OSpack
 
 The OSpack stage generates one or more generic (architecture specific but largely hardware independent) archived rootfs built from Apertis packages. These rootfs archives are known as OSpacks. The process is managed by a tool called [Debos](https://github.com/go-debos/debos), which uses yaml configuration files to guide what steps it takes. Apertis provides yaml files to assemble a number of differently targeted OSpacks, ranging from a minimal GUI-less OSpack, a target focused GUI OSpack and a development environment with a desktop style GUI and has pre-packaged the components required to generate these OSpacks.
 
 ![OSpack creation with Debos](/images/debos-ospack.svg)
 
-#### HWpack
+### HWpack
 
 Unlike the OSpack step, the hardware package (HWpack) step does not result in an item known as a HWpack. The HWpack is comprised of a Debos script which controls the processing of a run time determined OSpack to convert it from a hardware independent OSpack into an image which can be successfully booted on a specific hardware platform. In addition to developing the HWpack script, the HWpack step requires the modification and packaging of the required components to perform this transformation.
 
 ![Image creation with Debos](/images/debos-image.svg)
 
-### Apertis packages
+## Apertis packages
 
 Apertis standardizes on a specific set of components (with specific versions) and technologies to fulfill the needs of the target platforms. This maximizes sharing and reuse, thus minimizing effort and cost of maintaining common components across products. Deviations from the standard selection may be needed to accommodate product-specific needs but such deviations tend to reduce reuse and thus increase the long-term maintenance efforts. It will likely fall on the product team in question to carry this added effort. As a result, it is strongly preferred for deviations to be minimized with generic improvements and additions made to the standard components to add the required functionality where possible.
 
@@ -65,7 +61,7 @@ These are some of the key packages from which the Apertis system is built:
 
 All Apertis packages are packaged using standard Debian packaging, with source code and package configuration stored in the Apertis GitLab enabling automation of the package build process.
 
-### Typical Apertis OS layout
+## Typical Apertis OS layout
 
 The reference Apertis images share a common layout per architecture, enabling images to be shared across the various supported platforms of each architecture:
  - Bootloader typically stored in flash

content/designs/license-applying.md → content/policies/license-applying.md

@@ -40,10 +40,10 @@ There are two parts to licensing a project:
 
 The license text is normally distributed in the `COPYING.MPL` or `COPYING` file
 which lives in the top directory in the git repository for the project. This
-file will contain the full license text, as listed at
-[https://www.mozilla.org/media/MPL/2.0/index.815ca599c9df.txt], without any
-modifications or changes. For example, see the
-[newport COPYING file](https://gitlab.apertis.org/appfw/newport/blob/apertis/v2019/COPYING).
+file will contain the full license text, as
+[provided by Mozilla](https://www.mozilla.org/media/MPL/2.0/index.815ca599c9df.txt),
+without any modifications or changes. For example, see the
+[newport COPYING file](https://gitlab.apertis.org/pkg/target/newport/blob/apertis/v2019/COPYING).
 
 While `COPYING` is a more common filename to use, `COPYING.MPL` accounts for
 the case where there may be files in the project under a different license