Attention

EWAOL development has moved to the SOAFEE Special Interest Group and is now hosted at https://gitlab.com/soafee/ewaol/meta-ewaol,
and the official documentation at: https://meta-ewaol.docs.soafee.io/.
For more details on SOAFEE, please see https://soafee.io/.
Note the following documentation is only applicable to the EWAOL’s repo hosted here: https://gitlab.arm.com/ewaol/meta-ewaol.

Contributing

EWAOL welcomes contributions via the meta-ewaol public Gitlab repository: https://gitlab.arm.com/ewaol/meta-ewaol.

Contributions should follow the project’s contribution guidelines, below.

Contribution Guidelines

The following is a set of guidelines that must be adhered to for contributions to be reviewed and accepted by the EWAOL project:

The contribution should be aligned with the goals and scope of the project.

EWAOL forms the reference software implementation of the SOAFEE project (https://soafee.io). Contributions should therefore be generally applicable to other downstream consumers of meta-ewaol.
Contributions should be high-quality, and should pass all tests within the repository’s Quality Assurance (QA) check suite.

A contribution must adhere to a set of minimal standards defined by the project. These are grouped as follows, listed here as a link to more detail about the requirements:
A set of QA checks are provided by the project to help automatically validate that a contribution meets these minimal standards. However, each of the links above may include additional expectations that are not appropriate for automatic validation via an associated QA check, but should still be adhered to. Note that all contributions will undergo a code-review process.

See Quality Assurance Checks for details on how to run the QA checks.
The contribution must be appropriately licensed.

It is expected that all contributions are licensed under the project’s standard license (see License for details), except for files that represent modifications to externally licensed works (for example, patch files), which may be contributed under alternative licenses in order to be compliant with the licensing requirements of the associated external works.
Contributions must include appropriate documentation.

Contributions which change the documentation should be validated by running the Documentation Build Validation step.
The contribution should not introduce software regressions.

Contributions which introduce image build failures or integration test failures will not be accepted.
Contributions that introduce additional run-time functionality to EWAOL distribution images should be accompanied by run-time integration tests to validate the functionality.

Any additional run-time integration tests or test suites must be documented, and follow a similar design to the validation tests described in Validation.
Security aspects of contributions must be considered as part of EWAOL’s Secure Development Lifecycle (SDL) process.

EWAOL’s SDL process is currently handled on a per-contribution basis, and it is expected that any security aspects raised by the project’s maintainer(s) will be engaged with before the contribution can be accepted.

Example security aspects that must be considered as part of a contribution include:
- The contribution’s effect on the management and storage of data onto temporary or persistent filesystems, and whether appropriate access controls to stored data (e.g. filesystem permissions) have been put in place.
- The contribution’s effect on data communications (both transmitted or received) taking place on the EWAOL distribution, such as changes or additions involving client and server processes, and whether appropriate security mechanisms (e.g. secure protocols, data encryption) have been put in place.

Minimal Contribution Standards

Each contribution must meet a set of minimum requirements, listed below. A subset of these requirements are checked automatically by the QA check tooling, which is described in Quality Assurance Checks.

Note

More detail on the validation steps performed by each check are included as in-source documentation at the top of each check Python module within the tools/qa-checks directory. In addition, any failed validation will output the specific reason for the failure, enabling it to be fixed prior to submitting the contribution.

Commit Message

Each commit message of the contribution should adhere to the following requirements:

The message title (first line) must not be blank.

The title should include the associated layer or component as a prefix. For example, a commit that updates the documentation should be prefixed with doc:, or a commit that updates the run-time integration tests in the meta-ewaol-tests layer should be prefixed with ewaol-tests: (note that meta- should be dropped for brevity). More precise prefixes should be provided if the commit applies only to a particular component. For example, a commit that adds a Linux kernel patch to the meta-ewaol-distro layer should use a prefix ewaol-distro/linux:. Commits which effect multiple layers or components can include multiple prefixes separated via a comma.

The first letter in the title after the prefix should be capitalized, if appropriate.

The number of characters in the title must not be greater than 80.

The second line must be blank to separate the message title and body.

The number of characters in each line of the message body must not be greater than 80, unless this is unavoidable (for example, a URL).

A sign-off must be be included in the message, with the following format: Signed-off-by: Name <valid@email.dom>. Note that the given email must also be formed correctly.

Please refer to the Git commit log of the repository for further examples of the expected format.

Documentation

The documentation should build successfully without errors or warnings. Validation of the documentation build is performed as part of the QA-check suite by default.

The rendered documentation should be checked to ensure the formatting is as expected, and no new formatting problems have been introduced. See Documentation Build Validation tool for details on building the rendered documentation.

Inclusive Language

The project aims to promote usage of inclusive language wherever possible, and so it is expected that contributions avoid introducing non-inclusive language into the repository.

To help identify potential usage of non-inclusive language, a check is performed as part of the QA check suite to highlight occurrences within the repository, so that alternatives may be considered. To support this automated check, a list of potentially non-inclusive terminology is maintained in the project configuration files at meta-ewaol-config/qa-checks/non-inclusive-language.txt.

As there are situations in which the terminology highlighted by the check is not used in a non-inclusive manner, or its usage is otherwise unavoidable, a usage can be tagged as excluded from the check by adding the text inclusivity-exception prior to the occurrence (either in the previous line or in the same line). So that this tag is not considered as part of the file’s normal contents, it should be commented or otherwise excluded from the file’s expected usage.

License and Copyright Header

Contributed files must contain a valid license and copyright header, following one of the two following formats, based on the source of the contribution:

Original works contributed to the project:
Copyright (c) YYYY(-YYYY), <Contributor>
SPDX-License-Identifier: <License name>
Modified externally-licensed works contributed to the project:
Based on: <original file>
In open-source project: <source project/repository>

Original file: Copyright (c) YYYY(-YYYY) <Contributor>
Modifications: Copyright (c) YYYY(-YYYY) <Contributor>

SPDX-License-Identifier: <License name>
Note

Please follow the contribution guideline relating to licensing in order to select the appropriate SPDX License Identifier for the contributed files.

The license and copyright header QA check expects the header lines to be commented. The current implementation therefore expects each line to begin with one of the following set of characters: #, //, *, ;. Please refer to the current files within the repository for further guidance on how to include valid headers for different file types.

For each file with such a header, the final copyright year of the modifications must match or be later than the latest year that the file was modified in the git commit tree.

As some files within the project are inappropriate to license with a plain-text header (for example, .png image files), some file types are excluded as part of the QA check configuration. Running the QA check will highlight any files which are expected to include a valid header, but do not.

Python Code Quality

All Python code contributed to the project must pass validation by the Python style guide checker pycodestyle, which enforces style conventions based on the PEP 8 style guide for Python code. The precise Python style conventions that pycodestyle validates can be found in the pycodestyle Documentation.

Shell Script Code Quality

All shell scripts and BATS files contributed to the project must produce no warnings when passed to the Shellcheck static analysis tool, as made available by the shellcheck-py Python package.

Documentation for each specific check is documented within the Shellcheck wiki pages.

Spelling

The project expects documentation to have correct English (en-US) spelling. Words within documentation text files have their spelling validated via the pyspellchecker Python package.

As many project files are technical in nature with non-standard English words, a file containing a list of additional valid words exists at meta-ewaol-config/qa-checks/ewaol-dictionary which may be modified if the QA check erroneously highlights valid technical terminology.

YAML Formatting

All YAML files contributed to the project must pass validation as evaluated by the yamllint Python-based linter for YAML files, which should report no warnings or errors. This is run by default as part of the QA checks.

For more details on yamllint see yamllint documentation.

Yocto Layer Compatibility

Contributions must not break layer compatibility with the Yocto Project, as validated via the Yocto Project’s yocto-check-layer script, documented as part of the Yocto Project Documentation at Yocto Check Layer Script.

As the validation script can take several minutes to run, it is not performed as part of the QA check script by default. Instead, it should be enabled by passing --check=layer to run only the layer compatibility check, or by passing --check=all to the script to run all the checks including the layer compatibility check. For example:

./tools/qa-checks/run-checks.py --check=layer

The layer compatibility QA check runs as a containerized application using Docker. Docker must therefore be installed on the host environment to perform this QA check. See the Docker documentation for installation instructions.

Further details for running the QA checks are given at Quality Assurance Checks.

Contribution Process

Adhering to the contributions guidelines listed above, contributions to the EWAOL project should be made using the process listed in this section.

Gitlab Account Setup

In order to contribute to the repository, it is necessary to have an account on https://gitlab.arm.com. Please see https://gitlab.arm.com/documentation/contributions for details of how to create an account and request a fork of the meta-ewaol repository.

Submission

Note

The mechanics of the EWAOL submission process has not yet been established. The process described here is therefore subject to change.

With an appropriate Gitlab account, a contribution can be submitted to https://gitlab.arm.com/ewaol/meta-ewaol via the following process:

If the contribution relates to a Gitlab Issue (for example, fixes a reported bug, resolves a raised security concern, or implements a related feature request) please include the relevant meta-ewaol Gitlab Issue ID within the Git commit message(s) of the contribution.
Fork the meta-ewaol Gitlab repository.
Push changes to a branch on the forked repository. This contribution branch should be based on the latest development branch of meta-ewaol, which is: kirkstone-dev.
Submit a Merge Request to meta-ewaol using the contribution branch on the forked repository. Please include all information required by the project’s Merge Request template.

Supporting Tools

To support contributions, the project provides tooling for building and validating the documentation, and for running automated quality-assurance validation related to the minimal standards listed in Minimal Contribution Standards. These tools are detailed below.

Documentation Build Validation

EWAOL provides a Python script to locally build and render the documentation, available at tools/build/doc-build.py. This script will install all necessary Python packages into a temporary Python Virtual Environment, and generate an HTML version of the documentation under public/. The script requires Python 3.8 or greater, and to build the EWAOL documentation should be called from the meta-ewaol directory via:

./tools/build/doc-build.py

The generated documentation can be accessed by opening public/index.html in a web browser.

For further information about the parameters, call the help function of the script:

./tools/build/doc-build.py --help

Quality Assurance Checks

The project provides tooling for running Quality Assurance (QA) checks on the repository. These checks aim to automatically validate that contributions adhere to a set of minimal standards, defined by the project and documented earlier at Minimal Contribution Standards.

The tooling is provided as a set of Python scripts that can be found within the tools/qa-checks/ directory of the repository. In order to run the tool, the system must have installed Python 3 (version 3.8 or greater), the PyYAML Python package available via pip (5.4.1 is the project’s currently supported version), and Git version 2.25 or greater.

Note

Git version 2.25 may not be available via the default PPAs included with Ubuntu 18.04. On this distribution, it can be made available via the Git stable releases PPA: add-apt-repository ppa:git-core/ppa

The QA-checks should be run for each commit of the contribution, by executing run-checks.py via the following command:

./tools/qa-checks/run-checks.py --check=all

The script should pass with no errors or warnings.