From 949e3779f290aa5c1e82a4e1d8c285dd45977087 Mon Sep 17 00:00:00 2001 From: Yannic Moog Date: Tue, 2 Apr 2024 11:49:09 +0200 Subject: [PATCH] Add initial faq. Some frequent questions arose. Address them in an faq section of this project. Since the questions are aimed at developers, add them to the CONTRIBUTING.rst file. Signed-off-by: Yannic Moog --- CONTRIBUTING.rst | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index c843e2d3..4224ba50 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -363,3 +363,46 @@ being on your WIP branch:: When committing, make sure to add a sign-off using the option ``-s``:: git commit -s + +Frequently asked Questions +========================== + +How to decide where to put include files? +----------------------------------------- + +| Is the content architecture specific -> arch subdir +| Is it SoC specific -> soc subdir +| etc. + +When to update include files? +----------------------------- + +Whenever necessary. If some program is being described and the cli or the +behaviour changes, then existing manuals using the include file are now +outdated. When updating the include file to describe the newest revision of said +program, see `How does versioning work?`_. + +Why don't we use branches? +-------------------------- + +Branches are deemed too complicated for our purposes. + +How does versioning work? +------------------------- + +Since no branches shall be used for versioning, content for older manuals may +end up in the leaf files, i.e. the .rst files when no longer +compatible with the newest version. Specifically, the content will flow +downstream towards the leaf files. + +Example: + +i.MX 8M product family uses the (old) version of ``mmc`` that is no longer +compatible with master branches. It will need its own version of an include file +describing usage of the ``mmc`` program. + +Example: + +i.MX 8MP uses a different ``mmc`` command from master and from the rest of the +i.MX 8M family. The content will be split again and i.MX 8MP needs to use its +own specific version (different file).