docs: Add code structure & contributing section, fix headings

doc/_static/custom.css

@@ -6,7 +6,18 @@
 	}
 }
 
-h1 {
+h1::before {
+	content: '';
+	background: url('header.png');
+	background-size: contain;
+	background-repeat: repeat-x;
+	height: 4em;
+	width: 100%;
+	display: inline-block;
+}
+
+p + section h2, h1 + section h2 {
+	break-before: page;
 }
 
 .align-left {

doc/code-structure.rst

@@ -0,0 +1,129 @@
+=============================================
+Code structure, contributing
+=============================================
+
+To make the development easy and available to masses, plumCore is adopting
+some common standards to manage code and releases:
+
+
+Git version control system
+=============================================
+
+Gitflow workflow
+=============================================
+
+
+Contributing
+=============================================
+
+All contributions are commited to *feature* branches. Developers from within
+the main development team can contribute to the mainline hosted at ``GitHub``.
+
+All other contributors must fork the mainline repository on ``GitHub``,
+push their changes there and create a pull request.
+
+After all required tests are completed successfuly and all the required
+reviewers approve the PR, it can be merged into the *develop* branch.
+
+
+Semantic versioning
+=============================================
+
+The |plum| plumCore project uses Semantic Versioning 2.0.0 for all its
+build releases, that is for:
+
+- stable releases from the release branches (``release/<version>``)
+- development releases from the develop branch (``<version>-dev.<num>``),
+  where ``version`` is MAJOR.MINOR.PATCH, ``num`` is the number of commits
+  since the last tagged development release
+- alpha, beta, RC releases from the release branches (``<version>-a.<num>``,
+  ``<version>-b.<num>``, ``<version>-rc.<num>``), where ``version`` is
+  MAJOR.MINOR.PATCH and ``num`` is the number of the release version
+- feature/testing releases form the release branches (``<version>-<name>.<num>``),
+  where where ``version`` is MAJOR.MINOR.PATCH of the last tagged development
+  branch, ``name`` is the feature name and ``num`` is the number of commits
+  since the feature was branched off the development branch
+
+
+
+
+Conventional Commits
+=============================================
+
+As the page at https://www.conventionalcommits.org/en/v1.0.0/ says:
+
+*The Conventional Commits specification is a lightweight convention on top
+of commit messages. It provides an easy set of rules for creating an explicit
+commit history; which makes it easier to write automated tools on top of.
+This convention dovetails with SemVer, by describing the features, fixes,
+and breaking changes made in commit messages.*
+
+We are using commint messages in the format:
+
+.. code-block:: text
+	:linenos:
+
+	type(scope): description
+
+	[optional body]
+
+	[optional footer(s)]
+
+Where ``type`` is one of the following:
+
+- ``fix``: a commit of the type ``fix`` patches a bug in your codebase (this correlates with ``PATCH``
+  in Semantic Versioning).
+
+- ``feat``: a commit of the type ``feat`` introduces a new feature to the codebase (this correlates
+  with ``MINOR`` in Semantic Versioning).
+
+- breaking change: a commit that appends a ``!`` after the ``type/scope``, introduces a breaking API
+  change (correlating with ``MAJOR`` in Semantic Versioning). A breaking change can be part of commits
+  of any type.
+
+There are additional types available when the commit doesn't fall into one of the previous categories:
+
+- ``docs`` for documentation only changes which do not modify the resulting build
+- ``style`` changes not modifying the code meaning (whitespaces, formatting, etc.)
+- ``refactor`` changes in code not introducing any new features nor bug fixes
+- ``chore`` for changes in the build system, tools, repository configuration, etc. 
+
+Scope is the changed part of the plumCore framework:
+
+- services are shortened to ``srv``
+- ``kernel`` for all changes in the microkernel and implementation of the basic IPC
+- ``app/name`` - changes in the application named ``name``
+- ``port/name`` - changes in the corresponding port code
+- ``plat/name`` - changes in the corresponding platform code
+
+Footers are written in the format described in https://git-scm.com/docs/git-interpret-trailers
+
+
+
+Continuous Integration
+=============================================
+
+
+
+Release artifacts
+=============================================
+
+Artifacts are being made as a result of the build process. There are multiple build processes
+producing different kinds of artifacts in the |plum| plumCore project:
+
+Firmware builds
+-----------------------
+
+Firmware builds are located in the ``bin/`` directory. There are several:
+
+- ELF images with debug symbols
+- MAP files to facilitate debugging
+- stripped ELF images (optionally) loadable by the plumCore bootloader/chainloader
+- signed ELF images with a signing section added for loading in signature-verification
+  enabled bootloader
+
+Documentation builds
+----------------------------
+
+They are located in the ``doc/build/`` directory.
+

doc/conf.py

@@ -39,7 +39,7 @@
 
 .. |plum| raw:: html
 
-   <img style="position: relative; top: -0.15em; height: 1em; width: auto;" src="_static/plum.svg">
+   <img style="position: relative; top: -0.15em; height: 1em; width: auto;" src="/_static/plum.svg">
 
 .. role:: tag-button
 .. role:: material-icons

index.rst

@@ -1,8 +1,3 @@
-.. image:: doc/_static/header.png
-	:width: 100%
-	:alt: header image
-
-
 ====================================
 |plum| The plumCore DAQ framework
 ====================================
@@ -40,6 +35,7 @@ are not plumCore's target applications.
 	protocols/nbus/nbus
 	ports/index
 	doc/conceptual/conceptual
+	doc/code-structure
 	doc/coding-style