Linux kernel workflow

One of the most important and widely used workflows at Pengutronix is the one used to develop the Linux kernel.

The Linux kernel is divided into different subsystems, which are roughly comparable to individual departments of a company. Depending on the complexity, there may be further subsystems. Possible changes to the Linux kernel (bug fixes, new drivers, code quality improvements) are first discussed within the subsystem. A maintainer is responsible for each subsystem (this can be compared to a middle management level), who carries out tests and checks whether the quality standards are met. If everything is in order, the changes of all subsystems flow into the next version of the Linux kernel. This is released by Linus Torvalds (the first author and maintainer of Linux) himself.

We have adapted the described workflow for the work on the process manual: changes to the process documentation are discussed with the respective process users and then passed on to the management for approval. Currently, the Pengutronix process manual project is still small enough that "subsystem maintainers" e.g. a middle management layer is not required.

Version control

In order to be able to implement this workflow, the processes are written as structured text files that are managed in a version-controlled manner. The release branch of the version management can only be written for the management, so that a new release of the process manual also ensures the release at the same time.

The advantage of files written in reStructuredText (.rst) or Markdown (.md) plain-text formats as opposed to non-text-based formats such as .docx or .odf is that the change in content can be easily tracked in a version management system along with a timestamp and the respective authors. Furthermore, in addition to just tracking changes, a version management system also allows descriptive text to be written to record why a change was made and what decisions led to the process change.

Web representation

As great as the charm of text files is from the point of view of the process writers, for the process users the user-friendliness is not ideal. Therefore, Pengutronix uses the open source software documentation tool Sphinx to generate a web view of the process manual. In this, the processes can be linked directly as well as forms belonging to a process can be made available for download.

Build server

With the help of a build server, the current release of the process documentation is built and made available as a web view. At the same time, the build server enables the use of automated tests.

At Pengutronix, the build server checks, among other things, whether the date on which the next process review is due has been exceeded. If this occurs, reminder e-mails are sent so that the process can be checked promptly to ensure that it is up to date.

The setup has only been described schematically here, as the focus is not on concrete products but on their use for process documentation. What is more important is that any form of version management is used to track changes and that any kind of build server is used for continuous testing and continuous deployment.

Structure of a process description

In order for the setup to be used to its full extent, it is crucial that a structure for the handbook and the structure of a process is determined in advance. A good example of the structure of processes and how such a manual can be designed is the "Company Handbook" by GitLab Inc.

In order to go into practice, the structure of a process in the process documentation of Pengutronix is described in excerpts, and a test is presented as an example.

A process consists of three sections: the first section is a table in which metadata is recorded. When was the process last updated? When is the next review due? Is there a predecessor process? Which process follows on from the current process? Are there any forms to download?

The second section contains the actual process description. There is no fixed form for this. To make the process easy to read, additional structuring elements such as info boxes or enumerations are used.

The third section is reserved for general information based on the quality criteria of ISO 9001. Among others, the following questions should be answered: Who are the process users and owners? When is the process activated? What requirements are there for the process users and what quality criteria are there for the process to fulfill?

On the one hand, the structure is aimed at the process users so that the information can be found as easily as possible. On the other hand, the metadata table allows the use of test automation.

Test automation

One of the most important uses for test automation is a regular reminder that processes are due for review.

In order for certain elements, such as the next review date of a process, to be reviewed, it is necessary to specify very precisely where the element can be found. The table structure is particularly suitable for this.

The tests here were written in Python and the docutils library was used to parse the file. This code example shows the test for the review date of a process.

def check_Wiedervorlage(self, document):
     assert 'Wiedervorlage' in self._data, \
         annotate(self._table, "metadata table missing 'Wiedervorlage' row")
     value = self._data['Wiedervorlage']
     match = re.match(r"(\w+): ([\d\-]+)", value)
     assert match, \
         annotate(self._table, "metadata 'Wiedervorlage' row has the wrong format")
     groups = match.groups()
     try:
         dt = datetime.strptime(groups[1], "%Y-%m-%d")
     except ValueError:
         dt = None
     assert dt is not None, \
         annotate(self._table, "metadata review time ('{}') format is invalid".format(groups[1]))
     assert dt >= datetime.strptime(datetime.now().strftime("%Y-%m-%d"), "%Y-%m-%d"), \
         annotate(self._table, "metadata review time ('{}') is in the past".format(groups[1]))

This test consists of three test steps: first, it checks whether the table column was found at all, then whether the date corresponds to the expected format, and finally whether this date is in the past.