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>

After trying to manually create a link to a page section for the nth time,
I finally scratched that itch and added AnchorJS to provide the links for
us. This greatly simplifies the process for linking to sections of pages,
especially useful for those not versed in digging around in the page
source.

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

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

We have recently had issues with older revisions of the Minnowboard
firmware, resulting in a 5 minute pause at boot (due to the addition of
reset attack mitigation functionality in newer versions of Linux).

We are in the process of updating boards to the latest firmware available.
Document the version that we are using and recommend that others update
their firmware.

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

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

The amd64 reference hardware page states the MinnowBoard Max is the
recommended hardware, but then lists 2 MinnowBoard Turbots in the table
below. Update the page to state the Turbot is the recommended hardware.

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

Try to speed up the single-threaded PDF generation by starting a process
for each CPU core.

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

GitLab Pages only really handles a single branch for each project, so
forking is the best way to have the proposed pages be rendered and
published by Pages.

By setting `baseURL` from CI using `$CI_PAGES_URL` we can ensure that
links are set properly instead of always pointing at
https://www.apertis.org/ as that's quite confusing during reviews.

However, for the main project we don't want to use the default GitLab
pages address, but we want to have links using the official
https://www.apertis.org/ address: to the main project now sets
`$BASEURL` as a CI/CD variable to point at https://www.apertis.org/


while forked projects will use the default based on `$CI_PAGES_URL`.

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 Frederic Danis committed 4 years ago

The code of conduct contains for Ekaterina, who is no longer at Collabora.
Update the page to contain the new "conduct@apertis.org" email alias which
has been setup for this purpose.

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

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

This patch extends the Contribution process document and the
contribution checklist for adding new designs to Apertis.

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

Denis Pynkin authored 4 years ago and Denis Pynkin committed 4 years ago

Add the subsection described how to setup the VirtualBox for
USB-OTG boot mode to be used in Apertis SDK VM.

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

Denis Pynkin authored 4 years ago and Denis Pynkin committed 4 years ago

Use 'internal' boot mode for the default boot.
Update photos of BOOT switch used during U-Boot flush to
be more human-friendly on resized page.

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

Denis Pynkin authored 4 years ago and Denis Pynkin committed 4 years ago

Mention the additional terminal for `minicom` for USB OTG boot
method. Need to mention this explicitly to avoid the problem
then novice user tries to run all steps in the single terminal.
This is preventing the data loss from the U-Boot output via serial
console and allows to see the flash status.

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

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

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>

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

Got out of step whilst adding creation dates to designs and failed to test
properly. A stray space is stopping the dates from being parsed. Remove
the space.

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

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

Add aliases to the main website page for the index page URLs as redirected
from designs.apertis.org. We are redirecting to the main page as the
contents of designs.apertis.org is in the process of being amalgamated
into the website structure and thus not all the designs content will end
up under one topic.

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

The old designs.a.o site holds versioned copies of the designs. We are not
going to present these any more, so where appropriate, link to the latest
copy of the document rather than returning 404.

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

The metadata in each file on designs.apertis.org didn't contain a creation
date, however this is the primary means that we are ordering the documents
by on the new Apertis website so that the newer documents are listed
first.

Whilst the documents don't contain a creation date, they are stored in a
git repository that can provide us with this information. Add the
retrieved dates into the front matter.

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

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

We are using Hugo's "ref" shortcode for links on the website as this helps
to ensure that our links are valid. A number of links that aren't using
this tool have been identified, fix them and the resulting bad page links
found un upstreaming.md.

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

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

A number of documents had previously been copied over from designs.a.o.
Tweak the contribution process document to correct broken titling
(discovered during comparison) and remove duplicates.

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

Since the `usb_imx` utility is not installed into PATH we have to use
relative or absolute path for calling it.

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

Whilst the documents copied over from designs.a.o are searchable, they are
not directly accessible from the main page. Add a link to them for now.
This link will be removed once the documents are sorted into the new
category structure.

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

Peter Senna Tschudin authored 4 years ago and Emanuele Aina committed 4 years ago

This patch fixes a few typos and minor issues and add a concrete example
of how to reproduce the build.

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

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

Whilst not important in CI as they will get cleaned up, having
temporary files and directories left after building locally is a pain.
Tweak to clean these files up.

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

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

The codeblock tables are being badly formatted, with the column for the
line numbers the same width as that for the content. Tweak the html for
tables with the `lntable` class so that the line numbers are only 3% of
the width.

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

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

