OS tier levels + AutoSD as a community OS

[odra]

fixes #2264

Changes

• adds a new Software Platform section to the OS Module
• Includes AutoSD as a community platform to onboard the OS into S-CORE
• Adds OS onboarding documents, including a template to be used as a starting point
• Adds three folders regarding OS tier/levels: community, functional and certifiable

[github-actions]

⚠️ Docs-as-Code version mismatch detected
Please check the CI build logs for details and align the documentation version with the Bazel dependency.

[github-actions]

The created documentation from the pull request is available at: docu-html

[opajonk]

I checked the non-AutoSD-specific parts and I think this is a good starting point for adding OSs.

[FScholPer]

@odra whats the state with that pr?

[odra]

It's waiting for a review from the Arch. WG.

[qor-lb]

The PR is a good step towards making “supported OSs / software platforms” discoverable and positioning Red Hat AutoSD as the first documented target platform. The new entry point under the OS module is useful and the AutoSD page already contains actionable technical information (build/run/tooling pointers), which aligns well with the intention that users find practical integration guidance in one place.

That said, to fully achieve the goal that users can quickly answer:

1. What platforms are supported and at which level?
2. How are the levels defined?
3. How do I onboard / promote a new platform?

some restructuring and additional content would make the result significantly clearer and easier to maintain long-term imho.

[qor-lb]

We should describes the onboarding, maybe something like this (in separate file):

.. _platform-onboarding:

Onboarding and Promotion of Platforms
=====================================

This page describes how platforms are added and promoted.

The process requirements are defined in :ref:`platform_assumptions`.

Principle
---------

Promotion has two phases:

1. **Eligibility (Platform Maintainer)**:
   The platform maintainer resolves the **supplier** requirements of the target level.
   Only if these requirements are fulfilled, the OS can be considered for promotion.

2. **Acceptance + Lifecycle Guarantees (S-CORE)**:
   S-CORE reviews the promotion request.
   If accepted at **Functional** or **Certifiable**, S-CORE commits to maintain the
   guarantees of the accepted level across all increments.

Community level onboarding
--------------------------

**What it means**
  In-tree best-effort integration.
  S-CORE provides no guarantees.

**Eligibility requirements (Platform Maintainer / supplier requirements)**
  The OS maintainer must fulfil the Community level supplier requirements as defined in:
  :ref:`platform_assumptions`.

**Review and acceptance (S-CORE)**
  S-CORE reviews the documentation entry for completeness and consistency.
  Acceptance only means the platform is listed in-tree.
  No infrastructure or lifecycle support is implied.

Promotion to Functional
-----------------------

**What it means**
  S-CORE provides functional guarantees for the accepted reference integration and
  maintains them across all increments.

**Eligibility requirements (Platform Maintainer / supplier requirements)**
  The platform maintainer must fulfil the Functional level supplier requirements as defined in:
  :ref:`platform_assumptions`.

**Additional acceptance requirements (S-CORE / system integrator requirements)**
  From Functional level onwards, S-CORE must be able to continuously validate the platform.
  This requires infrastructure and test integration.

**Required approvals**
  Promotion to Functional requires explicit approval by:

  * Platform maintainers
  * Architecture WG
  * Infrastructure WG (CI / build & test environment support)
  * Testing WG
  * Quality Management

Promotion to Certifiable
------------------------

**What it means**
  S-CORE provides certifiability-oriented guarantees for the accepted reference integration
  and maintains them across all increments.

**Eligibility requirements (Platform Maintainer / supplier requirements)**
  The platform maintainer must fulfil the Certifiable level supplier requirements as defined in:
  :ref:`platform_assumptions`.

**Additional acceptance requirements (S-CORE / system integrator requirements)**
  Certifiable level implies additional safety/security expectations and evidence handling.

**Required approvals**
  Promotion to Certifiable requires explicit approval by:

  * OS module maintainers
  * Architecture WG
  * Infrastructure WG
  * Testing WG
  * Quality Management
  * Safety Manager
  * Security Manager

Demotion
--------

If the eligibility requirements or the S-CORE lifecycle guarantees of an accepted platform
can no longer be maintained, the platform must be demoted to the highest level that can be
sustained.

[qor-lb]

@odra this is still open

[odra]

added as onboarding.rst

[qor-lb]

