GitLab

- Add some guidance about the type of information a patch author should
  provide to facilitate the review (and for future reference).

- Make a number of implicit expectations explicit:
  - Every patch must compile.
  - All CI tests must pass.

- Mention that the patch author is expected to add reviewers and explain
  how to choose them.

- Explain the patch submission rules in terms of Gerrit labels.

Also do some cosmetic changes, like adding empty lines, shuffling some
paragraphs around.

Change-Id: I6dac486684310b5a35aac7353e10fe5474a81ec5
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

Change-Id: I5362780db422772fd547dc8e68e459109edccdd0
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

This patch expands the coding style documentation, splitting it
into two documents: the core style rules and extended guidelines.
Note that it does not redefine or change the coding style (aside
from section 4.6.2) - generally, it is only documenting the
existing style in more detail.

The aim is for the coding style to be more readable and, in turn,
for it to be followed by more people. We can use this as a more
concrete reference when discussing the accepted style with external
contributors.

Change-Id: I87405ace9a879d7f81e6b0b91b93ca69535e50ff
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
Signed-off-by: Petre-Ionut Tudor <petre-ionut.tudor@arm.com>

Tidying up a few Sphinx warnings that had built-up over time.
None of these are critical but it cleans up the Sphinx output.

At the same time, fixing some spelling errors that were detected.

Change-Id: I38209e235481eed287f8008c6de9dedd6b12ab2e
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Change-Id: Ic5aab23b549d0bf8e0f7053b46fd59243214aac1
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>

Credit to sam.ellis@arm.com for the input to create the list.

Change-Id: Id70a8eddc5f2490811bebb278482c61950f10cce
Signed-off-by: Soby Mathew <soby.mathew@arm.com>

The documentation contains plenty of notes and warnings. Enable
special rendering of these blocks by converting the note prefix
into a .. note:: annotation.

Change-Id: I34e26ca6bf313d335672ab6c2645741900338822
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Several code blocks do not specify a language for syntax
highlighting. This results in Sphinx using a default highlighter
which is Python.

This patch adds the correct language to each code block that doesn't
already specify it.

Change-Id: Icce1949aabfdc11a334a42d49edf55fa673cddc3
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

These are no longer needed as there will always be a table of contents
rendered to the left of every page.

Some of these lists can be quite long and, when opening a page, the
reader sees nothing but a huge list of contents! After this patch,
the document contents are front-and-centre and the contents are
nicely rendered in the sidebar without duplication.

Change-Id: I444754d548ec91d00f2b04e861de8dde8856aa62
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

This patch attempts to standardise the document titles as well as
adding titles to documents that were missing one. The aim is to
remove needless references to "TF-A" or "Trusted Firmware" in the
title of every document and to make sure that the title matches
with the document content.

Change-Id: I9b93ccf43b5d57e8dc793a5311b8ed7c4dd245cc
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

This change creates the following directories under docs/
in order to provide a grouping for the content:

- components
- design
- getting_started
- perf
- process

In each of these directories an index.rst file is created
and this serves as an index / landing page for each of the
groups when the pages are compiled. Proper layout of the
top-level table of contents relies on this directory/index
structure.

Without this patch it is possible to build the documents
correctly with Sphinx but the output looks messy because
there is no overall hierarchy.

Change-Id: I3c9f4443ec98571a56a6edf775f2c8d74d7f429f
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Change-Id: I915303cea787d9fb188428b98ac6cfc610cc4470
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

Sections 2.2, 2.3 and 2.4 contained example code blocks that were not
being formatted properly due to missing newlines.

Change-Id: I0dbce90c931cf69e4f47d2ccbcc8bc0e20f8fd66
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

This patch adds more details on #include directive use, including (pun
not intended) the desired ordering, grouping and variants (<> or "").

Change-Id: Ib024ffc4d3577c63179e1bbc408f0d0462026312
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

This patch attempts to make the guidelines clearer by reordering
the sections and grouping similar topics.

Change-Id: I1418d6fc060d6403fe3e1978f32fd54b8793ad5b
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Adds a link from user-guide.rst to coding-guidelines.rst and merges
the information about using checkpatch from both files into the user
guide document.

Change-Id: Iffbb4225836a042d20024faf28b8bdd6b2c4043e
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Change-Id: I083f673f37495d2e53c704a43a0892231b6eb281
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

Change-Id: Id0e6d272b6d3d37eab785273f9c12c093191f3fc
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

This content has been imported and adapted from the TF GitHub wiki
article 'ARM-Trusted-Firmware-Coding-Guidelines'.

The aim is to increase the visibility of the coding guidelines by
including them as part of the documentation that is within the TF
repository.

Additionally, the documentation can then be linked to by other
documents in the docs/ directory without worrying about broken links
to, for example, the external wiki.

Change-Id: I9d8cd6b5117b707c1a113baeba7fc5e1b4bf33bc
Signed-off-by: Paul Beesley <paul.beesley@arm.com>