From 6edc4376e4a422d6a834385a09173a227e766191 Mon Sep 17 00:00:00 2001 From: Marek Koza Date: Wed, 17 Apr 2024 21:56:23 +0200 Subject: [PATCH] docs: Add code structure & contributing section, fix headings --- doc/_static/custom.css | 13 ++++- doc/code-structure.rst | 129 +++++++++++++++++++++++++++++++++++++++++ doc/conf.py | 2 +- index.rst | 6 +- 4 files changed, 143 insertions(+), 7 deletions(-) create mode 100644 doc/code-structure.rst diff --git a/doc/_static/custom.css b/doc/_static/custom.css index f219f9a..35247ea 100644 --- a/doc/_static/custom.css +++ b/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 { diff --git a/doc/code-structure.rst b/doc/code-structure.rst new file mode 100644 index 0000000..601a705 --- /dev/null +++ b/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/``) +- development releases from the develop branch (``-dev.``), + 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 (``-a.``, + ``-b.``, ``-rc.``), where ``version`` is + MAJOR.MINOR.PATCH and ``num`` is the number of the release version +- feature/testing releases form the release branches (``-.``), + 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. + diff --git a/doc/conf.py b/doc/conf.py index bddca67..bf49b3f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -39,7 +39,7 @@ .. |plum| raw:: html - + .. role:: tag-button .. role:: material-icons diff --git a/index.rst b/index.rst index 70aff98..ff3baf1 100644 --- a/index.rst +++ b/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