Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

Following the tweaks to the pages the images need to be moved to their new
expected location under images.

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

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

The developer documentation is now in it's own temporary section. Move the
index page to the correct name for a section index.

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

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

The existing metadata and some inline codes need converting to work with
Hugo:

 - Remove authors as we don't have an equivalent for that in Hugo
 - Add in fields that the existing metadata doesn't have
 - Include aliases to allow us to point to the new pages from a
   redirect on designs.apertis.org
 - Ensure we have a title (based on filename if one not present)
 - Convert hotdoc code blocks to Hugo equivalent
 - HotDoc allowed a `[][link]` format that Hugo doesn't understand
 - HotDoc allowed relative links without text, which Hugo doesn't handle
 - The location of the images and other media has changed
 - The format used for internal page references has is different

Additionally, fix up touched links to other Apertis pages to use the
Hugo "ref" shortcode, which reduces the risk of leaving hanging links.

All frontmatter created in toml format to stay consistent with existing
documents.

Converted using the following python script:
```

import os
import re
import subprocess
import sys
import toml
import yaml

def url_munge(match):
    url = match.group('url').strip('.')
    if url[0] != "/":
        url = "/%s" % url
    url = url.replace("media", "images")
    link = ("![](%s)" % url)

    return link

def link_munge(match):
    link = match.group('link')
    new = link.replace("(", "")
    new = new.replace(")", "")
    new = new.replace("`", "")
    new = new.replace("?", "")
    new = new.replace(":", "")
    new = new.replace(",", "")
    new = new.replace("–", "")
    new = new.replace("“", "")
    new = new.replace("”", "")
    new = new.replace(".", "")
    new = new.replace(" ", "-")
    new = new.lower()
    new = (" [%s]( {{< ref \"#%s\" >}} )" % (link, new))

    return new

def link_munge_2(match):
    link = match.group('link')
    new = link.replace("#", "")
    new = new.replace("-", " ")
    new = new.replace(".md", "")
    if not "http" in link:
        link = " {{< ref \"%s\" >}} " % link

    new = (" [%s](%s)" % (new, link))

    return new

for filename in os.listdir("."):
    if ".md" not in filename:
        continue

    print("%s: " % filename)
    with open(filename, 'r+') as file:
        contents = file.read()
        if contents[0:3] == "+++":
            # We have toml
            data = toml.loads(contents.split("+++")[1])
            doc = "+++".join(contents.split("+++")[2:])
        elif contents[0:3] == "---":
            # We have yaml
            data = yaml.load(contents.split("---")[1])
            doc = "---".join(contents.split("---")[2:])
        else:
            # No frontmatter
            data = {}
            doc = contents

        if not "title" in data.keys():
            data["title"] = filename.split(".")[0].replace('_', ' ').capitalize()

        data["weight"] = 100
        data["aliases"] = ["/old-developer/latest/%s" % filename.replace(".md", ".html")]

        # Add aliases
        latest = data['aliases'][0]

        for version in ['v2019', 'v2020', 'v2021pre', 'v2022dev0']:
            versioned = latest.replace("/latest/", "/%s/" % version)
            data['aliases'].append(versioned)

        data["outputs"] = ["html", "pdf-in"]

        # Remove authors
        if "authors" in data.keys():
            del data["authors"]

        # Switch HotDoc code blocks to hugo code blocks
        pattern = re.compile("^---", re.MULTILINE)
        doc = pattern.sub("```", doc)

        # Hotdoc uses `[][Internal Title]` for internal links whilst Hugo uses `[](#internal-title)`
        pattern = re.compile("\[\]\[(?P<link>.*?)\]")
        doc = pattern.sub(link_munge, doc)

        # Hotdoc allows empty links like `[](url)`
        pattern = re.compile("[^!]\[\]\((?P<link>.*?)\)")
        doc = pattern.sub(link_munge_2, doc)

        # Media links not working
        pattern = re.compile("!\[\]\((?P<url>.*?)\)")
        doc = pattern.sub(url_munge, doc)

        file.seek(0)
        file.truncate()

        file.write("+++\n")
        file.write(toml.dumps(data))
        file.write("+++")
        file.write(doc)