A mistake whilst scripting replacements resulted in lines with 3
characters being replaced and later removed. Fix these errors.

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

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

The PDF generator can't find the images as the paths are relate to
where Hugo will place them on the website. Tweak the path to to point
to the images. We need to convert the SVG files into something the next
step can handle. Don't leave them in the static directory in case this
results in them being exported to the website.

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

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

Some of the image links were badly tweaked, resulting in the images not
being found. Correct the links.

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

This is required when the cleaning up and recovering space.
Usually, the beta, development and preview releases are the common
candidates for removal

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

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

A number of broken links didn't match the patterns used for automated
replacement. Fix up those that can be manually.

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

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

We now have the designs here, don't point to designs.a.o.

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

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

After moving the documents from designs.a.o to www.a.o, there were
quite a few links from the designs.a.o docs pointing to wiki.a.o and
quite a few links from www.a.o pointing to designs.a.o. Replace these
links with Hugo ref shortcodes to avoid hammering the redirects.

This was achieved with the following script:

```

import os
import re
import sys
import toml

from urllib.parse import urlparse

def get_aliases(filename):
    #print("%s: " % filename)
    with open(filename, 'r') as file:
        contents = file.read()
        if not contents[0:3] == "+++":
            return

        if "_index.md" in filename:
            filename = filename.strip(".")
        else:
            filename = filename.split("/")[-1]

        data = toml.loads(contents.split("+++")[1])

        if not "aliases" in data.keys():
            return

        for alias in data["aliases"]:
            if "/old-wiki/" in alias:
                wiki_aliases[alias.replace("/old-wiki/", "/")] = filename

            if "/old-designs/" in alias:
                # We're dropping the per-release links from designs.a.o, so match on shorter path
                design_aliases[alias.replace("/old-designs/latest/", "/")] = filename

def fix_link(url):
    link = url.group('link')

    url = urlparse(link)

    if url.netloc == "wiki.apertis.org":
        if url.path in wiki_aliases.keys():
            url = url._replace(scheme="")
            url = url._replace(netloc="")
            url = url._replace(path=wiki_aliases[url.path])
            link = " {{< ref \"%s\" >}} " % url.geturl()

    if url.netloc == "designs.apertis.org":
        # We're dropping the per-release links from designs.a.o, so match on shorter path
        path = "/%s" % url.path.split('/', 2)[-1]
        print(path)
        if path in design_aliases.keys():
            url = url._replace(scheme="")
            url = url._replace(netloc="")
            url = url._replace(path=design_aliases[path])
            link = " {{< ref \"%s\" >}} " % url.geturl()

    return "](%s)" % link

def fix_ref(url):
    link = url.group('link')

    url = urlparse(link)

    if url.netloc == "wiki.apertis.org":
        if url.path in wiki_aliases.keys():
            url = url._replace(scheme="")
            url = url._replace(netloc="")
            url = url._replace(path=wiki_aliases[url.path])
            link = " {{< ref \"%s\" >}} " % url.geturl()

    if url.netloc == "designs.apertis.org":
        # We're dropping the per-release links from designs.a.o, so match on shorter path
        path = "/%s" % url.path.split('/', 2)[-1]
        print(path)
        if path in design_aliases.keys():
            url = url._replace(scheme="")
            url = url._replace(netloc="")
            url = url._replace(path=design_aliases[path])
            link = " {{< ref \"%s\" >}} " % url.geturl()

    return "]: %s" % link

def correct_links(filename):
    #print("%s: " % filename)
    with open(filename, 'r+') as file:
        contents = file.read()

        if not contents[0:3] == "+++":
            return

        fm = contents.split("+++")[1]
        doc = contents.split("+++",2)[2]

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

        pattern = re.compile("\]: (?P<link>.*)")
        doc = pattern.sub(fix_ref, doc)

        file.seek(0)
        file.truncate()

        file.write("+++")
        file.write(fm)
        file.write("+++")
        file.write(doc)

wiki_aliases = {}
design_aliases = {}

for root, dirs, files in os.walk(sys.argv[1]):
    for file in files:
        if ".md" in file:
            get_aliases("%s/%s" %(root, file))

print("wiki_aliases:")
print(wiki_aliases)
print("design_aliases:")
print(design_aliases)

for root, dirs, files in os.walk(sys.argv[1]):
    for file in files:
        if ".md" in file:
            correct_links("%s/%s" %(root, file))
```

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