Add guidelines and checklist for contributing designs

This patch extends the Contribution process document and the
contribution checklist for adding new designs to Apertis.

Signed-off-by: Peter Senna Tschudin <peter.senna@collabora.com>

content/policies/contribution_checklist.md

@@ -84,11 +84,9 @@ avoid the review getting hung up on avoidable issues:
    [API design guidelines]( {{< ref "api_design.md" >}} ),
    [namespacing guidelines](https://developer.gnome.org/programming-guidelines/unstable/namespacing.html.en),
    [memory management guidelines](https://developer.gnome.org/programming-guidelines/unstable/memory-management.html.en),
-   [pre- and post-condition
-guidelines](https://developer.gnome.org/programming-guidelines/unstable/preconditions.html.en),
+   [pre- and post-condition guidelines](https://developer.gnome.org/programming-guidelines/unstable/preconditions.html.en),
    and
-   [introspection
-guidelines](https://developer.gnome.org/programming-guidelines/unstable/introspection.html.en)
+   [introspection guidelines](https://developer.gnome.org/programming-guidelines/unstable/introspection.html.en)
    — some key points from these are pulled out below, but these are not the
    only points to pay attention to.
 1. All new public API must be
@@ -265,3 +263,58 @@ guidelines](https://developer.gnome.org/programming-guidelines/unstable/introspe
    any design decisions which the author thinks the reviewer might question. If
    a commit message is inadequate, the reviewer is going to ask questions in
    the review which could have been avoided otherwise.
+
+# Checklist for a design contribution
+
+This checklist contains the main sections that are expected on a proposal of a
+new Apertis design. The main difference of a design when compared to a
+component is the project-wide impact. If a component contribution has impact
+that goes beyond the expected additional maintenance effort, a design document
+is likely to be required before the component can be added to Apertis. We use
+here the same example we used on the [Contribution Process: Adding designs to Apertis]( {{< ref "contribution_process.md#adding-designs-to-apertis" >}} ).
+
+1. **What is the design proposal goal?** In our example the goal is to provide
+   tools and workflows for process automation by including the
+   [Robot Framework](https://robotframework.org/) in the Apertis Universe.
+1. **What is the state-of-the-art for addressing the goals of the design proposal?**
+   In our example the Robot Framework is not the only process automation
+   framework available. The goal here is to compare the Robot Framework to other
+   existing solutions, and include a rationale of why Robot Framework was
+   chosen.
+1. **How does the design work?** Following our example this section should explain
+   what Robot Framework is, how it works, what is the architecture, and mention
+   use cases.
+1. **What is the potential impact on Apertis?** This is a very important section,
+   and all known details should be included. For the Robot Framework we would
+   describe the potential impact on the Apertis development workflow, on the
+   content of Apertis test images, and on the Apertis testing infrastructure.
+1. **What are the benefits for the Apertis Universe?** This section should explain
+   the benefits to Apertis, such as offering a popular feature that will bring
+   new users to Apertis.
+1. **What is the license of the main components?** Do we plan to ship components on
+   Apertis target images? Robot Framework is released under [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0.html),
+   and we do not expect to ship Robot Framework components on Apertis target
+   images.
+1. **What is the proposal to integrate the design into Apertis?** In our example we
+   describe how to address the integration with Apertis taking into account the
+   constraints of the Apertis development workflow, of testing Apertis images, and
+   of the Apertis testing infrastructure. Remember to mention deprecating
+   existing components if needed.
+1. **High level description of the estimated work.** For integrating Robot
+   Framework into Apertis will involve developing and/or modifying Robot
+   Framework libraries; and developing a run-time compatibility layer for LAVA to
+   keep testing environments as close as possible to production environments, and
+   to adapt the execution of Robot Framework tests to suit the LAVA constraints.
+1. **High level implementation plan.** Describe the main work packages and the
+   execution order.
+
+{{% notice note %}}
+This list contains the general topics, but it may not be complete for all
+designs. Regarding the level of details the design document should be complete
+enough to describe the design and surrounding problems to developers and
+project managers, but it is not necessary to describe implementation details.
+{{% /notice %}}
+
+As a rule of thumb start with a lean design document and submit it for review
+as early as possible. You can send a new design for review to the same channels
+used for a [component contribution]( {{< ref "contribution_process.md#development-process" >}} ).

content/policies/contribution_process.md

@@ -236,6 +236,110 @@ either to the packages upstream or Debian. More guidance is provided in the
 [upstreaming]( {{< ref "upstreaming.md" >}} ) documentation.
 
 
+## Adding designs to Apertis
+
+Another way to contribute to Apertis is with design documents. A design
+document contains the description of all relevant aspects of a feature or of a
+requirement. As an example of a design document the
+[Apertis secure boot]( {{< ref "secure-boot.md"  >}} )
+describes what secure boot is, how it works, what are the threat models, the
+required infrastructure, and finally the integration with Apertis.
+
+Currently Apertis has [Concept Designs]( {{< ref "concepts" >}} ) that are
+documents covering topics that have been researched but not necessarily
+implemented, and [Designs]( {{< ref "designs"  >}}  ) which reflects what is
+currently implemented.
+
+Project-wide impact is the metric used to decide if a contribution will be
+handled as a component or as a design. If the impact of the contribution on the
+Apertis project goes beyond the additional maintenance effort, it is likely to
+require a design document before the component contribution.
+
+As an example we will consider a proposal to provide tools and workflows for
+process automation by including the [Robot Framework](https://robotframework.org/)
+in the Apertis Universe. The Robot Framework is a generic open source
+automation framework that can be used for automation of tests and processes.
+Robot Framework is released under
+[Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
+However we do not expect to ship Robot Framework components on Apertis target images.
+
+The first important consideration is the state-of-the-art for addressing the
+goals of the design. In our example the Robot Framework is preferred due it's
+maturity, unique and simple to use descriptive language, and it's active
+development community. However a strong argument in favor of the Robot
+Framework is it's user base. Adding the Robot Framework to the Apertis Universe
+is expected to bring Robot Framework users to Apertis.
+
+The next important consideration are how the design is expected to work and the
+potential impact on Apertis. The Robot framework has a layered architecture.
+The top layer is the simple, powerful, and extensible keyword-driven
+descriptive language for testing and automation.  This language resembles a
+natural language, is quick to develop, is easy to reuse, and is easy to extend.
+On the bottom layer of the architecture is the item to be tested, or the
+process to be automated.
+
+The middle layer is what makes the Robot Framework extensible: libraries. A
+library, in Robot Framework terminology, extends the Robot Framework language
+with new keywords, and provides the implementation for these new keywords. Each
+Robot Framework library acts as glue between the high level language and low
+level details of the item being tested, or of the environment in which the item
+to be tested is present.
+
+Adding the Robot Framework to the Apertis Universe has potential to impact:
+1. Development workflow: Apertis encourages the use of continuous integration
+   and the use of shared infrastructure resources instead of resources that are
+   private to specific developers.
+1. Testing Apertis images: Apertis encourages the use of environments that are
+   as close as possible to production environments, meaning that ideally, the
+   Apertis images under test are not instrumented for testing, and are only
+   minimally modified.
+1. Testing infrastructure: Apertis uses LAVA for deployment of operating system
+   and software in hardware, and for automated testing. The two main
+   constraints are LAVA being asynchronous and non-interactive. While both
+   developers and CI pipelines can submit jobs to LAVA, they cannot interact with
+   a job while it is running. The LAVA workflow is: submit a job, wait for the job
+   to be selected for execution, wait for the job to complete execution, and
+   download test results.
+
+Addressing the benefits of the new design proposal is also important. As
+mentioned, adding tools and workflows for process automation with the Robot
+Framework will extend the Apertis projects and we expect to attract more users
+by doing so. Adding real-world use cases can illustrate the value with a good
+level of details.
+
+The proposal should also describe how to address the integration with Apertis
+taking into account the constraints of the Apertis development workflow, of
+testing Apertis images, and of the Apertis testing infrastructure.
+
+The design proposal can also include a high level description of the estimated
+work. For example, adding Robot Framework to Apertis will involve developing
+and/or modifying Robot Framework libraries; and developing a run-time
+compatibility layer for LAVA to keep testing environments as close as possible
+to production environments, and to adapt the execution of Robot Framework tests
+to suit the LAVA constraints.
+
+And finally it could contain a high level implementation plan. In our example,
+one possible way to integrate Robot Framework is to adopt it in stages:
+1. Add Robot Framework to the Apertis SDK to enable developers to use the Robot
+   Framework locally
+1. Robot Framework Integration development: Adapt libraries and create the
+   run-time compatibility layer for LAVA
+1. Deployment on the Apertis infrastructure
+
+{{% notice note %}}
+
+This section describes general topics, but it may not be complete for all
+designs. Regarding the level of details the design document should be complete
+enough to describe the design and surrounding problems to developers and
+project managers, but it is not necessary to describe implementation details.
+
+{{% /notice %}}
+
+As a rule of thumb start with a lean design document and submit it for review
+as early as possible. You can send a new design for review to the same channels
+used for a [component contribution]( {{< ref "#development-process" >}} ).
+
+
 # Development Process
 
 The process for contributing code to Apertis is the same as for many other open