We should add a template that standardizes the information presented. I would also like the ability to filter for specific platform so making them as needs would be nice. Please include and link that in the onboarding page and apply it for autosd:

Platform Name
=============

.. platform:: <platform name>
   :id: platform__<platform name snake case>
   :level: <community/functinal/certifiable>
   :maintainer: <GitHub Handles>

Short overview of the platform and why it is relevant for S-CORE.
Keep this to 3-6 lines. Mention what the OS is and the intended usage context.

Target maintainers/integration assistance
-----------------------------------------

GitHub Handles of the target maintainers.


Integration assistance
----------------------

- Provide the names or mailing lists that users can contact for help with S‑CORE integration.
- Use bullet points for multiple contacts.


Integration manual
------------------

- Summarise how to obtain and use the integration manual for this platform.
- Link to external documentation if it exists.


Build instructions
------------------

Explain how to build an image of this platform and how to build S-CORE for it.

.. code-block:: console

  # example commands to build an image
  curl -o /tmp/image-builder.sh https://example.com/image-builder.sh
  chmod +x /tmp/image-builder.sh
  sudo bash /tmp/image-builder.sh --distro <distro> --target <target>

Provide any additional context, such as how to boot or run the image (e.g. with QEMU).

Toolchain
---------

- Explain how to set up Bazel toolchains for this platform.
- Include a short example ``MODULE.bazel`` snippet.


Bug interface
-------------

- Explain how users can report bugs (mailing lists, issue trackers, Matrix/Slack channels etc.).

[qor-lb]

@odra this is still open. I would also link the template in the onboarding section above.

[odra]

Added as "os_onboarding_template.rst"

[qor-lb]

we should also update the codeowner file to reflect the necessary approvals for the different levels

[qor-lb]

resolves #1691 and #1740

[aschemmel-tech]

see inline comments

[aschemmel-tech]

Please rename this and the other occurrences to something different from "SW platform" because this is the name we use for the S-CORE SW platform - see discussion in #1740. I would rather call it plainly OS or Operating System. If you want to differentiate between different implementations maybe call it variant?

[odra]

I just kept it as "os", so the name structure is "comp_doc_os_$level_$osname" (_comp_doc_os__community__autosd)

[aschemmel-tech]

Better: "These are the Operating Systems supported on a "community" level for Eclipse S-CORE."

[aschemmel-tech]

Better: "for the exact requirements for each level (Tier)" as we do not use the term Tier in the assumptions.

[aschemmel-tech]

Also here please "Operating System" as a Component name. Or maybe "Operating System Platform" or "Operating System Environment" as proposed below in the text anyway.

[odra]

I replace the term by "Operating System"

[aschemmel-tech]

Please call this "Community Level"

[aschemmel-tech]

Please do not duplicate the AoU documented in the "SW-platform Assumptions" section of S-CORE. What you want is to document the "fulfillment" of these "Non-Functional" AoU with a instruction/guideline how to use "Red Hat AutoSD". So please refer here to the AoU by stating for example "The following fulfills :need:aou_req__platform__integration_assistance ". Better would be to describe the instruction/guideline as a sphinx needs element like @qor-lb proposed (but not with the id "platform__...") with an attribute that links to the AoU. But this is maybe a seperate PR because it would need considering the best way to change the metamodel and modelling by docs-as-code team.

[aschemmel-tech]

see above

[aschemmel-tech]

see above

[odra]

@qor-lb @aschemmel-tech I've updated my PR with the requested changes, could you please review it again?

[opajonk]

Details only

[masc2023]

Our metamodel does not define that need, you should follow that, and OS is more or less a component, so use please .. comp: as defined here https://github.com/eclipse-score/docs-as-code/blob/main/src/extensions/score_metamodel/metamodel.yaml (row 553), example https://eclipse-score.github.io/score/main/modules/communication/ipc_binding/docs/architecture/index.html#comp__com_ipc_binding

if the intention here is only to have an description, then please use document (raw 202)

[odra]

this as the original proposed by @qor-lb:

.. platform:: <platform name>
   :id: platform__<platform name snake case>
   :level: <community/functinal/certifiable>
   :maintainer: <GitHub Handles>

I assumed it was comment metadata (at least for now) since there's no "platform::" directive (I got a compilation error when using it)

[masc2023]

