Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • eclipse/oniro-core/docs
  • agherzan/docs
  • shettygururaj/docs
  • dricci783/docs
  • lucafavaretto/docs
  • lucazizolfi/docs
  • landgraf/docs
  • nawab/docs
  • mrybczyn/docs
  • esben/docs
  • lucaseri/docs
  • kristis/docs
  • bero/docs
  • gwozdzcfs/docs
  • ghassaneben/oniro-docs
  • zyga/oniro-docs
  • pcoval/oniro-docs
  • stefanschmidt/docs2
  • kzarka/docs
19 results
Show changes
Commits on Source (48)
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 1424 additions and 118 deletions
.gitlab-ci.yml
View file @ 940f44cb
...@@ -8,12 +8,13 @@ stages: ...@@ -8,12 +8,13 @@ stages:
- deploy - deploy
include: include:
- project: eclipse/oniro-core/oniro - project: eclipse/oniro-core/oniro
ref: kirkstone ref: kirkstone
file: file:
- .oniro-ci/dco.yaml - .oniro-ci/dco.yaml
- .oniro-ci/reuse.yaml - .oniro-ci/reuse.yaml
- .oniro-ci/build-generic.yaml - project: 'eclipsefdn/it/releng/gitlab-ci-templates'
file: '/jobs/eca.gitlab-ci.yml'
dco: dco:
extends: .dco extends: .dco
...@@ -26,50 +27,226 @@ reuse: ...@@ -26,50 +27,226 @@ reuse:
rules: rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
# Customize the .workspace job to set the path of the git repository to deviate eca:
# from what the git-repo manifest prepares. This effectively allows testing extends: .eca
# incoming changes that match the repository holding this CI pipeline.
.workspace: # Naming scheme for variables is defined as follows:
#
# CI_ONIRO_*:
# Oniro specific variables used during CI/CD process. Variables in this group
# should use meaningful names and avoid abbreviations, if possible.
#
# CI_ONIRO_MANIFEST_REPO_{URL,REV}:
# URL and revision of the manifest repository.
#
# CI_ONIRO_MANIFEST_MIRROR_REPO_{URL,REV,DIR}:
# URL, revision and directory path of the mirror of manifest repository.
# This repository is used to speed up construction of repo workspace.
#
# CI_ONIRO_REPO_WORKSPACE_DIR:
# Directory path of repo workspace.
#
# CI_*:
# Third party variables used during CI/CD process, defined by GitLab.
# Variables in this group are defined by GitLab and retain their original
# name.
#
# GIT_STRATEGY, CACHE_COMPRESSION_LEVEL:
# Part of GitLab interface.
.oniro-repo-workspace:
interruptible: true
image:
name: registry.ostc-eu.org/ostc/oniro/bitbake-builder:latest
variables: variables:
CI_ONIRO_GIT_REPO_PATH: docs # URL and branch or revision of the oniro.git repository which contains a
# repo manifest file.
#
# The revision should be bumped during the major release of Oniro but both
# variables can be changed to CI_PROJECT_URL/CI_COMMIT_SHA when testing
# changes landing to oniro.git.
CI_ONIRO_MANIFEST_REPO_URL: https://gitlab.eclipse.org/eclipse/oniro-core/oniro.git
CI_ONIRO_MANIFEST_REPO_REV: kirkstone
# URL and branch used with repo "repo --mirror" to speed up workspace
# construction.
#
# Those are distinct from CI_ONIRO_MANIFEST_REPO_{URL,REV} because the
# former variables can be redirected to CI_PROJECT_URL and CI_COMMIT_SHA,
# while those two stay fixed.
#
# The revision should _only_ be bumped during the major release of Oniro.
CI_ONIRO_MANIFEST_MIRROR_REPO_URL: https://gitlab.eclipse.org/eclipse/oniro-core/oniro.git
CI_ONIRO_MANIFEST_MIRROR_REPO_REV: kirkstone
# Directory where repo mirror is constructed. This location is covered by
# GitLab cache system, and will be reused between pipelines of the same
# project. Note that the .cache directory name is special.
CI_ONIRO_MANIFEST_MIRROR_REPO_DIR: $CI_PROJECT_DIR/.cache/repo-mirror
# XML snippet to inject as a "local manifest" for repo. Those allow arbitrary
# modifications to the project structure to happen before "repo sync" is used
# to construct the workspace.
#
# The default interpreter for the local manifest is plain "echo". For some
# more complex cases, where inline shell is required, use "eval" instead
# and put "cat" echo into the local manifest, coupled with a here-doc
# value.
CI_ONIRO_REPO_WORKSPACE_LOCAL_MANIFEST: ""
CI_ONIRO_REPO_WORKSPACE_LOCAL_MANIFEST_INTERPRETER: echo
# Directory where repo workspace is constructed.
CI_ONIRO_REPO_WORKSPACE_DIR: $CI_PROJECT_DIR/.tmp/repo-workspace
# Use fastest cache compression algorithm, as bulk of the cache is
# already-compressed git history.
CACHE_COMPRESSION_LEVEL: fastest
# Ask GitLab _not_ to check out the git repository associated with the
# project. This is, in a way, pointless, since we use repo, not pure git,
# to construct the workspace. Due to the fact that oniro is
# self-referential (the manifest refers to the repository that contains the
# manifest). This requires custom logic to behave correctly in scenarios
# that modify oniro.git in any way (e.g. a branch, a pull request or merge
# train).
GIT_STRATEGY: none
cache:
- key:
prefix: repo-mirror-$CI_ONIRO_MANIFEST_MIRROR_REPO_REV
files:
- default.xml
paths:
- $CI_ONIRO_MANIFEST_MIRROR_REPO_DIR
before_script:
# Define helper functions to generate GitLab fold markers.
- |
# Disable all the bitbake jobs, since we are not building any code here. function gl_section_open() {
.bitbake-workspace: printf '\e[0K''section_start'':%s:%s\r\e[0K%s\n' "$(date +%s)" "$1" "$2"
rules: }
- when: never
function gl_section_open_collapsed() {
printf '\e[0K''section_start'':%s:%s[collapsed=true]\r\e[0K%s\n' "$(date +%s)" "$1" "$2"
}
function gl_section_close() {
printf '\e[0K''section_end'':%s:%s\r\e[0K\n' "$(date +%s)" "$1"
}
# Query system information. This is mostly useful for forensics, when
# something goes wrong and access to basic information of this type can
# help to uncover the problem.
- gl_section_open_collapsed system_info "Querying system information"
- id
- uname -a
- cat /etc/os-release
- free -m
- lscpu
- env | grep -E '^CI_ONIRO' | sort
- gl_section_close system_info
# Set up Git with bot identity. Eclipse ECA check allows this user to
# create and send commits.
- gl_section_open_collapsed setup_git "Setting up git"
- git config --global --add safe.directory "$CI_PROJECT_DIR"
- git config --global user.name "Oniro Core Project Bot"
- git config --global user.email "oniro-core-bot@eclipse.org"
- gl_section_close setup_git
# Since CI_PROJECT_DIR is set to 'none', GitLab runner does not perform any
# cleanup operations on CI_PROJECT_DIR. In consequence, repo can observe
# junk brought in by previous executions on the same runner, and get
# confused. Perform manual cleanup by removing all top-level items, other
# than .cache, where the cache items are strategically located, before
# proceeding.
- gl_section_open_collapsed cleanup_project_dir "Clean-up project directory"
- find "$CI_PROJECT_DIR" -mindepth 1 -maxdepth 1 ! -name .cache -exec rm -rf {} \;
- ls -la "$CI_PROJECT_DIR"
- gl_section_close cleanup_project_dir
# Create and update a mirror for repo, using the semi-fixed manifest mirror
# repo URL and revision. Since this is cached, the "repo init" part is
# rarely executed (see the test command below), and only the forced
# synchronization is executed.
#
# Note that the location of the mirror is stored in GitLab cache using the
# repo revision as cache key, allowing multiple releases to co-exist
# efficiently.
- gl_section_open_collapsed repo_mirror_setup "Setting up repo mirror"
- mkdir -p "$CI_ONIRO_MANIFEST_MIRROR_REPO_DIR"
- pushd "$CI_ONIRO_MANIFEST_MIRROR_REPO_DIR"
- echo "Initializing repository mirror from $CI_ONIRO_MANIFEST_MIRROR_REPO_URL and $CI_ONIRO_MANIFEST_MIRROR_REPO_REV"
- test ! -e .repo && repo init --mirror --manifest-url "$CI_ONIRO_MANIFEST_MIRROR_REPO_URL" --manifest-branch "$CI_ONIRO_MANIFEST_MIRROR_REPO_REV" --no-clone-bundle
- echo "Synchronizing repository mirror"
- repo sync --force-sync || ( rm -rf .repo && repo init --mirror --manifest-url "$CI_ONIRO_MANIFEST_MIRROR_REPO_URL" --manifest-branch "$CI_ONIRO_MANIFEST_MIRROR_REPO_REV" --no-clone-bundle && repo sync)
- gl_section_close repo_mirror_setup
# Create a repo workspace using the mirror as reference. This is fairly
# efficient, as repo will hardlink files (assuming they live on the same
# filesystem) and avoid bulk of the network traffic.
- gl_section_open_collapsed repo_workspace_setup "Setting up repo workspace"
- rm -rf "$CI_ONIRO_REPO_WORKSPACE_DIR" && mkdir -p "$CI_ONIRO_REPO_WORKSPACE_DIR"
- pushd "$CI_ONIRO_REPO_WORKSPACE_DIR"
- echo "Initializing repository workspace from $CI_ONIRO_MANIFEST_REPO_URL and $CI_ONIRO_MANIFEST_REPO_REV"
- repo init --reference "$CI_ONIRO_MANIFEST_MIRROR_REPO_DIR" --manifest-url "$CI_ONIRO_MANIFEST_REPO_URL" --manifest-branch "$CI_ONIRO_MANIFEST_REPO_REV" --no-clone-bundle
- mkdir -p "${CI_ONIRO_REPO_WORKSPACE_DIR}/.repo/local_manifests"
- test -n "${CI_ONIRO_REPO_WORKSPACE_LOCAL_MANIFEST:-}" && "$CI_ONIRO_REPO_WORKSPACE_LOCAL_MANIFEST_INTERPRETER" "$CI_ONIRO_REPO_WORKSPACE_LOCAL_MANIFEST" | tee "${CI_ONIRO_REPO_WORKSPACE_DIR}/.repo/local_manifests/local.xml"
- echo "Synchronizing repository workspace"
- repo sync --force-sync
- gl_section_close repo_workspace_setup
# Define a build-docs job that extends both the .workspace, for the general
# workspace setup, and .build-docs, for the documentation build logic. The
# script first assembles the workspace and then proceeds to build the
# documentation.
#
# The job extends more than one parent, with the order being relevant for,
# among others, the "rules" section.
build-docs: build-docs:
extends: [.workspace, .build-docs] extends: [.oniro-repo-workspace]
variables: interruptible: true
CI_ONIRO_INSTANCE_SIZE: s3.large.2 image:
name: registry.ostc-eu.org/ostc/oniro/docs-builder:latest
script: script:
- !reference [.workspace, script] - make -C docs
- !reference [.build-docs, script] - mv docs/build "$CI_PROJECT_DIR"
# Artifacts are relative to CI_PROJECT_DIR so we need to provide the build
# docs there.
- mv "$SCRATCH_DIR"/docs/build/ "$CI_PROJECT_DIR" || true
artifacts: artifacts:
paths: paths:
- build - build
variables:
# When the workspace is created, substitute the "docs" repository that
# described by the manifest with the project being tested. This works for
# forks and branches but not for merge requests. For that look at the build
# rule below.
CI_ONIRO_REPO_WORKSPACE_LOCAL_MANIFEST: >
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
<!-- remove original docs project entry -->
<remove-project name="oniro-core/docs.git" />
<!-- add remote representing the project -->
<remote name="oniro-override" fetch="${CI_PROJECT_URL}/../" />
<!-- add docs at the exact version are testing -->
<project name="${CI_PROJECT_NAME}" path="docs" remote="oniro-override" revision="${CI_COMMIT_SHA}" />
</manifest>
rules: rules:
# Build the docs when a merge request is created. # During the merge request, substitute the "docs" repository that is
# described by the manifest with the project that is the source of the
# merge request. This does not test the merged result but is the next best
# thing we can do right now.
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
variables:
CI_ONIRO_REPO_WORKSPACE_LOCAL_MANIFEST_INTERPRETER: eval
CI_ONIRO_REPO_WORKSPACE_LOCAL_MANIFEST: |
cat <<__EOM__
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
<!-- remove original docs project entry -->
<remove-project name="oniro-core/docs.git" />
<!-- add remote representing the project -->
<remote name="oniro-override" fetch="${CI_MERGE_REQUEST_SOURCE_PROJECT_URL}/../" />
<!-- add docs at the exact version are testing -->
<project name="$(basename "$CI_MERGE_REQUEST_SOURCE_PROJECT_PATH")" path="docs" remote="oniro-override" revision="${CI_COMMIT_SHA}" />
</manifest>
__EOM__
# Or when things land. # Or when things land.
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
deploy: deploy:
extends: .workspace extends: .oniro-repo-workspace
image:
name: registry.ostc-eu.org/ostc/oniro/docs-builder:latest
stage: deploy stage: deploy
script: script:
- !reference [.workspace, script] # We are in the root of the git-repo workspace. Because
# We are in the root of the git-repo workspace. # .oniro-repo-workspace uses GIT_STRATEGY=none, the workspace is not
# cleaned automatically.
- rm -rf aggregated
- git clone https://user:$CI_ONIRO_AGGREGATED_DOCS_TOKEN@gitlab.eclipse.org/eclipse/oniro-core/oniro-readthedocs-aggregated.git aggregated - git clone https://user:$CI_ONIRO_AGGREGATED_DOCS_TOKEN@gitlab.eclipse.org/eclipse/oniro-core/oniro-readthedocs-aggregated.git aggregated
- find aggregated -maxdepth 1 -not -path aggregated/.git -not -path aggregated -exec rm -rvf {} \; - find aggregated -maxdepth 1 -not -path aggregated/.git -not -path aggregated -exec rm -rvf {} \;
- tar -c --dereference -C docs --exclude ./.git --exclude ./.gitlab-ci.yml . | tar -x -C aggregated - tar -c --dereference -C docs --exclude ./.git --exclude ./.gitlab-ci.yml . | tar -x -C aggregated
......
CONTRIBUTING.md
View file @ 940f44cb
...@@ -4,17 +4,29 @@ SPDX-FileCopyrightText: Huawei Inc. ...@@ -4,17 +4,29 @@ SPDX-FileCopyrightText: Huawei Inc.
SPDX-License-Identifier: CC-BY-4.0 SPDX-License-Identifier: CC-BY-4.0
--> -->
- [Gitlab Contributions](#gitlab-contributions) - <a href="#eclipse-contributor-agreement" id="toc-eclipse-contributor-agreement">Eclipse Contributor Agreement</a>
- [Overview](#overview) - <a href="#gitlab-contributions" id="toc-gitlab-contributions">Gitlab Contributions</a>
- [Commit Guidelines](#commit-guidelines) - <a href="#overview" id="toc-overview">Overview</a>
- [Contributions to Documentation](#contributions-to-documentation) - <a href="#git-setup" id="toc-git-setup">Git setup</a>
- [REUSE Compliance](#reuse-compliance) - <a href="#commit-guidelines" id="toc-commit-guidelines">Commit Guidelines</a>
- [SPDX Information and REUSE Standard](#spdx-information-and-reuse-standard) - <a href="#contributions-to-documentation" id="toc-contributions-to-documentation">Contributions to Documentation</a>
- [SPDX Header Example](#spdx-header-example) - <a href="#creating-merge-requests" id="toc-creating-merge-requests">Creating merge requests</a>
- [Substantial Contributions](#substantial-contributions) - <a href="#reuse-compliance" id="toc-reuse-compliance">REUSE Compliance</a>
- [DCO sign-off](#dco-sign-off) - <a href="#spdx-information-and-reuse-standard" id="toc-spdx-information-and-reuse-standard">SPDX Information and REUSE Standard</a>
- [Overview](#overview-1) - <a href="#spdx-header-example" id="toc-spdx-header-example">SPDX Header Example</a>
- [Developer Certificate of Origin](#docs_dco) - <a href="#dep5-files-paragraph-examples" id="toc-dep5-files-paragraph-examples">DEP5 "Files" Paragraph Examples</a>
- <a href="#substantial-contributions" id="toc-substantial-contributions">Substantial Contributions</a>
- <a href="#dco-sign-off" id="toc-dco-sign-off">DCO sign-off</a>
- <a href="#overview-1" id="toc-overview-1">Overview</a>
- <a href="#docs_dco" id="toc-docs_dco">Developer Certificate of Origin</a>
# Eclipse Contributor Agreement
Before your contribution can be accepted by the project team, contributors must electronically sign the [Eclipse Contributor Agreement (ECA)](http://www.eclipse.org/legal/ECA.php).
Commits must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. Also, an associated Eclipse Foundation account needs to be in place with a signed Eclipse Contributor Agreement on file. These requirements are enforced by the Eclipse Foundation infrastructure tooling.
For more information, please see the [Eclipse Committer Handbook](https://www.eclipse.org/projects/handbook/#resources-commit).
# Gitlab Contributions # Gitlab Contributions
...@@ -22,6 +34,19 @@ SPDX-License-Identifier: CC-BY-4.0 ...@@ -22,6 +34,19 @@ SPDX-License-Identifier: CC-BY-4.0
Oniro Project handles contributions as [merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/) to relevant repositories part of the Oniro Project [GitLab instance](https://gitlab.eclipse.org/eclipse/oniro-core). The flow for handling that is classic: fork-based merge requests. This means that once you have an account, you can fork any repository, create a branch with proposed changes and raise a merge request against the forked repository. More generic information you can find on the Gitlab's documentation as part of ["Merge requests workflow"](https://docs.gitlab.com/ee/development/contributing/merge_request_workflow.html). Oniro Project handles contributions as [merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/) to relevant repositories part of the Oniro Project [GitLab instance](https://gitlab.eclipse.org/eclipse/oniro-core). The flow for handling that is classic: fork-based merge requests. This means that once you have an account, you can fork any repository, create a branch with proposed changes and raise a merge request against the forked repository. More generic information you can find on the Gitlab's documentation as part of ["Merge requests workflow"](https://docs.gitlab.com/ee/development/contributing/merge_request_workflow.html).
## Git setup
Clone your fork locally, enter its directory and set:
``` bash
$ git config --local user.email <your_eclipse_account_email>
$ git config --local user.name <your_eclipse_full_name>
```
To push and pull over HTTPS with Git using your account, you must set a password or [a Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) .
If you want to push or pull repositories using SSH, you have to [add a SSH key](https://docs.gitlab.com/ee/user/ssh.html) to your profile.
## Commit Guidelines ## Commit Guidelines
<div class="note"> <div class="note">
...@@ -40,39 +65,39 @@ At its core, contributing to the Oniro Project project means *wrapping* your wor ...@@ -40,39 +65,39 @@ At its core, contributing to the Oniro Project project means *wrapping* your wor
To achieve this, we maintain the following commit guidelines: To achieve this, we maintain the following commit guidelines:
- Each commit should be able to stand by itself providing a building block as part of the MR. - Each commit should be able to stand by itself providing a building block as part of the MR.
- A good balance of granularity with scoped commits helps to handle backports (e.g. cherry-picks) and also improves the ability to review smaller chunks of code taking commit by commit. - A good balance of granularity with scoped commits helps to handle backports (e.g. cherry-picks) and also improves the ability to review smaller chunks of code taking commit by commit.
- Changes that were added on top of changes introduced in the MR, should be squashed into the initial commit. - Changes that were added on top of changes introduced in the MR, should be squashed into the initial commit.
- For example, a MR that introduced a new build system recipe and, as a separate commit, fixed a build error in the initial recipe. The latter commit should be squashed into the initial commit. - For example, a MR that introduced a new build system recipe and, as a separate commit, fixed a build error in the initial recipe. The latter commit should be squashed into the initial commit.
- For example, a MR introducing a new docs chapter and also adding, as a separate commit, some typo fixes. The latter commits should be squashed into the initial commit. - For example, a MR introducing a new docs chapter and also adding, as a separate commit, some typo fixes. The latter commits should be squashed into the initial commit.
- There is a small set of exceptions to this rule. All these exceptions gravitate around the case where an MR, even if it provides multiple commits in the same scope (for example, to the same build recipe), each of the commits has a very specific purpose. - There is a small set of exceptions to this rule. All these exceptions gravitate around the case where an MR, even if it provides multiple commits in the same scope (for example, to the same build recipe), each of the commits has a very specific purpose.
- For example, a line formating change followed by a chapter addition change in the same documentation file. - For example, a line formating change followed by a chapter addition change in the same documentation file.
- Also, it can be the case of two functional changes that are building blocks in the same scope. - Also, it can be the case of two functional changes that are building blocks in the same scope.
- Another example where commits are not to be squashed is when having a commit moving the code and a commit modifying the code in the new location. - Another example where commits are not to be squashed is when having a commit moving the code and a commit modifying the code in the new location.
- Make sure you clean your code of trailing white spaces/tabs and that each file ends with a new line. - Make sure you clean your code of trailing white spaces/tabs and that each file ends with a new line.
- Avoid *merge* commits as part of your MR. Your commits should be rebased on top of the *HEAD* of the destination branch. - Avoid *merge* commits as part of your MR. Your commits should be rebased on top of the *HEAD* of the destination branch.
As mentioned above, *git log* becomes informally part of the documentation of the product. Maintaining consistency in its format and content improves debugging, auditing, and general code browsing. To achieve this, we also require the following commit message guidelines: As mentioned above, *git log* becomes informally part of the documentation of the product. Maintaining consistency in its format and content improves debugging, auditing, and general code browsing. To achieve this, we also require the following commit message guidelines:
- The *subject* line (the first line) needs to have the following format: `scope: Title limited to 80 characters`. - The *subject* line (the first line) needs to have the following format: `scope: Title limited to 80 characters`.
- Use the imperative mood in the *subject* line for the *title*. - Use the imperative mood in the *subject* line for the *title*.
- The *scope* prefix (including the colon and the following whitespace) is optional but most of the time highly recommended. For example, fixing an issue for a specific build recipe, would use the recipe name as the *scope*. - The *scope* prefix (including the colon and the following whitespace) is optional but most of the time highly recommended. For example, fixing an issue for a specific build recipe, would use the recipe name as the *scope*.
- The *title* (the part after the *scope*) starts with a capital letter. - The *title* (the part after the *scope*) starts with a capital letter.
- The entire *subject* line shouldn't exceed 80 characters (same text wrapping rule for the commit body). - The entire *subject* line shouldn't exceed 80 characters (same text wrapping rule for the commit body).
- The commit *body* separated by an empty line from the *subject* line. - The commit *body* separated by an empty line from the *subject* line.
- The commit *body* is optional but highly recommended. Provide a clear, descriptive text block that accounts for all the changes introduced by a specific commit. - The commit *body* is optional but highly recommended. Provide a clear, descriptive text block that accounts for all the changes introduced by a specific commit.
- The commit *body* must not contain more than 80 characters per line. - The commit *body* must not contain more than 80 characters per line.
- The commit message will have the commit message *trailers* separated by a new line from the *body*. - The commit message will have the commit message *trailers* separated by a new line from the *body*.
- Each commit requires at least a *Signed-off-by* trailer line. See more as part of the `/contributing/dco` document. - Each commit requires at least a *Signed-off-by* trailer line. See more as part of the `/contributing/dco` document.
- All *trailer* lines are to be provided as part of the same text block - no empty lines in between the *trailers*. - All *trailer* lines are to be provided as part of the same text block - no empty lines in between the *trailers*.
Additional commit message notes: Additional commit message notes:
- Avoid using special characters anywhere in the commit message. - Avoid using special characters anywhere in the commit message.
- Be succinct but descriptive. - Be succinct but descriptive.
- Have at least one *trailer* as part of each commit: *Signed-off-by*. - Have at least one *trailer* as part of each commit: *Signed-off-by*.
- You can automatically let `git` add the *Signed-off-by* by taking advantage of its `-s` argument. - You can automatically let `git` add the *Signed-off-by* by taking advantage of its `-s` argument.
- Whenever in doubt, check the existing log on the file (`<FILE>`) you are about to commit changes, using something similar to: `git log <FILE>`. - Whenever in doubt, check the existing log on the file (`<FILE>`) you are about to commit changes, using something similar to: `git log <FILE>`.
Example of a full git message: Example of a full git message:
...@@ -95,23 +120,36 @@ In terms of file format, the project unifies its documentation as `ReStructuredT ...@@ -95,23 +120,36 @@ In terms of file format, the project unifies its documentation as `ReStructuredT
As a rule of thumb, anything that ends up compiled in the project documentation is to maintain the RestructuredText file format. Text files that are not meant to be compiled as part of the project's documentation can be written in [Markdown](https://daringfireball.net/projects/markdown/). For example, a repository `README` file can be written in Markdown as it doesn't end up compiled in the project-wide documentation. As a rule of thumb, anything that ends up compiled in the project documentation is to maintain the RestructuredText file format. Text files that are not meant to be compiled as part of the project's documentation can be written in [Markdown](https://daringfireball.net/projects/markdown/). For example, a repository `README` file can be written in Markdown as it doesn't end up compiled in the project-wide documentation.
### Creating merge requests
Once your changes have been pushed to your fork, you are ready to prepare a merge request.
1. Go to your repository in an internet browser.
2. Create a merge request by clicking `Merge Requests` on left toolbar and press `New merge request`. Add an explainable description and create a merge request. Alternatively, you can enter the website of your fork. You should see a message that you pushed your branch to the repository. In the same section you can press `Create merge request`.
3. Before merging, it has to be reviewed and approved by Oniro Project repository maintainers. Read their review and add any required changes to your merge request.
4. After you polish your merge request, the maintainers will run the pipelines which check if your changes do not break the project and approve them. If everything is correct, your work is merged to the main project. Remember that each commit of the merge request should be a minimum, self-contained building block.
# REUSE Compliance # REUSE Compliance
## SPDX Information and REUSE Standard ## SPDX Information and REUSE Standard
All projects and files for an hosted project **MUST** be [REUSE](https://reuse.software/) compliant. REUSE requires SPDX information for each file, rules for which are as follows: All projects and files for an hosted project **MUST** be [REUSE](https://reuse.software/) compliant. REUSE requires SPDX information for each file, rules for which are as follows:
- Any new file must have a SPDX header (copyright and license). - for files copyrighted by projects contributors (**"First Party Files"**):
- For files that don't support headers (for example binaries, patches etc.) an associated `.license` file must be included with the relevant SPDX information. - any new file MUST have a SPDX header (copyright and license);
- Do not add Copyright Year as part of the SPDX header information. - for files that don't support headers (for example binaries, patches etc.) an associated `.license` file MUST be included with the relevant SPDX information;
- The general rule of thumb for the license of a patch file is to use the license of the component for which the patch applies. - do not add Copyright Year as part of the SPDX header information;
- When modifying a file through this contribution process, you may (but don't have to) claim copyright by adding a copyright line. - the general rule for patch files is to use the MIT license and *not* the license of the component for which the patch applies - the latter solution would be error-prone and hard to manage and maintain in the long run, and there may be difficult-to-handle cases (what if the patches modifies multiple files in the same component - eg. gcc - which are subject to different licenses?);
- Never alter copyright statements made by others, but only add your own. - when modifying a file through this contribution process, you may (but don't have to) claim copyright by adding a copyright line;
- you MUST NOT alter copyright statements made by others, but only add your own;
Some files will make an exception to the above rules as described below: - for files copyrighted by third parties and just added to the project by contributors, eg. files copied from other projects or back-ported patches (**"Third Party Files"**):
- if upstream files already have SPDX headers, they MUST be left unchanged;
- Files for which copyright is not claimed and for which this information was not trivial to fetch (for example backporting patches, importing build recipes etc. when upstream doesn't provide the SPDX information in the first place) - if upstream files do *not* have SPDX headers:
- license files (for example `common-licenses` in bitbake layers) - the exact upstream provenance (repo, revision, path) MUST be identified;
- you MUST NOT add SPDX headers to Third Party Files;
- copyright and license information, as well as upstream provenance information (in the "Comment" section), MUST be stored in <span class="title-ref">.reuse/dep5</span> following [Debian dep5 specification](https://dep-team.pages.debian.net/deps/dep5/) (see examples below);
- you MUST NOT use wildcards (\*) in dep5 "Files" paragraphs even if Debian specs allow it: it may lead to unnoticed errors or inconsistencies in case of future file additions that may be covered by wildcard expressions even if they have a different license;
- in case of doubts or problems in finding the correct license and copyright information for Third Party Files, contributors may ask the project's Legal Team in the project mailing list <oniro-dev@eclipse.org>;
### SPDX Header Example ### SPDX Header Example
...@@ -125,9 +163,29 @@ Make sure all of your submitted new files have a licensing statement in the head ...@@ -125,9 +163,29 @@ Make sure all of your submitted new files have a licensing statement in the head
*/ */
``` ```
### DEP5 "Files" Paragraph Examples
``` text
Files: meta-oniro-staging/recipes-containers/buildah/buildah_git.bb
Copyright: OpenEmbedded Contributors
License: MIT
Comment: Recipe file for buildah copied from meta-virtualization project at
https://git.yoctoproject.org/meta-virtualization,
recipes-containers/buildah.
README file of meta-virtualization project states:
"All metadata is MIT licensed unless otherwise stated."
Files: meta-oniro-staging/recipes-devtools/ninja/ninja/0001-feat-support-cpu-limit-by-cgroups-on-linux.patch
Copyright: Google Inc.
License: Apache-2.0
Comment: Patch for ninja backported from Ninja project at
https://github.com/ninja-build/ninja, commit 540be33
Copyright text left as found in the header of the patched file.
```
### Substantial Contributions ### Substantial Contributions
Therefore, if your contribution is only a patch directly applied to an existing file, then you are not required to do anything. If your contribution is an entire new project, or a substantial, copyrighted contribution, you **MUST** make sure that you do that following the [IP Policy](https://booting.oniroproject.org/distro/governance/ip-policy) and that you comply with REUSE standard to include the licensing information where they are required. Therefore, if your contribution is only a patch directly applied to an existing file, then you are not required to do anything. If your contribution is an entire new project, or a substantial, copyrighted contribution, you **MUST** make sure that you do that following the [IP Policy](https://git.ostc-eu.org/oss-compliance/ip-policy/) and that you comply with REUSE standard to include the licensing information where they are required.
# DCO sign-off # DCO sign-off
......
ci/device-testing.rst
View file @ 940f44cb
...@@ -148,8 +148,6 @@ Test devices are connected to their local LAVA worker and manged by LAVA server. ...@@ -148,8 +148,6 @@ Test devices are connected to their local LAVA worker and manged by LAVA server.
* `How to deploy wic image on Raspberry Pi in LAVA <https://forum.ostc-eu.org/t/how-to-deploy-wic-image-on-raspberry-pi-in-lava/228>`_ * `How to deploy wic image on Raspberry Pi in LAVA <https://forum.ostc-eu.org/t/how-to-deploy-wic-image-on-raspberry-pi-in-lava/228>`_
* `Adding Arduino Nano 33 BLE Board to LAVA Lab <https://forum.ostc-eu.org/t/adding-arduino-nano-33-ble-board-to-lava-lab/215>`_ * `Adding Arduino Nano 33 BLE Board to LAVA Lab <https://forum.ostc-eu.org/t/adding-arduino-nano-33-ble-board-to-lava-lab/215>`_
* `Adding Nitrogen Board to LAVA Lab <https://forum.ostc-eu.org/t/adding-nitrogen-board-to-lava-lab/192>`_
* `Adding Avenger96 Board to LAVA Lab <https://forum.ostc-eu.org/t/adding-avenger96-board-to-lava-lab/46>`_
References References
---------- ----------
......
conf.py
View file @ 940f44cb
...@@ -25,7 +25,7 @@ project = 'Oniro Project' ...@@ -25,7 +25,7 @@ project = 'Oniro Project'
copyright = '2022' copyright = '2022'
author = 'Oniro Project' author = 'Oniro Project'
version = '2.0.0-alpha' version = '2.0.0'
release = version release = version
# -- General configuration --------------------------------------------------- # -- General configuration ---------------------------------------------------
......
contributing/CONTRIBUTING.lua
View file @ 940f44cb
...@@ -8,9 +8,8 @@ ...@@ -8,9 +8,8 @@
-- tool. This is needed when converting a set of reST documents to a markdown -- tool. This is needed when converting a set of reST documents to a markdown
-- one where directives like `toctree` and `contents` are not supported and end -- one where directives like `toctree` and `contents` are not supported and end
-- up translated literally. -- up translated literally.
function Div(el) function Div(div)
local class = el["c"][1][2][1] if div.classes:includes('toctree') or div.classes:includes('contents') then
if class == "toctree" or class == "contents" then
return {} return {}
else else
return nil return nil
......
contributing/CONTRIBUTING.sh
View file @ 940f44cb
...@@ -100,6 +100,7 @@ log "Converting to markdown..." ...@@ -100,6 +100,7 @@ log "Converting to markdown..."
pandoc -s --toc --markdown-headings=atx --wrap=none -t gfm \ pandoc -s --toc --markdown-headings=atx --wrap=none -t gfm \
--lua-filter="$SCRIPT_PATH/CONTRIBUTING.lua" \ --lua-filter="$SCRIPT_PATH/CONTRIBUTING.lua" \
"$SCRIPT_PATH/../definitions.rst" \ "$SCRIPT_PATH/../definitions.rst" \
"$SCRIPT_PATH/eca.rst" \
"$SCRIPT_PATH/gitlab.rst" \ "$SCRIPT_PATH/gitlab.rst" \
"$SCRIPT_PATH/reuse.rst" \ "$SCRIPT_PATH/reuse.rst" \
"$SCRIPT_PATH/dco.rst" \ "$SCRIPT_PATH/dco.rst" \
......
contributing/eca.rst 0 → 100644
View file @ 940f44cb
.. SPDX-FileCopyrightText: Huawei Inc.
..
.. SPDX-License-Identifier: CC-BY-4.0
.. include:: ../definitions.rst
Eclipse Contributor Agreement
#############################
Before your contribution can be accepted by the project team, contributors must
electronically sign the
`Eclipse Contributor Agreement (ECA) <http://www.eclipse.org/legal/ECA.php>`_.
Commits must have a Signed-off-by field in the footer indicating that the
author is aware of the terms by which the contribution has been provided to the
project. Also, an associated Eclipse Foundation account needs to be in place
with a signed Eclipse Contributor Agreement on file. These requirements
are enforced by the Eclipse Foundation infrastructure tooling.
For more information, please see the
`Eclipse Committer Handbook <https://www.eclipse.org/projects/handbook/#resources-commit>`_.
contributing/gitlab.rst
View file @ 940f44cb
...@@ -21,6 +21,24 @@ with proposed changes and raise a merge request against the forked repository. ...@@ -21,6 +21,24 @@ with proposed changes and raise a merge request against the forked repository.
More generic information you can find on the Gitlab's documentation as part of More generic information you can find on the Gitlab's documentation as part of
`"Merge requests workflow" <https://docs.gitlab.com/ee/development/contributing/merge_request_workflow.html>`_. `"Merge requests workflow" <https://docs.gitlab.com/ee/development/contributing/merge_request_workflow.html>`_.
Git setup
*********
Clone your fork locally, enter its directory and set:
.. code-block:: bash
$ git config --local user.email <your_eclipse_account_email>
$ git config --local user.name <your_eclipse_full_name>
To push and pull over HTTPS with Git using your account, you must set a password
or `a Personal Access Token <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`_
.
If you want to push or pull repositories using SSH, you have to
`add a SSH key <https://docs.gitlab.com/ee/user/ssh.html>`_ to your profile.
Commit Guidelines Commit Guidelines
***************** *****************
...@@ -145,3 +163,21 @@ is to maintain the RestructuredText file format. Text files that are not meant t ...@@ -145,3 +163,21 @@ is to maintain the RestructuredText file format. Text files that are not meant t
as part of the project's documentation can be written in `Markdown <https://daringfireball.net/projects/markdown/>`_. as part of the project's documentation can be written in `Markdown <https://daringfireball.net/projects/markdown/>`_.
For example, a repository ``README`` file can be written in Markdown as it For example, a repository ``README`` file can be written in Markdown as it
doesn't end up compiled in the project-wide documentation. doesn't end up compiled in the project-wide documentation.
Creating merge requests
-----------------------
Once your changes have been pushed to your fork, you are ready to prepare a merge request.
1. Go to your repository in an internet browser.
#. Create a merge request by clicking ``Merge Requests`` on left toolbar
and press ``New merge request``. Add an explainable description and create a merge request.
Alternatively, you can enter the website of your fork. You should see a message that you
pushed your branch to the repository. In the same section you can press ``Create merge request``.
#. Before merging, it has to be reviewed and approved by |main_project_name| repository
maintainers. Read their review and add any required changes to your merge request.
#. After you polish your merge request, the maintainers will run the pipelines which check
if your changes do not break the project and approve them. If everything is correct, your work
is merged to the main project. Remember that each commit of the merge request should be a minimum,
self-contained building block.
contributing/index.rst
View file @ 940f44cb
...@@ -16,6 +16,8 @@ requirements. ...@@ -16,6 +16,8 @@ requirements.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
quick-start-contribution-onboarding
eca
gitlab gitlab
reuse reuse
dco dco
......
contributing/quick-start-contribution-onboarding.rst 0 → 100644
View file @ 940f44cb
.. SPDX-FileCopyrightText: Huawei Inc.
..
.. SPDX-License-Identifier: CC-BY-4.0
.. include:: ../definitions.rst
Quick start contribution guide for new developers
#################################################
This page describes Quick start contribution guide for new developers who would like to
join the |main_project_name|
.. contents::
:depth: 2
Setting up
**********
Creating an account on Eclipse
------------------------------
Head to the
`Eclipse foundation website <https://accounts.eclipse.org/user/register?destination=user/login>`_
and set up an account by entering your:
- Email
- Username
- Full name
- Organization
- Password
- Country
Then read and check the box to agree to Terms of Use, Privacy Policy and Code of Conduct.
When you complete that, follow the instructions sent to your email to activate the account.
Signing the ECA
---------------
In order to contribute to the |main_project_name| you need to sign the
`Eclipse Contributor Agreement <https://accounts.eclipse.org/user/eca>`_,
which describes the terms under which you can contribute to the project.
If you sign this ECA, you confirm your legal rights to submit the code to the project.
You also provide license to your contributions to Eclipse and specified users, however
you still own your contributions.
EF Gitlab Account Setup
-----------------------
Now you can go to `the Oniro Gitlab <https://gitlab.eclipse.org/eclipse/oniro-core/oniro>`_ .
You should use the account that was created in the previous step to log in.
For further information, go to the :doc:`Gitlab section <gitlab>`.
contributing/reuse.rst
View file @ 940f44cb
...@@ -17,17 +17,26 @@ All projects and files for an hosted project **MUST** be `REUSE <https://reuse.s ...@@ -17,17 +17,26 @@ All projects and files for an hosted project **MUST** be `REUSE <https://reuse.s
compliant. REUSE requires SPDX information for each file, rules for which are compliant. REUSE requires SPDX information for each file, rules for which are
as follows: as follows:
* Any new file must have a SPDX header (copyright and license). * for files copyrighted by projects contributors (**"First Party Files"**):
* For files that don't support headers (for example binaries, patches etc.) an associated ``.license`` file must be included with the relevant SPDX information.
* Do not add Copyright Year as part of the SPDX header information.
* The general rule of thumb for the license of a patch file is to use the license of the component for which the patch applies.
* When modifying a file through this contribution process, you may (but don't have to) claim copyright by adding a copyright line.
* Never alter copyright statements made by others, but only add your own.
Some files will make an exception to the above rules as described below: * any new file MUST have a SPDX header (copyright and license);
* for files that don't support headers (for example binaries, patches etc.) an associated ``.license`` file MUST be included with the relevant SPDX information;
* do not add Copyright Year as part of the SPDX header information;
* the general rule for patch files is to use the MIT license and *not* the license of the component for which the patch applies - the latter solution would be error-prone and hard to manage and maintain in the long run, and there may be difficult-to-handle cases (what if the patches modifies multiple files in the same component - eg. gcc - which are subject to different licenses);
* when modifying a file through this contribution process, you may (but don't have to) claim copyright by adding a copyright line;
* you MUST NOT alter copyright statements made by others, but only add your own;
* for files copyrighted by third parties and just added to the project by contributors, eg. files copied from other projects or back-ported patches (**"Third Party Files"**):
* if upstream files already have SPDX headers, they MUST be left unchanged;
* if upstream files do *not* have SPDX headers:
* the exact upstream provenance (repo, revision, path) MUST be identified;
* you MUST NOT add SPDX headers to Third Party Files;
* copyright and license information, as well as upstream provenance information (in the "Comment" section), MUST be stored in `.reuse/dep5` following `Debian dep5 specification <https://dep-team.pages.debian.net/deps/dep5/>`_ (see examples below);
* you MUST NOT use wildcards (\*) in dep5 "Files" paragraphs even if Debian specs allow it: it may lead to unnoticed errors or inconsistencies in case of future file additions that may be covered by wildcard expressions even if they have a different license;
* in case of doubts or problems in finding the correct license and copyright information for Third Party Files, contributors may ask the project's Legal Team in the project mailing list oniro-dev@eclipse.org;
* Files for which copyright is not claimed and for which this information was not trivial to fetch (for example backporting patches, importing build recipes etc. when upstream doesn't provide the SPDX information in the first place)
* license files (for example ``common-licenses`` in bitbake layers)
SPDX Header Example SPDX Header Example
------------------- -------------------
...@@ -42,7 +51,30 @@ Make sure all of your submitted new files have a licensing statement in the head ...@@ -42,7 +51,30 @@ Make sure all of your submitted new files have a licensing statement in the head
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
*/ */
DEP5 "Files" Paragraph Examples
-------------------------------
.. code-block:: text
Files: meta-oniro-staging/recipes-containers/buildah/buildah_git.bb
Copyright: OpenEmbedded Contributors
License: MIT
Comment: Recipe file for buildah copied from meta-virtualization project at
https://git.yoctoproject.org/meta-virtualization,
recipes-containers/buildah.
README file of meta-virtualization project states:
"All metadata is MIT licensed unless otherwise stated."
Files: meta-oniro-staging/recipes-devtools/ninja/ninja/0001-feat-support-cpu-limit-by-cgroups-on-linux.patch
Copyright: Google Inc.
License: Apache-2.0
Comment: Patch for ninja backported from Ninja project at
https://github.com/ninja-build/ninja, commit 540be33
Copyright text left as found in the header of the patched file.
Substantial Contributions Substantial Contributions
------------------------- -------------------------
Therefore, if your contribution is only a patch directly applied to an existing file, then you are not required to do anything. If your contribution is an entire new project, or a substantial, copyrighted contribution, you **MUST** make sure that you do that following the `IP Policy <https://booting.oniroproject.org/distro/governance/ip-policy>`_ and that you comply with REUSE standard to include the licensing information where they are required. Therefore, if your contribution is only a patch directly applied to an existing file, then you are not required to do anything. If your contribution is an entire new project, or a substantial, copyrighted contribution, you **MUST** make sure that you do that following the `IP Policy <https://git.ostc-eu.org/oss-compliance/ip-policy/>`_ and that you comply with REUSE standard to include the licensing information where they are required.
contributing/upstream_contribution_process.rst
View file @ 940f44cb
...@@ -14,7 +14,7 @@ Contributing to Projects not Maintained by |main_project_name| Team ...@@ -14,7 +14,7 @@ Contributing to Projects not Maintained by |main_project_name| Team
Overview Overview
******** ********
In order to comply with :ref:`Upstream first<sec-upstream>` rule and Open Source licenses requirements, |main_project_name| developers collaborate with several upstream projects to submit fixes, improvements, bug reports, problem investigation results etc. Contribution must be made in accordance with upstream project policy using the tooling upstream project prefers such as mailing list, github/gitlab pull/merge requests, etc. In order to comply with "upstream first" rule and Open Source licenses requirements, |main_project_name| developers collaborate with several upstream projects to submit fixes, improvements, bug reports, problem investigation results etc. Contribution must be made in accordance with upstream project policy using the tooling upstream project prefers such as mailing list, github/gitlab pull/merge requests, etc.
.. _sec_upstream_contrib_signoff: .. _sec_upstream_contrib_signoff:
......
index.rst
View file @ 940f44cb
...@@ -66,17 +66,37 @@ daily life. ...@@ -66,17 +66,37 @@ daily life.
oniro/hardware-support/index oniro/hardware-support/index
building-project-documentation building-project-documentation
.. toctree::
:caption: OS Features
:maxdepth: 2
ota
.. toctree:: .. toctree::
:caption: Supported Technologies :caption: Supported Technologies
:maxdepth: 2 :maxdepth: 2
oniro/supported-technologies/openthread oniro/supported-technologies/openthread
oniro/supported-technologies/matter
oniro/supported-technologies/containers
oniro/supported-technologies/modbus
oniro/supported-technologies/lvgl
oniro/supported-technologies/ledge
.. toctree::
:caption: Supported Toolchains
:maxdepth: 2
oniro/toolchains
.. toctree:: .. toctree::
:caption: Troubleshoot :caption: Troubleshoot
:maxdepth: 2 :maxdepth: 2
oniro/fallback-devices-support oniro/fallback-devices-support
oniro/debug-mode
oniro/update-tool
oniro/default-password
.. toctree:: .. toctree::
:caption: Contribute :caption: Contribute
...@@ -95,8 +115,8 @@ daily life. ...@@ -95,8 +115,8 @@ daily life.
.. toctree:: .. toctree::
:caption: Policies and Compliance :caption: Policies and Compliance
:maxdepth: 2 :maxdepth: 2
ip-policy/index Intellectual Property Policy <https://www.eclipse.org/org/documents/Eclipse_IP_Policy.pdf>
security/index security/index
.. toctree:: .. toctree::
......
ip-policy/index.rst deleted 100644 → 0
View file @ bbcb3db0
.. SPDX-FileCopyrightText: Huawei Inc.
..
.. SPDX-License-Identifier: CC-BY-4.0
Intellectual Property Compliance Policy
#######################################
.. toctree::
:maxdepth: 1
ip-policy_policy/index
ip-policy_implementation-guidelines/index
ip-policy/ip-policy_implementation-guidelines deleted 120000 → 0
View file @ bbcb3db0
../../ip-policy/implementation_guidelines/source/
\ No newline at end of file
ip-policy/ip-policy_policy deleted 120000 → 0
View file @ bbcb3db0
../../ip-policy/policy/source/
\ No newline at end of file
ota.rst 0 → 100644
View file @ 940f44cb
This diff is collapsed.
overview/oniroproject-vision.rst
View file @ 940f44cb
...@@ -44,6 +44,24 @@ able to choose from Java, Extensible Markup Language (XML), C/C++, JavaScript ...@@ -44,6 +44,24 @@ able to choose from Java, Extensible Markup Language (XML), C/C++, JavaScript
(JS), Cascading Style Sheets (CSS), and HarmonyOS Markup Language (HML) to (JS), Cascading Style Sheets (CSS), and HarmonyOS Markup Language (HML) to
develop applications for |main_project_name|. develop applications for |main_project_name|.
OpenHarmony Compatibility
-------------------------
|main_project_name| will be OpenHarmony compatible. It will include the services
and frameworks required by OpenHarmony specification, and provide the APIs
required by OpenHarmony specification, so that you can develop products that can
interoperate with other OpenHarmony products and be certified as OpenHarmony
compatible.
OpenHarmony compatibility will enable required OpenHarmony features in the
kernel layer, system services layer and framework layer, allowing the addition
of OpenHarmony compatible applications.
Due to the inherent modularity of the Oniro build system (OpenEmbedded),
individual projects will be able to pick and choose from the OpenHarmony
compatibility features, allowing to build products with just the parts that are
needed.
Technical Architecture Technical Architecture
---------------------- ----------------------
......
releases/2.0/2.0.0/index.rst 0 → 100644
View file @ 940f44cb
.. SPDX-FileCopyrightText: Huawei Inc.
..
.. SPDX-License-Identifier: CC-BY-4.0
.. include:: ../../../definitions.rst
2.0.0
#####
**Release timeframe**: 2022-03-07 .. 2022-11-30
**Release Artefacts Download Area**: https://download.eclipse.org/oniro-core/releases/2.0.0/
**Release Tags GPG Public Key**: https://download.eclipse.org/oniro-core/releases/2.0.0/oniro-2.0.0_gpg_key.asc [*]_
.. toctree::
:maxdepth: 1
release_notes
requirements
test_report
ip_compliance_note
security_report
.. [*] All repositories released part of 2.0.0 have associated 2.0.0 `git
tags` that have been signed during the Eclipse Foundation release process.
You can use this GPG public key to verify all these signatures.
releases/2.0/2.0.0/ip_compliance_note.rst 0 → 100644
View file @ 940f44cb
.. SPDX-FileCopyrightText: Alberto Pianon <pianon@array.eu> and Carlo Piana <piana@array.eu>
..
.. SPDX-License-Identifier: CC-BY-4.0
.. _2_0_0_IPComplianceNote:
IP Compliance Note
==================
Since the very beginning, a Continuous Compliance `toolchain`_ and `process`_
have been developed and integrated into the Oniro project development so that
source components used to generate Oniro binary images are continuously scanned
by open-source tools like `Fossology`_ and `Scancode`_, and reviewed by
Software Audit Experts and IP Lawyers [*]_.
For detailed information about the why and the how of such a process, please
refer to the Oniro Compliance Toolchain’s `official documentation`_. Sources
and documentation for custom components of the toolchain (`tinfoilhat`_,
`aliens4friends`_, `dashboard`_, `pipelines`_) can be found in their respective
repositories.
*TL;DR*: we put ourselves in your shoes, a device maker willing to use Oniro to
develop its products. We simulated the IP compliance work you would have to do
(on third-party components fetched by Yocto recipes) to build your firmware
image(-s) and spot possible legal risks and issues. In the true open-source
spirit, every time we found an issue with a particular upstream component, we
raised that issue upstream, and most of the time we got it solved for you by
upstream developers.
As of Oniro’s 2.0.0 GA Release, there are just a few issues left that we cannot
address. These relate to proprietary firmware/drivers for hardware support and
some patent-covered technologies. The issues require your attention and
possible action, e.g. getting a patent license. We will briefly explain these
here.
The overall status of audit activities can be monitored through a `dedicated
dashboard`_, which gets updated after every commit to Oniro's main repository.
In the dashboard, also CVE information (collected at the time of the commit) is
shown and can be filtered based on target machines, images, and single
components.
All repositories included in the Oniro 2.0.0 Release are `REUSE compliant
<https://reuse.software/spec/>`_. It means that copyright and license metadata
for every source file are made available within each repository in a standard
machine-readable format, and that at any time one can generate an SPDX SBoM
[*]_ for such repositories with `REUSE tool
<https://github.com/fsfe/reuse-tool>`_ by just running ``reuse spdx`` command.
REUSE-generated SPDX files for all released repositories are available as part
of the `release artefacts download area
<https://download.eclipse.org/oniro-core/releases/oniro-v2.0.0_spdx_sbom.tar.gz>`_.
Last but not least, we provide reference SPDX SBoM of source packages used to
build oniro-image-base and zephyr-philosophers images for a selection of
supported target machines (qemu, raspberrypi4, arduino-nano-33ble), generated
by continuous compliance pipelines. They are provided as a convenience only,
with no express or implied warranty about the accuracy and completeness of the
information contained therein (see the disclaimers below):
============================= ====== ============ =================== ===================
SBoM kernel toolchain(s) machine(s) image
============================= ====== ============ =================== ===================
`linux-qemu`_ linux gcc,clang qemu\* oniro-image-base
`linux-raspberrypi4`_ linux gcc,clang raspberrypi4-64 oniro-image-base
`zephyr-qemu`_ zephyr gcc qemu\* zephyr-philosophers
`zephyr-arduino-nano-33-ble`_ zephyr gcc arduino-nano-33-ble zephyr-philosophers
============================= ====== ============ =================== ===================
.. _linux-qemu: https://download.eclipse.org/oniro-core/releases/2.0.0/oniro-v2.0.0_linux-qemu_images_spdx_sbom.zip
.. _linux-raspberrypi4: https://download.eclipse.org/oniro-core/releases/2.0.0/oniro-v2.0.0_linux-raspberrypi4_images_spdx_sbom.zip
.. _zephyr-qemu: https://download.eclipse.org/oniro-core/releases/2.0.0/oniro-v2.0.0_zephyr-qemu_images_spdx_sbom.zip
.. _zephyr-arduino-nano-33-ble: https://download.eclipse.org/oniro-core/releases/2.0.0/oniro-v2.0.0_zephyr-arduino-nano-33-ble_images_spdx_sbom.zip
*Disclaimer#1*: This is not legal advice. This note is provided just as a
convenience for you, to suggest some critical areas in which you should seek
legal advice if you want to develop real-world products based on Oniro. It is
not meant to be complete nor to substitute internal due-diligence activities
you need to perform before marketing your products.
*Disclaimer#2*: This note covers only source components used to generate
supported Oniro images (oniro-image-base and zephyr-philosophers) for supported
target machines (qemux86-64, qemux86, qemuarm-efi, qemuarm64-efi,
raspberrypi4-64, seco-intel-b68, seco-px30-d23, seco-imx8mm-c61-2gb,
seco-imx8mm-c61-4gb, qemu-cortex-m3, nrf52840dk-nrf52840, arduino-nano-33-ble).
*Disclaimer#3*: “supported” *referred to a board* means that a board is
officially targeted as a potential platform where an Oniro image can be
installed for any purposes; when *referred to an image*, means that the image
targeting a supported board receives thorough testing and specific attention
during the development. It does NOT mean that both will receive support
services nor that any member of the Oniro Working Group or of the Eclipse
Foundation will provide any warranty whatsoever.
Solved Issues
-------------
- There was a proprietary software font accidentally included in
zephyr-philosophers; we opened the issue upstream
(https://github.com/zephyrproject-rtos/zephyr/issues/48111), which was
solved (https://github.com/zephyrproject-rtos/zephyr/pull/49103), and the
fix was backported to Oniro.
(https://gitlab.eclipse.org/eclipse/oniro-core/meta-zephyr/-/commit/0f36ae849d59da08e445af83f711a1c0108dd3bf);
- A similar issue was found also in Harfbuzz component, raised upstream
(https://github.com/harfbuzz/harfbuzz/issues/3845), fixed
(https://github.com/harfbuzz/harfbuzz/pull/3846), and the fix was backported
to Oniro
(https://gitlab.eclipse.org/eclipse/oniro-core/oniro/-/commit/fbb4bc229b287fa293439ee0adbb0d830764b2d8).
- There were a lot of binary files found in zephyr-philosophers, without
corresponding sources and no clear license information; we opened the issue
upstream
(https://gitlab.eclipse.org/eclipse/oniro-core/meta-zephyr/-/commit/0f36ae849d59da08e445af83f711a1c0108dd3bf),
which was then fixed
(https://github.com/zephyrproject-rtos/zephyr/pull/47181), and the fix was
backported to Oniro.
(https://gitlab.eclipse.org/eclipse/oniro-core/meta-zephyr/-/commit/a00d1c4f1aad8b0ea5b9f904966c0bd8a48d8d80)
- Some proprietary license headers, not granting redistribution nor any other
rights without written permission by Intel, were found in some source files
in the Intel-Media-SDK component; we opened the issue upstream
(https://github.com/Intel-Media-SDK/MediaSDK/issues/2937) and it turned out
it was an oversight occurred when open sourcing the component; it was then
fixed (https://github.com/Intel-Media-SDK/MediaSDK/pull/2939) and the fix was
backported to Oniro.
(https://gitlab.eclipse.org/eclipse/oniro-core/oniro/-/commit/d5ee837d90903d91a1ff358ebfe985d28925484e);
- A similar issue was found also in the Intel-Media-Driver component, it was
raised upstream (https://github.com/intel/media-driver/issues/1460), fixed
(https://github.com/intel/media-driver/pull/1465), and the fix was backported
to Oniro
(https://gitlab.eclipse.org/eclipse/oniro-core/oniro/-/commit/b56de944568c8e348cb8265c59d7cfd52a0831b9)
Warnings for Downstream Users: Hardware Support
-----------------------------------------------
Linux
~~~~~
IMX Firmware
^^^^^^^^^^^^
A couple of supported target boards (seco-imx8mm-c61-2gb and
seco-imx8mm-c61-4gb) require Freescale i.MX firmware for VPU and SDMA as well
as firmware for 8M Mini family to train memory interface on SoC and DRAM during
initialization. These firmware require acceptance of a `EULA`_ by the user
(you). Such acceptance may be provided by flagging a specific environment
variable (``ACCEPT_FSL_EULA = "1"``) in your configuration file (please refer
to Oniro’s technical documentation). You should carefully read that `EULA`_ to
check whether you are actually in a position to accept it and whether you can
fulfill all of its conditions. If needed, seek legal advice for that.
Linux-firmware
^^^^^^^^^^^^^^
The third-party components ``linux-firmware`` and ``linux-firmware-rpidistro``
contain many sub-components (mainly firmware BLOBs) for specific hardware
support, coming from different hardware vendors.
Almost all firmware vendor licenses restrict firmware usage to the specific
device(s) of their own.
Some of them (apparently) contain further restrictions, stating that the binary
file is licensed *“for use with [vendor] devices, but not as a part of the
Linux kernel or in any other form which would require these files themselves to
be covered by the terms of the GNU General Public License”*. Our understanding
is that such restriction is either redundant or useless. Apart from some
debatable and contested corner cases, there is no way in which a firmware blob
may become part of the Linux kernel and therefore be covered by the GNU General
Public License - so the above provision seems redundant. But even if someone
claimed that a proprietary firmware requires such a low-level interaction with
the kernel that such firmware must be deemed as a derivative work of the kernel
itself, such (alleged) non-compliance with GPL could not be avoided or excluded
by a vendor license clause - so the above provision would be useless. You
should seek legal advice to use the affected firmware files in either case.
================================= ================================================== ======================== ============================
Source Device/driver File(s) License found in
================================= ================================================== ======================== ============================
`linux-firmware-20220913.tar.xz`_ Conexant Cx23100/101/102 USB broadcast A/V decoder v4l-cx231xx-avcore-01.fw WHENCE
`linux-firmware-20220913.tar.xz`_ meson-vdec - Amlogic video decoder meson/vdec/\* LICENSE.amlogic_vdec, WHENCE
`linux-firmware-20220913.tar.xz`_ lt9611uxc - Lontium DSI to HDMI bridge lt9611uxc_fw.bin LICENSE.Lontium, WHENCE
================================= ================================================== ======================== ============================
Some other firmware files are covered by proprietary licenses that contain
termination clauses providing that either party may terminate the license at
any time without cause, which may work as killswitches (i.e. vendor may
terminate your license at any time without any reason, so your devices -
including already distributed ones - may lose, say, Bluetooth or Wifi support).
You should seek legal advice (and possibly negotiate a different license with
the vendor) if you need to use the affected firmware files:
========================================================== ====================== ======== ================
Source Device/driver File(s) License found in
========================================================== ====================== ======== ================
[git://github.com/murata-wireless/cyw-fmac-fw@ba140e42] Murata Wi-Fi/Bluetooth cyfmac\* LICENCE, README
[git://github.com/murata-wireless/cyw-fmac-nvram@8710e74e] Murata Wi-Fi/Bluetooth cyfmac\* LICENCE.cypress
[git://github.com/murata-wireless/cyw-bt-patch@9d040c25] Broadcom BCM43455 Wifi \*.hcd LICENCE.cypress
========================================================== ====================== ======== ================
Some other firmware files (for NVIDIA hardware, that is not included in any of
Oniro’s supported boards) have been expressly excluded from installation
because they come with a proprietary license with an unclear “open source
exception”. See `issue #834`_ in Oniro main repo for further details.
Some other firmware files are covered by a limited patent license. If you need
to use them, you should check whether you fulfill the conditions of such a
license.
================================= ========================= ============================= ======================
Source Device/driver File(s) License found in
================================= ========================= ============================= ======================
`linux-firmware-20220913.tar.xz`_ WiLink4 chips WLAN driver ti-connectivity/wl1251-fw.bin LICENCE.wl1251, WHENCE
================================= ========================= ============================= ======================
Finally, some licenses have unclear license wording about use and
redistribution. If you need to use firmware covered by such files, you should
check and possibly seek legal advice.
================================= ===================================================== ================================== =======================
Source Device/driver File(s) License found in
================================= ===================================================== ================================== =======================
`linux-firmware-20220913.tar.xz`_ WiLink4 chips WLAN driver ti-connectivity/wl1251-fw.bin LICENCE.wl1251, WHENCE
`linux-firmware-20220913.tar.xz`_ Marvell Libertas 802.11b/g cards libertas/\*.bin, mrvk/\*.bin LICENCE.Marvell, WHENCE
`linux-firmware-20220913.tar.xz`_ Marvell mac80211 driver for 80211ac cards mwlwifi/\*.bin LICENCE.Marvell, WHENCE
`linux-firmware-20220913.tar.xz`_ Marvell CPT driver mrvl/cpt01/\* LICENCE.Marvell, WHENCE
`linux-firmware-20220913.tar.xz`_ Marvell driver for Prestera family ASIC devices mrvl/prestera/\*.img LICENCE.Marvell, WHENCE
`linux-firmware-20220913.tar.xz`_ wave5 - Chips&Media, Inc. video codec driver cnm/wave521c_j721s2_codec_fw.bin LICENCE.cnm, WHENCE
`linux-firmware-20220913.tar.xz`_ Broadcom 802.11n fullmac wireless LAN driver brcm/brcmfmac/\*, cypress/cyfmac\* LICENCE.cypress, WHENCE
`linux-firmware-20220913.tar.xz`_ BCM-0bb4-0306 Cypress Bluetooth firmware for HTC Vive brcm/BCM-0bb4-0306.hcd LICENCE.cypress, WHENCE
================================= ===================================================== ================================== =======================
Zephyr
~~~~~~
The third-party repository ‘`zephyr-philosophers`_’ fetched by
zephyr-philosophers recipe contains many sub-components for specific hardware
support, coming from different hardware vendors. Some of them have specific
proprietary license conditions (eg. software components to support Atmel SAM
L21, Altera Nios II, Cypress/Infineon PSoC6) but are not used to generate Oniro
images, so they are not covered here. Should you need to add support for such
hardware boards, not officially supported by Oniro, you should carefully check
hardware vendor's license conditions.
Warnings for Downstream Users: Patents
--------------------------------------
“Dropbear” component documentation contains a patent and trademark notice:
The author (Tom St Denis) is not a patent lawyer so this section is not to
be treated as legal advice. To the best of the author’s knowledge, the only
patent-related issues within the library are the RC5 and RC6 symmetric block
cyphers. They can be removed from a build by simply commenting out the two
appropriate lines in `\textit{tomcrypt\_custom.h}`. The rest of the cyphers
and hashes are patent-free or under patents that have since expired.
The RC2 and RC4 symmetric cyphers are not under patents but are under
trademark regulations. This means you can use the cyphers you just can’t
advertise that you are doing so.
To our best knowledge, also patents on RC5 and RC6 symmetric block cyphers have
expired, but you should seek legal advice to check whether there still are
active patents covering such technologies.
.. [*]
Carlo Piana and Alberto Pianon from Array (Legal); Rahul Mohan G. and
Vaishali Avhad from NOI Techpark (Audit)
.. [*] SBOM is short for Software Bill Of Material, the full and detailed list
of upstream components. SPDX is short for Software Package Data Exchange, an
`ISO standard <https://spdx.github.io/spdx-spec>`_ to communicate
information about software in a machine-readable form.
.. _toolchain: https://projects.eclipse.org/projects/oniro.oniro-compliancetoolchain
.. _process: https://gitlab.eclipse.org/eclipse/oniro-compliancetoolchain/toolchain/docs/-/tree/main/audit_workflow
.. _Fossology: https://www.fossology.org
.. _Scancode: https://nexb.com/scancode
.. _official documentation: https://gitlab.eclipse.org/eclipse/oniro-compliancetoolchain/toolchain/docs
.. _tinfoilhat: https://gitlab.eclipse.org/eclipse/oniro-compliancetoolchain/toolchain/tinfoilhat
.. _aliens4friends: https://gitlab.eclipse.org/eclipse/oniro-compliancetoolchain/toolchain/aliens4friends
.. _dashboard: https://gitlab.eclipse.org/eclipse/oniro-compliancetoolchain/toolchain/dashboard
.. _pipelines: https://gitlab.eclipse.org/eclipse/oniro-compliancetoolchain/toolchain/pipelines
.. _EULA: https://git.yoctoproject.org/meta-freescale/tree/EULA
.. _linux-firmware-20220913.tar.xz: https://cdn.kernel.org/pub/linux/kernel/firmware/linux-firmware-20220913.tar.xz
.. _issue #834: https://gitlab.eclipse.org/eclipse/oniro-core/oniro/-/issues/834
.. _zephyr-philosophers: https://github.com/zephyrproject-rtos/zephyr
.. _dedicated dashboard: https://sca.software.bz.it/?json=https://gitlab.eclipse.org/eclipse/oniro-compliancetoolchain/mirrors/oniro-goofy/-/jobs/artifacts/kirkstone/raw/report.harvest.json?job=harvest

Copyright © Eclipse Foundation, Inc. All Rights Reserved.     Privacy Policy | Terms of Use | Copyright Agent