Project

General

Profile

Documentation »

Maintenance Guide

The documentation of xmera Omnia is written in AsciiDoc and convertible into HTML by Antora.

It is published on https://docs.xmera.de.

Development and maintenance of the documentation is reported on xmera Circle. Each core maintainer needs to have an account. Contributors may create pull requests on GitHub with their change requests.

Repositories on GitHub

The documentation consists of several repositories:

Project Purpose GitHub
xmera Omnia Documentation Is the leading repository used as a kind of container for the other repos below xo_docs
xmera Omnia Guide Contains the user and admin manual xo_guide
xmera Omnia Demo Guide Contains feature descriptions and short video sequencies of xmera Omnia with demo data xo_demo_guide
xmera Omnia - Docs UI Styles the User Interface according to xmera Solutions color scheme antora-ui-xmera

Repository Structure

Default Branches

Each repository is divided into some default branches:

  • master
  • <x.y>

where <x.y> represents the respective xmera Omnia main and minor version such as 3.7, 4.0. The master branch reflects the documentation of the latest xmera Omnia version such that 4.1.

Task Branches

For every task as listed in our Roadmap on xmera Circle it is necessary to create a fresh branch from the latest version of the relevant branch. The naming of the task branch should follow this pattern:

(name-of-issue-tracker)-#(number-of-issue)

It may look like this:

ìmprovement-#1129

The relevant branch is either master or any other <x.y>. The choice depends on the task itself.

Build and Release Flow

antora-ui-xmera

  • -- needs description --

xo_guide, xo_demo_guide

  • build directory needs to be excluded from version control
  • update antora-ui-xmera version if necessary
  • update sidebar navigation if necessary
  • update README and CHANGELOG if necessary
  • merge your task branch into the relevant branch (master or <x.y>)
  • when you needed to create a new feature branch <x.y> then you should change antora.yml from version: latest to version: <x.y> in that branch. Afterwards push this new branch and change back to master.
  • push your changes to origin and github

xo_docs

  • build directory needs to be included from version control
  • update antora-ui-xmera version if necessary
  • update sidebar navigation if necessary
  • update README and CHANGELOG if necessary
  • update playbook.yml by adding additional branches if necessary
  • make a test build in master branch
  • push your changes to origin and github
  • release the latest version on https://docs.xmera.de