Also not part of metadata, as proposed, your content is mainly a document, so use ..document, the need ..platform is not intended to be implemented, as also discussed with @aschemmel-tech, S-CORE itself is defined as SW-Platform

[odra]

I've changed it to use "comp_arc_sta" instead.

[FScholPer]

Looks good to me

[masc2023]

Your PR has an very old version of doc-as-code, that's why you may not able to use comp, because does not exists yet, please update at least do bazel_dep(name = "score_docs_as_code", version = "2.3.3") or higerh and try again with comp

[odra]

rebased and updated.

I've set the comp id as "comp__os_$osname".

[RolandJentschETAS]

Please add the comp to the os module ... (see modules/os/docs/index)

[RolandJentschETAS]

See above. Please add to the os module.

[odra]

This is one is just a template for onboarding a new OS, does it need to be added to the module list?

[RolandJentschETAS]

No its fine then. I hope there is no issue with it. At least a free running component. Not sure if this make some trouble in the sphinx needs linking. If this is only an template (placeholder) and not a real component, then maybe it is better to not define an sphinx needs element.

[masc2023]

Again, if it is a template, use the document need and add the comp need as note, as we do it also here https://eclipse-score.github.io/process_description//main/folder_templates/features/feature_name/architecture/index.html for example

[odra]

It looks like I cannot use :implements: in with comps anymore, and using logic_arc_int does not work as well since it requires a feat_req.

Should the meta model file be updated with a proper platform/os type?

[RolandJentschETAS]

Please use rst links

[masc2023]

Please check documentation for final review

[masc2023]

@odra there seems some documentation issue in this file, otherwise for me it looks now fine

[odra]

it's showing a warning (future error) for :implements: aou_req__platform__integration_assistance, aou_req__platform__os_integration_manual, aou_req__platform__bug_interface - it seems it's not allowed anymore as I said in this previous comment: #2266 (comment)

[masc2023]

Not sure the error is "/home/runner/work/score/score/docs/modules/os/operating_systems/docs/community/autosd.rst:23: WARNING: Duplicate explicit target name: "upstream documentation". [docutils]"
@RolandJentschETAS , any idea on that?

[odra]

@masc2023 ok, I fixed it

[masc2023]

Fine for now.

[opajonk]

Read it once more completely. Nice job! Understandable, and clear what needs to be done for an OS.

I found only one actual typo and a few details.

[opajonk]

[odra]

@masc2023 it needs a new approval due to some spelling errors

[RolandJentschETAS]

Looks from module cope now strange. QM inside ASIL module.

[masc2023]

But it is correct and as intended, as AutoSD applies not for Certifiable level

[opajonk]

My understanding of this would be: "If you integrate S-CORE on AutoSD, at the moment all you can expect is a QM system".

Disclaimer: same would be true for EB corbos Linux for Safety Application right now, until we successfully qualify for the highest integration level, as described in the PR. This is a step-by-step process, which is totally reasonable, and not how we start off.

[RolandJentschETAS]

This is understandable. Maybe we need an tag or something for this, within the the generated picture.

[RolandJentschETAS]

Or it is another module and dont fit into the OS.

[masc2023]

As comment above, not a problem, it shows exactly the status and any safety engineer will easily see, that AutoSD can not used currently in safety-critical context

[RolandJentschETAS]

But it is against our process requirements, so maybe we have an process issue. See gd_req__arch_linkage_safety_trace. The module OS is defined as ASIL_B and is an architectural element (see gd_req__arch_build_blocks). Therefore linking an QM element will be against this requirement.

[masc2023]

Your rules does not consider yet https://eclipse-score.github.io/score/pr-2266/requirements/platform_assumptions/index.html#aou_req__platform__integration_assistance, where it is allowed to deviate, if you want only to deliver on Community Level, so that is SCORE specific tailoring of the general process

[RolandJentschETAS]

Not sure, what "The supplier shall provide a contact point for integration assistance." have to do with this. But it might be another AOU. But nevertheless it would mean, that our docs as code which will implement the enforcement of this rule by sphinx-needs tests have to be modified or deactivated within S-CORE project scope. Right ?

[RolandJentschETAS]

I talked with the docs_as_code colleagues. They will implement the checks (leads to built errors) and there is currently no possibility implemented and anyhow foreseen to overrule that from the project. They follow currently only the process requirements.