docs: update contribution guideline
- Remove obsolete links to tf.org Phabricator.
- Update branching strategy.
- Small updates for readability.
Change-Id: Ic772801e952a8522c8bc8fd83622d4a93eeda92e
Signed-off-by: Gyorgy Szing <gyorgy.szing@arm.com>
diff --git a/docs/developer/service-deployment-model.rst b/docs/developer/service-deployment-model.rst
index 9f79999..8200adf 100644
--- a/docs/developer/service-deployment-model.rst
+++ b/docs/developer/service-deployment-model.rst
@@ -1,5 +1,6 @@
Service Deployment Model
========================
+
A goal of the Trusted Services project is to provide a toolbox of reusable service components
that can be deployed across a wide range of platforms. The project structure promotes reuse by
grouping related source files into subdirectories that represent reusable components. Components
@@ -11,20 +12,19 @@
deployments parent are sub-directories concerned with building and deploying different
applications. Applications can generally be classified as one of the following:
- - Service providers
- - Test suites
- - Libraries
- - Development support applications
+ - Service providers (e.g. psa-crypto)
+ - Test suites (e.g. ts-service-test)
+ - Libraries (e.g. libts)
+ - Development support applications (e.g. fwu-tool)
This page is mainly concerned with describing the conventions used to enable service providers
to be deployed in different environments, on different platforms and with different capabilities.
The conventions aim to minimize build definition duplication between alternative deployments
while offering sufficient flexibility to customize capabilities and support different platforms.
-The service deployment model borrows from a pattern used for deploying cloud services where There
-is a similar requirement for deployment flexibility.
Ports and Adapters Architecture
-------------------------------
+
An application is decoupled from any particular environment via a set of interfaces that reflect
the needs of the application. This model conforms to the ports and adapters architectural
pattern that aims to avoid tight coupling between application components and any particular
@@ -52,6 +52,7 @@
Service Deployment Structure
----------------------------
+
By convention, the directory structure for service provider deployments reflects the layers in
the ports and adapters architecture. The following dependency diagram illustrates the set of
relationships that exist for a fully defined deployment:
@@ -70,32 +71,39 @@
* - Build Component
- Defines
- Reuse Scope
- * - Application
- - | Set of components that form the core application to be deployed.
- - | All deployments of the application.
- * - Infra
- - | The set of adapters that realize the ports that the application depends on.
+ * - Deployment
+ - | Represents an application. Examples: a service provider, demo application, test application,
+ | some tool.
+ - | -
+ * - Infrastructure
+ - | A specific set of SW components that realize the ports that the application depends on.
| An infrastructure definition may depend on:
- * Environment specific components.
* Drivers that conform to a driver model.
- * Platform specific drivers.
- | Any deployment that uses the same infrastructure to support the application.
| This will depend on how specific the infrastructure is. An infrastructure
- | definition may allow for some level of configurability to enable deployment
+ | definition may allow for some level of configurability to enable a deployment
| to impose a particular build configuration. Where an infrastructure includes
| adapters that use a well supported driver model (such as UEFI), the scope
| for reuse is large.
- * - Env
+ * - Environment
- | The set of environment specific components that are common across all
| deployments of an application for a particular environment.
- | All deployments of the application into a specific environment. There is
| scope to improve reuse of environment specific components across multiple
| deployments.
- * - Config
- - | Build configuration variables together with a particular application, infra
- | and env.
- - | Depends on how specific the config is.
+ * - Configuration
+ - | Build configuration variables together with a particular application, infrastructure
+ | and environment. Represents a specific build of the application.
+ - | None.
+ * - Platform
+ - | A specific set of hardware drivers and target platform specific settings.
+ | A platform definition may depend on:
+
+ * Hardware driver ports defined by various components.
+ * Hardware specific resources.
+ * Target specific resource selection.
+ - | None.
Deployment Directory Structure
------------------------------
@@ -112,12 +120,11 @@
Configuration Definitions
^^^^^^^^^^^^^^^^^^^^^^^^^
To build a particular configuration of the block-storage service provider (in this case, one
-that uses flash storage on the N1SDP platform), use::
+that uses flash storage emulated with semihosting on the AEM FVP platform), use::
- cd deployments/block-storage/config/n1sdp-flash
+ cd deployments/block-storage/config/semihosted-opteesp
cmake -B build
- cd build
- make
+ cmake --build build
The CMakeLists.txt file for the n1sdp-flash deployment of the block-storage service provider
includes:
diff --git a/docs/developer/uml/ServiceDeploymentDependencies.puml b/docs/developer/uml/ServiceDeploymentDependencies.puml
index 515a7c5..b49c11c 100644
--- a/docs/developer/uml/ServiceDeploymentDependencies.puml
+++ b/docs/developer/uml/ServiceDeploymentDependencies.puml
@@ -7,19 +7,18 @@
@startuml
-package Deployment
-package Application
-package Infrastructure
-package Environment
-package Platform
-package BuildConfig
-package Adapter
+component Deployment
+component Infrastructure
+component Environment
+component Configuration
+component Adapter
+component Adapter as pl_adapter
+component Platform
-Deployment -down.> Application
Deployment -down.> Infrastructure
Deployment -down.> Environment
-Deployment -down.> "0..1" Platform
-Deployment -down.> "0..1" BuildConfig
+Deployment -down.> Configuration
+Deployment -down.> Platform
Infrastructure -down.> "0..*" Adapter
-
+Platform -down.> "0..*" "pl_adapter"
@enduml
\ No newline at end of file
diff --git a/docs/project/contributing.rst b/docs/project/contributing.rst
index 5d8cb8f..1576df0 100644
--- a/docs/project/contributing.rst
+++ b/docs/project/contributing.rst
@@ -9,39 +9,46 @@
Getting Started
---------------
-- Make sure you have a GitHub account and you are logged on `developer.trustedfirmware.org`_.
-- Send an email to the |TS_MAIL_LIST| about your work. This gives everyone
- visibility of whether others are working on something similar.
+- Make sure you have a GitHub account and you are logged in at `review.trustedfirmware.org`_.
+- Make sure the following is configured in `Gerrit settings`_:
+
+ - Your public key is set under ``SSH Keys``. This will be needed when pushing changes.
+ Please see `Public keys section`_ of Gerrit documentation if you need new keys.
+ - The email address you will use in git is added under ``Email Addresses``.
+
- Clone the |TS_REPO| on your own machine.
Making Changes
--------------
+- Send an email to the |TS_MAIL_LIST| about your work. This gives everyone visibility of whether others are working on
+ something similar.
- Make commits of logical units. See these general `Git guidelines`_ for contributing to a project.
- Follow the :ref:`Coding Style & Guidelines`.
- Keep the commits on topic. If you need to fix another bug or make another enhancement, please create a separate
change.
- Avoid long commit series. If you do have a long series, consider whether some
commits should be squashed together or addressed in a separate topic.
-- Make sure your commit messages are in the proper format. Please keel the 50/72 rule (for details see `Tim Popes blog entry`_.)
+- Make sure your commit messages are in the proper format. Please keep the 50/72 rule (for details see
+ `Tim Popes blog entry`_.)
- Where appropriate, please update the documentation.
- Consider which documents or other in-source documentation needs updating.
- - Ensure that each changed file has the correct copyright and license information. Files that entirely consist of
- contributions to this project should have a copyright notice and BSD-3-Clause SPDX license identifier of the form
- as shown in :ref:`license`. Example copyright and license comment blocks are shown in :ref:`Coding Style & Guidelines`.
- Files that contain changes to imported Third Party IP files should retain their original copyright and license
- notices. For significant contributions you may add your own copyright notice in following format::
+ - For topics with multiple commits, you should make all documentation changes (and nothing else) in the last commit
+ of the series. Otherwise, include the documentation changes within the single commit.
+
+- Ensure that files have the correct copyright and license information. Files that entirely consist of contributions to
+ this project should have a copyright notice and BSD-3-Clause SPDX license identifier of the form as shown in
+ :ref:`license`. Example copyright and license comment blocks are shown in :ref:`Coding Style & Guidelines`. Files that
+ contain changes to imported Third Party IP files should retain their original copyright and license
+ notices. For significant contributions you may add your own copyright notice in following format::
Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved.
- where XXXX is the year of first contribution (if different to YYYY) and YYYY is the year of most recent
- contribution. *<OWNER>* is your name or your company name.
- - For any change, ensure that YYYY is updated if a contribution is made in a year more recent than the previous YYYY.
- - If you are submitting new files that you intend to be the technical sub-maintainer for (for example, a new platform
- port), then also update the :ref:`maintainers` file.
- - For topics with multiple commits, you should make all documentation changes (and nothing else) in the last commit
- of the series. Otherwise, include the documentation changes within the single commit.
+ where `XXXX` is the year of first contribution (if different to `YYYY`) and `YYYY` is the year of most recent
+ contribution. `<OWNER>` is your name or your company name.
+- If you are submitting new files that you intend to be the technical sub-maintainer for (for example, a new platform
+ port), then also update the :ref:`maintainers` file.
- Please test your changes.
@@ -54,37 +61,46 @@
contribution is made under the terms of the :download:`Developer Certificate of Origin <../../dco.txt>`.
More details may be found in the `Gerrit Signed-off-by Lines guidelines`_.
-
- Ensure that each commit also has a unique ``Change-Id:`` line. If you have cloned the repository with the "`Clone with
commit-msg hook`" clone method, this should already be the case.
More details may be found in the `Gerrit Change-Ids documentation`_.
-- Submit your changes for review at https://review.trustedfirmware.org targeting the ``integration`` branch.
+- Select your target branch.
- - The changes will then undergo further review and testing by the :ref:`maintainers`. Any review comments will be made
- directly on your patch. This may require you to do some rework.
+ - If all commits of your change compile and run ok, then your review can target the ``integration`` branch.
+ - If not, a topic branch is needed. The name of the topic branch has to be kept reasonably sort and has to follow
+ this format: ``topics/<user-id>/<topic>``.
- Refer to the `Gerrit Uploading Changes documentation`_ for more details.
+ - `user-id` is unique ID of the user (e.g. nick name, <first name>_<last name>, etc...).
+ - `topic` is a title reflecting the purpose of the change.
+- Push your changes to Gerrit. Refer to the `Gerrit Uploading Changes documentation`_ to see how this can be done.
+
+- The changes will then undergo further review and testing by the :ref:`maintainers`. Any review comments will be made
+ directly on your patch. This may require you to do some rework.
- When the changes are accepted, the :ref:`maintainers` will integrate them.
- - Typically, the :ref:`maintainers` will merge the changes into the ``integration`` branch.
- - If the changes are not based on a sufficiently-recent commit, or if they cannot be automatically rebased, then the
- :ref:`maintainers` may rebase it on the ``main`` branch or ask you to do so.
- - After final integration testing, the changes will make their way into the ``main`` branch. If a problem is found
- during integration, the merge commit will be removed from the ``integration`` branch and the :ref:`maintainers` will
- ask you to create a new patch set to resolve the problem.
+- Typically, the :ref:`maintainers` will merge the changes into the target branch.
+
+- If the changes are not based on a sufficiently-recent commit, or if they cannot be automatically rebased, then the
+ :ref:`maintainers` may rebase it ask you to do so.
+
+- After final integration testing, the changes will make their way into the ``main`` branch. If a problem is found
+ during integration, the merge commit will be removed from the ``integration`` branch and the :ref:`maintainers` will
+ ask you to create a new patch set to resolve the problem.
--------------
-.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
+.. _review.trustedfirmware.org: https://review.trustedfirmware.org
.. _Git guidelines: http://git-scm.com/book/ch5-2.html
.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
.. _`Tim Popes blog entry`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
-.. _`Trusted Firmware Security Center`: https://developer.trustedfirmware.org/w/collaboration/security_center/
+.. _`Trusted Firmware Security Center`: https://trusted-firmware-docs.readthedocs.io/en/latest/security_center/index.html
+.. _`Gerrit settings`: https://review.trustedfirmware.org/settings/
+.. _`Public keys section`: https://review.trustedfirmware.org/Documentation/user-upload.html#configure_ssh_public_keys
*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*