```

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

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

The documentation pulled from developer.apertis.org, which utilises HotDoc
document generation uses a `...` marker at the end of it's leading
metadata whilst Hugo (as used on the website) expects `---`. change
instances of this string.

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

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

This is the initial import of documents and media from
developer.apertis.org. It will need tweaks to make it build properly.

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

For external developers, they may not have access right to push branches
into default repositories. We encourage users to fork the repository and
then prepare a merge request.

So updating the documentation accordingly.

Signed-off-by: Ritesh Raj Sarraf <ritesh.sarraf@collabora.com>

This commit fixes typos and small issues on the long term
reproducibility document.

Signed-off-by: Peter Senna Tschudin <peter.senna@collabora.com>

Martyn Welch authored 4 years ago and Peter Senna Tschudin committed 4 years ago

Move documents out of designs and into more suitable locations following
the layout guidelines.

Perform some minor edits to correct typos and remove unneeded titles.

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

Martyn Welch authored 4 years ago and Peter Senna Tschudin committed 4 years ago

The pages in the site map are currently ordered by date. This doesn't make
much sense in the list. Order alphabetically instead to make it a bit
clearer.

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

Martyn Welch authored 4 years ago and Peter Senna Tschudin committed 4 years ago

Add the expectations for the utilisation of the various existing sections
to the website README.md to help guide contributors.

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

.gitattributes is used by many projects in their development workflows.
THis can, many a times, interfere with the Apertis package development
workflow. Thus document the fix for such cases.

Signed-off-by: Ritesh Raj Sarraf <ritesh.sarraf@collabora.com>

Signed-off-by: Ritesh Raj Sarraf <ritesh.sarraf@collabora.com>

Martyn Welch authored 4 years ago and Martyn Welch committed 4 years ago

An evaluation has been performed of the test cases to determine their
validity and value in respect to the current focus and direction of
Apertis. Add a document showing the analysis and recommendations reached as
a result of this evaluation.

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

Ritesh Raj Sarraf authored 4 years ago and Martyn Welch committed 4 years ago

The base-files package, depending on its branch name, generates the os
distribution specific attributes. Since those attributes expect a
certain set of infrastructure changes available (eg. new release's
docker images), this step is classified to be executed manually.

Signed-off-by: Ritesh Raj Sarraf <ritesh.sarraf@collabora.com>

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

We have enabled the generation of PDFs when appropriate using a custom
output type "pdf-in". When the PDF is being produced, add a link to the
page to alert readers to its existance.

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

Add the `lightweight` tag to run jobs on the GitLab runners set up for
jobs that do not need large amounts of resources (max 2GB of RAM) and do
not need privileged containers.

The former makes jobs cheaper because they user smaller VM instance
types, the latter improves latency as there's no strong need to spin
separate VMs to keep each job isolated and existing instances can be
re-used instead.

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

Update the document to reflect the latest implementation status.

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

Add a basic description to the index page for each of the "official"
sections (as laid out inthe websites README.md). This provides visitors to
the site with some guidance as to what to expect to find in each section,
somewhere to point out to related polices (such as the release schedule and
flow from the releases section) and a way to add aliases (such as the
missing alias to Guides for the "Guidelines" section that was found on the
old wiki).

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

Emanuele Aina authored 4 years ago and Frederic Danis committed 4 years ago

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

Martyn Welch authored 4 years ago and Martyn Welch committed 4 years ago

The site menu is quite long. When we are in a section, scroll the menu to
the relevant section.

This is a bit hacky due to the navbar at the top and the way the theme is
constructed. In order to avoid issues with the scrolling distance being
incorrectly calculated (due to reflow of text as the side bar gets wider)
animate as a drop-down instead of appearing from the side.

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

Martyn Welch authored 4 years ago and Martyn Welch committed 4 years ago

We can change the logic subtly and reduce replication of properties.
Also set visibility to improve accessibility.

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

This reverts commit d7d0dfd9.

The patch was ineffective and thus being reverted to ensure we don't build
up cruft.

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

SabreLite v1.0 has a reversed switch position for SW1 for
normal and USB-OTG boot. Since it is very rare and old board
there is no need to provide the photo but it is useful to mention
about the difference.

Signed-off-by: Denis Pynkin <denis.pynkin@collabora.com>

Should be armhf architecture for SabreLite.

Signed-off-by: Denis Pynkin <denis.pynkin@collabora.com>

We have the Apertis Logo linked from the Debian census here:

  https://wiki.debian.org/Derivatives/Census/Apertis

This entry was added to the census when we were still using the wiki. As a
result it is linking to:

  https://wiki.apertis.org/mediawiki/images/2/27/Apertis-100.png

This no longer exists, it is redirected to:

  https://www.apertis.org/old-wiki/mediawiki/images/2/27/Apertis-100.png



The quickest solution is to ensure this image exists. We can look at
updating the census data as well, but that will probably take longer.

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

Andrej Shadura authored 4 years ago and Sjoerd Simons committed 4 years ago

Future changes to the licensing of some TLS implementations are
compounding an already uncertain licensing situation. Add a document
describing the situation; an analysis of options to rectify this and
our recommendations.

Signed-off-by: Andrej Shadura <andrew.shadura@collabora.co.uk>
Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

It has been communicated to us that the menu on the left hand side of the
designs.apertis.org site is missed when looking for documents on the
website. Implement a basic site menu in a sidebar to get feedback.

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

This documents the invocation of the automation script for folding
changes. And also emphasizes that the final result should be validated
manually.

Signed-off-by: Ritesh Raj Sarraf <ritesh.sarraf@collabora.com>

Emanuele Aina authored 4 years ago and Martyn Welch committed 4 years ago

This document describes how we built images on Jenkins, but we have now
largely moved away from it in favor of GitLab CI/CD.

The README in the infrastructure/apertis-image-recipes> project
describes the current setup closer to the actual code.

Keep the document around since v2019 and v2020 are still officially on
Jenkins and old release notes still point here.

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

Emanuele Aina authored 4 years ago and Martyn Welch committed 4 years ago

Now that we have largely moved away from Jenkins to GitLab CI/CD the
document describing the benefits of using Docker with Jenkins no longer
add much value.

The switch to Docker has proved immensely useful and has been a
fundamental piece for our ability to move to GitLab CI/CD, and in 2020
Docker is widespread enough in the industry that there's no longer a
real need for Apertis to rehash the benefits it brings.

Let's drop the document now that it has been fully implemented and
that we moved the CI/CD architecture even further, making the
document obsolete.

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

The license expectations document is a little out of date. Tweak it a bit
and move it along with the license-exceptions document to policies.

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

Martyn Welch authored 4 years ago and Martyn Welch committed 4 years ago

This concept document describes a possible approach to closing the CI loop
using Jenkins. Apertis is moving away from the use of Jenkins and so this
document is now defunct. Remove it.

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

Martyn Welch authored 4 years ago and Martyn Welch committed 4 years ago

The selection of images as defined for the v2019 release has been used for
a number of releases. This is no longer an open concept, add the
documentation to the images page and remove the concept document.

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

Martyn Welch authored 4 years ago and Martyn Welch committed 4 years ago

The license-validation document covers the same ground as the first
portion of the automated license compliance documentation. Drop it to save
duplication of information.

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

Martyn Welch authored 4 years ago and Martyn Welch committed 4 years ago

The captilisation used for further links is inconsistent. There are also a
rather large number of links under "Developer Ready".

Reduce captitalisation for the further links items, re-order and reduce
the number of further links under "Developer Ready" to focus more on the
important topics not linked elsewhere.

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

We are currently adding anchor links to all headings. This includes the
page titles, which is the one heading to which we really don't need a
link. The page title is also centered and the addition of the anchor
causes the normally visible part of the title to be nudged to rendered off
center. This is visually unappealing, so stop adding anchors to the page
titles.

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