diff --git a/docs/users_guide/_assets/initial_module_rst_content.png b/docs/contribute/_assets/initial_module_rst_content.png similarity index 100% rename from docs/users_guide/_assets/initial_module_rst_content.png rename to docs/contribute/_assets/initial_module_rst_content.png diff --git a/docs/users_guide/_assets/repository_layout.png b/docs/contribute/_assets/repository_layout.png similarity index 100% rename from docs/users_guide/_assets/repository_layout.png rename to docs/contribute/_assets/repository_layout.png diff --git a/docs/users_guide/_assets/score_image.png b/docs/contribute/_assets/score_image.png similarity index 100% rename from docs/users_guide/_assets/score_image.png rename to docs/contribute/_assets/score_image.png diff --git a/docs/contribute/ci/index.rst b/docs/contribute/ci/index.rst deleted file mode 100644 index bd854b1789c..00000000000 --- a/docs/contribute/ci/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2024 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -CI -## - -.. toctree:: - :maxdepth: 1 - - publishing-gh-pages diff --git a/docs/users_guide/building_simple_application/reference_integration.rst b/docs/contribute/contribute_new_module/add_to_ref_integration.rst similarity index 97% rename from docs/users_guide/building_simple_application/reference_integration.rst rename to docs/contribute/contribute_new_module/add_to_ref_integration.rst index 051447ba6c3..8ec8096ba2f 100644 --- a/docs/users_guide/building_simple_application/reference_integration.rst +++ b/docs/contribute/contribute_new_module/add_to_ref_integration.rst @@ -12,8 +12,19 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -How to Integrate a New Module into the Reference Integration -============================================================= +.. _add_to_ref_integration: + +Adding a Module to Reference Integration +======================================== + +.. document:: Add Module to Reference Integration Guide + :id: doc__add_module_to_ref_integration_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + This guide explains how to add a new S-CORE module to the `reference_integration `_ repository, diff --git a/docs/users_guide/building_simple_application/building_source_code.rst b/docs/contribute/contribute_new_module/build_module.rst similarity index 97% rename from docs/users_guide/building_simple_application/building_source_code.rst rename to docs/contribute/contribute_new_module/build_module.rst index c09ac5c8bff..8dffe5f276b 100644 --- a/docs/users_guide/building_simple_application/building_source_code.rst +++ b/docs/contribute/contribute_new_module/build_module.rst @@ -12,10 +12,19 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. _building_source_code: +.. _build_module: + +Build Module +============ + +.. document:: Build Module Guide + :id: doc__build_module_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] -Building source code -===================== SCRAMPLE provides two minimal “Hello World” applications — one in C++ and one in Rust — that both use the S-CORE ``mw::log`` logging library. diff --git a/docs/users_guide/building_simple_application/cicd_workflows.rst b/docs/contribute/contribute_new_module/cicd_workflows.rst similarity index 93% rename from docs/users_guide/building_simple_application/cicd_workflows.rst rename to docs/contribute/contribute_new_module/cicd_workflows.rst index 1bcf7ab930a..dc4a546d23f 100644 --- a/docs/users_guide/building_simple_application/cicd_workflows.rst +++ b/docs/contribute/contribute_new_module/cicd_workflows.rst @@ -12,8 +12,19 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _cicd_workflows: + CI/CD Workflows -================ +=============== + +.. document:: CI/CD Workflow Guide + :id: doc__ci_cd_workflow_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + After successfully building the scrample binary, we need to ensure that future changes do not break the build. diff --git a/docs/users_guide/building_simple_application/first_score_module.rst b/docs/contribute/contribute_new_module/create_new_score_module.rst similarity index 96% rename from docs/users_guide/building_simple_application/first_score_module.rst rename to docs/contribute/contribute_new_module/create_new_score_module.rst index 3f01678d2d0..e4bdd40c180 100644 --- a/docs/users_guide/building_simple_application/first_score_module.rst +++ b/docs/contribute/contribute_new_module/create_new_score_module.rst @@ -12,8 +12,19 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -First Eclipse S-CORE Module -================================= +.. _create_new_score_module: + +Create New Eclipse S-CORE Module +================================ + +.. document:: Create New Module Guide + :id: doc__create_new_module_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + Before starting, ensure you are an official contributor to the Eclipse S-CORE project. Otherwise, you will not have required permissions. Instructions can be found in @@ -90,7 +101,7 @@ Below is an overview of the most relevant files and folders. .github/workflows/ ------------------ Contains CI/CD workflows (build, unit-tests, -:ref:`integration gate ` checks). +:ref:`integration gate ` checks). .vscode @@ -124,7 +135,7 @@ Follows the naming convention ``score//``. tests/ ------- Component Integration Tests (CIT) and Feature Integration Tests (FIT). -See the :ref:`Technology Overview ` for details on test levels. +See the :ref:`Technology Overview ` for details on test levels. .bazelrc diff --git a/docs/users_guide/building_simple_application/doc_generation.rst b/docs/contribute/contribute_new_module/generate_documentation.rst similarity index 95% rename from docs/users_guide/building_simple_application/doc_generation.rst rename to docs/contribute/contribute_new_module/generate_documentation.rst index fbb44f19f9b..32bf56a83a1 100644 --- a/docs/users_guide/building_simple_application/doc_generation.rst +++ b/docs/contribute/contribute_new_module/generate_documentation.rst @@ -12,12 +12,24 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Documentation generation -========================== + +.. _generate_documentation: + +Generate Documentation +====================== + +.. document:: Generate Documentation Guide + :id: doc__generate_documentation_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + Introduction --------------- -As described in the :ref:`Overview of technologies ` chapter, +As described in the :ref:`Technology Introduction ` chapter, Eclipse S-CORE uses the sphinx and sphinx-needs toolchain to generate documentation from rst files. Elements of Eclipse S-CORE metamodel are represented as sphinx-needs objects. diff --git a/docs/contribute/contribute_new_module/index.rst b/docs/contribute/contribute_new_module/index.rst new file mode 100644 index 00000000000..aafbd589996 --- /dev/null +++ b/docs/contribute/contribute_new_module/index.rst @@ -0,0 +1,49 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. _contribution_workflow_guide: + +Contribution Work Flow Guide +============================ + +.. document:: Contribution Work Flow Guide + :id: doc__contribution_work_flow_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + +This guide walks you through contributing a new platform module to Eclipse S-CORE end-to-end. +As a running example you will build a small demo application called +`scrample `_, which shows how +to compose existing S-CORE platform modules into new functionality. + +By the end of this section you will have: + +- :ref:`Created a properly structured S-CORE module from scratch `. +- :ref:`Generated documentation from source and integrated it into the platform docs `. +- :ref:`Build the module with Bazel and verified it compiles cleanly `. +- :ref:`Wired up CI/CD workflows so every change is automatically validated `. +- :ref:`Add the module into the reference integration to make it part of the platform `. + +.. toctree:: + :maxdepth: 1 + :hidden: + + create_new_score_module.rst + generate_documentation.rst + build_module.rst + cicd_workflows.rst + add_to_ref_integration.rst diff --git a/docs/contribute/contribution_request/index.rst b/docs/contribute/contribution_request/index.rst deleted file mode 100644 index bb868771c5c..00000000000 --- a/docs/contribute/contribution_request/index.rst +++ /dev/null @@ -1,195 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2024 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -.. _contribute_contribution_guideline: - -How to Contribute? -################## - -.. document:: Contribution Guideline - :id: doc__contr_guideline - :status: valid - :version: 1 - :safety: QM - :security: NO - :realizes: wp__training_path[version==1] - -How we Work -=========== - -At S-CORE, we believe that every contribution makes our platform stronger. Whether you're a seasoned developer or just starting out in open source, your ideas and work are warmly welcomed. We follow a structured yet flexible process rooted in our change management principles and overall lifecycle concept. For more details on our processes, feel free to explore our `Life Cycle Concept `_ and the :need:`doc__platform_change_management_plan`. And if you want to dive right into contributing, check out :ref:`what_is_a_pr` and :ref:`what_is_a_github_issue`. - -Feature Requests: Our Shared Roadmap ------------------------------------- - -Feature requests are at the heart of our evolution. They describe the intended functionality of the S-CORE platform and serve as a collaborative starting point where maintainers and contributors align on new ideas. These requests not only define the motivation and requirements but also shape the technical roadmap for future developments. We invite you to check out all current feature requests on our -`Feature Request Board `_. - -New Feature and major Feature Modification requests go through a :need:`Feature Enhancement Proposal (FEP) `, where an Architecture Community Shepherd guides the proposal to a Final Comment Period before it's decided. Component-level and single-Feature-Team changes are handled directly by the responsible team, as described in the :need:`doc__platform_change_management_plan`. - -From Vision to Reality: Calling for Contributions -------------------------------------------------- - -Once a feature request is embraced by the community, it becomes a targeted opportunity for innovation. At this stage, we issue a call for contributions, inviting anyone with a solution - whether in-house or open source - to submit a contribution pitch. We ask that your pitch focuses on the technical aspects and clearly outlines how you plan to meet the feature goals (and not a sales pitch 😉). Don't worry if you're still polishing your idea; as long as the source code is already available (or will be within about three weeks with a publicly committed roadmap), you're ready to join in the conversation. - -How We Evaluate Contributions ------------------------------ - -We work together with contributors to review each pitch based on several criteria: - -- **Alignment with the Feature Request:** - Your solution should fully or partially meet the specified functionality, with room for further enhancements as needed. - -- **Availability of the Source Code:** - We value open source solutions under an OSI-compliant license. If your code isn't public yet, a clear plan to open source it is just as welcome. - -- **Technical Maturity:** - We look at whether your implementation is built in a safety-certifiable subset of C++ or Rust, or if it might need some refinements. - -- **Initial Impact Assessment:** - Please state the assumed impact on other systems. It makes a significant difference if your solution requires other components to refactor versus extending functionality through existing APIs. - -- **Supporting Artifacts:** - To ensure everything is in order for certification and further development, we check that all necessary artifacts are available or that there's a plan to make them available. - -For a deeper dive into our evaluation process, you can review the notes from our very first call for contributions on our -`Architecture Community F2F Workshop [2025-02-11 - 2025-02-13] `_. - -Once a contribution is selected, it not only implements a new feature but also helps guide the ongoing evolution of S-CORE. - -**Replacement of existing functionality** -In S-CORE we aim for having only one solution for a specific problem. If you have an idea for improving an existing feature, you're welcome to pitch a replacement implementation. Just be sure to highlight clearly the benefits over the current solution. - - -Join Us in Building S-CORE --------------------------- - -- **Have a New Idea?** - Start by raising a new feature request to help expand the scope of our platform. - -- **Ready to Code?** - Submit a contribution pitch for a specific feature request if you have a solution you'd like to share. - -- **Looking to Improve What's Already There?** - Contribute enhancements to existing implementations or get involved with one of our Feature Teams (FTs). - -We're excited to have you on board. Together, we can shape S-CORE into a platform that's not only innovative but also a joy to be a part of. - -.. _what_is_a_pr: - -What is a Pull Request (PR)? -============================ - -.. document:: Pull Request Guideline - :id: doc__pull_request_guideline - :status: valid - :version: 1 - :safety: QM - :security: NO - :realizes: wp__training_path[version==1] - -A Pull Request (**PR**) is the **ONLY** way to contribute **CODE** to the *S-CORE* project. - -The figure below shows a simplified workflow for a PR. - -* The contributor (:need:`Contributor `) starts by creating a PR: `Creating a Pull Request (Github Docs) `_. -* Required reviewers will be automatically assigned based on the contributed content (via CODEOWNERS). -* If the content fullfils the review and acceptance criteria, a committer (:need:`Committer `) will approve the *PR* and thus it can be merged. - -.. figure:: _assets/score_contribution_request_simple.drawio.svg - :width: 600 - :align: center - :alt: Simple *PR* based contribution workflow overview - - Simple *PR* based contribution workflow overview - -Content in general may contain features, requirements, architectural designs, modules, components, detailed designs, implementations and source code, tests, process descriptions, any documentations, guidelines, tutorials, tools, or infrastructure topics and more of the *S-CORE* project. In case of doubt or for any other input we strongly encourage to open a *GitHub Issue* (:need:`doc__issue_guideline`) first. - -The *PR* should provide all required information of the new or changed content. Therefore the *S-CORE* project provides content specific templates, which the contributor (:need:`Contributor `) must use for their *PR* (ToDo link here to the templates overview). Templates may be *PR* templates, *GitHub Issue* templates and also additional document or work product templates. - -The content of any *PR* is the commit content and the description as well as the comments given in GitHub and is kept in a versioned repository, their revision history is the historical record of the PR. - -This historical record is available by the normal git commands for retrieving older revisions, and can also be browsed on GitHub. - - -Detailed *S-CORE* Pull Request Workflow ---------------------------------------- - -This chapter is only for optional read to understand the details for the Pull Request workflow defined in *S-CORE*. - -The figure below gives an overview about all the possible steps for a *PR* until it is either accepted or rejected. - -.. figure:: _assets/score_contribution_request_standard.drawio.svg - :width: 100% - :align: center - :alt: Detailed *S-CORE* Pull request workflow overview - - Detailed *S-CORE* Pull request workflow overview - -Create a PR ------------ - -The contributor (:need:`Contributor `) creates a PR. - -Reviewers will be automatically assigned (:need:`Committer `) based on the contributed content (ruleset as defined by the committers). In addition several checks for the contributed content (ToDo: Link to the description of the checks) will be started. - -Review and merge a PR ---------------------- - -A *PR* is reviewed with all content that adds/modifies it. As long as a *PR* requires further work by the contributor (:need:`Contributor `), the *PR* is not approved and thus not merged and further changes are requested. Once the contributor (:need:`Contributor `) considers all review comments as resolved, :need:`Contributor ` can re-request a review. The committer (:need:`Committer `) reviews the *PR* content according the *S-CORE* review and acceptance criteria (ToDo link here to the criteria). -Further the contributor (:need:`Contributor `) must resolve found issues from the automated checks, if they do not pass. - -As long as the *PR* does not meet the defined criteria and the checks does not pass, it will not be approved. If it does not follow the required templates, based on the provided content or the templates are not filled out properly, the committer as reviewer (:need:`Committer `) will place the *PR* to the "Draft" state. - -It is then the responsibility of the contributor (:need:`Contributor `) to add the missing information and to re-start the contribution by placing the *PR* back for review. - -To change from "Draft" to "Open" see `Changing the stage of a pull request (Github Docs) `_. - -At any point the contributor (:need:`Contributor `) may decide not to continue with the PR, then the contributor (:need:`Contributor `) just closes the PR. - -.. _what_is_a_github_issue: - -What is a GitHub Issue? -======================= - -.. document:: Issue Guideline - :id: doc__issue_guideline - :status: valid - :version: 1 - :safety: QM - :security: NO - :realizes: wp__training_path[version==1] - -A *GitHub Issue* is the way to report bugs or propose improvements without knowing the solution and to request features (incl. scope changes). - -For creating *GitHub Issue* compare here: `Creating a GitHub Issue (Github Docs) `_. - -Create an *GitHub Issue* to collect feedback, before investing too much effort into a *PR*. *GitHub Issues* may be accompanied by draft *PRs* if code is to be shown. - -It can also be used to collect community input and for planning and tracking activities. - -The figure below shows options to report something. - -.. figure:: _assets/score_discussion_request_options.drawio.svg - :width: 400 - :align: center - :alt: Reporting options overview - - Reporting options overview - -.. toctree:: - :hidden: - :maxdepth: 2 - - feature_request diff --git a/docs/contribute/development/assets/example_rust_source_code_link.png b/docs/contribute/development/_assets/example_rust_source_code_link.png similarity index 100% rename from docs/contribute/development/assets/example_rust_source_code_link.png rename to docs/contribute/development/_assets/example_rust_source_code_link.png diff --git a/docs/contribute/fork/assets/internal-first-workflow.drawio.svg b/docs/contribute/development/_assets/internal-first-workflow.drawio.svg similarity index 100% rename from docs/contribute/fork/assets/internal-first-workflow.drawio.svg rename to docs/contribute/development/_assets/internal-first-workflow.drawio.svg diff --git a/docs/contribute/development/api_guideline.rst b/docs/contribute/development/api_guideline.rst index 2624b59c0f8..61ba8644bdb 100644 --- a/docs/contribute/development/api_guideline.rst +++ b/docs/contribute/development/api_guideline.rst @@ -12,11 +12,13 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _api_guide: + Designing API ############# -.. document:: API Guidelines - :id: doc__api_guidelines +.. document:: API Guide + :id: doc__api_guide :status: draft :version: 1 :safety: QM diff --git a/docs/contribute/development/cpp/code_analysis.rst b/docs/contribute/development/cpp/cpp_code_analysis.rst similarity index 88% rename from docs/contribute/development/cpp/code_analysis.rst rename to docs/contribute/development/cpp/cpp_code_analysis.rst index 0a9e879a137..69158da8ca7 100644 --- a/docs/contribute/development/cpp/code_analysis.rst +++ b/docs/contribute/development/cpp/cpp_code_analysis.rst @@ -12,10 +12,12 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Code Analysis C++ +.. _cpp_code_analysis: + +C++ Code Analysis ################# -.. document:: Static Code Analysis C++ +.. document:: C++ Code Analysis :id: doc__cpp_code_analysis :status: valid :version: 1 @@ -27,9 +29,12 @@ Code Analysis C++ Static Code Analysis ==================== -In order to fulfil the S-CORE related standard requirements a concept for *Static Code Analysis* needs to be established. Input for the analysis is based upon *MISRA* and *ISO26262* standards in accordance to the :need:`doc__cpp_coding_guidelines`. +In order to fulfil the S-CORE related standard requirements a concept for *Static Code Analysis* needs to be established. +Input for the analysis is based upon *MISRA* and *ISO26262* standards in accordance to the :need:`doc__cpp_coding_guidelines`. -Checking those rules can partially be automated and implemented by a combination of different tools. Thus a mapping needs to be established which provides a linkage of all *MISRA* requirements to the respective tool requirements/rules. For *MISRA C++:2023* this mapping is established: :need:`here ` +Checking those rules can partially be automated and implemented by a combination of different tools. +Thus a mapping needs to be established which provides a linkage of all *MISRA* requirements to the respective tool requirements/rules. +For *MISRA C++:2023* this mapping is established: :need:`here ` .. needuml:: diff --git a/docs/contribute/development/cpp/coding_guidelines.rst b/docs/contribute/development/cpp/cpp_coding_guidelines.rst similarity index 98% rename from docs/contribute/development/cpp/coding_guidelines.rst rename to docs/contribute/development/cpp/cpp_coding_guidelines.rst index a6570dba225..5538ebdd65a 100644 --- a/docs/contribute/development/cpp/coding_guidelines.rst +++ b/docs/contribute/development/cpp/cpp_coding_guidelines.rst @@ -12,8 +12,10 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Writing C++ Code incl. Coding Guidelines -######################################## +.. _cpp_coding_guidelines: + +C++ Coding Guidelines +##################### .. document:: Coding Guidelines C++ :id: doc__cpp_coding_guidelines diff --git a/docs/contribute/development/cpp/misra_2023_rule_mapping.rst b/docs/contribute/development/cpp/cpp_misra_rules.rst similarity index 86% rename from docs/contribute/development/cpp/misra_2023_rule_mapping.rst rename to docs/contribute/development/cpp/cpp_misra_rules.rst index c5163c299b4..066e42b10fb 100644 --- a/docs/contribute/development/cpp/misra_2023_rule_mapping.rst +++ b/docs/contribute/development/cpp/cpp_misra_rules.rst @@ -12,11 +12,13 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -MISRA C++:2023 Rule Mapping -########################### +.. _cpp_misra_rules: -.. document:: MISRA C++:2023 Rule Mapping - :id: doc__cpp_misra2023_rule_mapping +C++ MISRA Rules +############### + +.. document:: C++ MISRA Rules + :id: doc__cpp_misra_rules :status: draft :version: 1 :safety: ASIL_B diff --git a/docs/contribute/development/cpp/index.rst b/docs/contribute/development/cpp/index.rst deleted file mode 100644 index f7a7040d6b6..00000000000 --- a/docs/contribute/development/cpp/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -C++ -### - -.. toctree:: - :maxdepth: 1 - - coding_guidelines - code_analysis - misra_2023_rule_mapping diff --git a/docs/contribute/development/fork/index.rst b/docs/contribute/development/fork/index.rst new file mode 100644 index 00000000000..c5dea5a369c --- /dev/null +++ b/docs/contribute/development/fork/index.rst @@ -0,0 +1,395 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + + +.. _forking_guide: + +Forking Guide +############# + +.. document:: Forking Guide + :id: doc__forking_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + + + +1 Purpose & Context +=================== + +This guide helps companies (tool vendors, integrators, OEMs, suppliers) decide how to structure forks of S-CORE repositories to: + +* Contribute efficiently upstream +* Integrate internal compliance & security workflows +* Keep proprietary or distribution-specific assets separate +* Avoid accidental leakage of secrets or internal IP +* Automate promotion of reviewed code to the public community dadad + +.. note:: + S-CORE spans 50+ repositories. You don't need a one-size-fits-all approach — pick the minimal model per repository and evolve as needs grow. + +1.1 Audience +------------ + +Engineering organizations managing both internal and external code flows; platform/DevEx teams formalizing contribution and publication pipelines; compliance and security stakeholders. + +1.2 Goals +--------- + +Provide a decision and execution framework that reduces friction and risk while keeping the path to upstream contribution short. + +1.3 Out of Scope +---------------- + +License interpretation, export control, internal HR / policy approvals. You must comply with S-CORE licensing independently. + +1.4 Private vs Public Forks +--------------------------- + +Each model description focuses on WHEN to use it and inherent CONSTRAINTS. Implementation details are in Section 2. + +Public Fork +^^^^^^^^^^^ + +- Use when: You only need to contribute upstream or maintain a long-lived divergence openly. +- Pros: Simple, no internal infra, no delays for daily work. +- Constraints: No internal-only code separation; risk of accidental leakage if you try to “hide” things manually. Review happens in public, which may not suit all contributions. All authors must be comfortable with public exposure. + +Internal Fork +^^^^^^^^^^^^^ + +- Use when: You passively consume S-CORE (read-only) or maintain internal extensions not (yet) publishable. +- Pros: Freedom to experiment internally; shield proprietary assets. +- Constraints: Requires disciplined syncing from upstream to avoid drift. Requires internal infrastructure. No contributions possible. + +Note that internal forks can use any infrastructure and do not need to be on GitHub. + +Hybrid (Both) +^^^^^^^^^^^^^ + +- Use when: You both maintain internal-only additions AND contribute upstream regularly. + + + +2 Implementing the Hybrid Approach +================================== + + +When organizations need both internal-only work and a path to upstream contribution, adopt a hybrid approach. Below each variant includes a short "use / pros / constraints" summary and recommended practices. + +Depending on policy and compliance constraints, pick the simplest viable variant and document ownership for sync and publication tooling. + +2.1 Public-first Workflow +------------------------- + +All S-CORE targeting contributions happen directly on the public fork. + +Recommendations + +1. Short-lived feature branches (e.g., ``topic`` or ``/``) +2. Open an individual PR for each change upstream +3. Delete merged branches + +Notes + +- Your fork's ``main`` may either track upstream or remain unused. +- Use pre-commit checks to detect internal-only patterns before pushing. + +Use when + +- You primarily contribute upstream or maintain public divergences. + +Pros + +- Simple: little infrastructure needed and fewer delays for day-to-day work. + +Constraints + +- No built-in separation for internal-only code; manual hiding is error-prone. +- History and reviews are public; not suitable for all compliance/privacy needs. +- Potentially not suitable for large or sensitive contributions. + +2.2 Internal-first Workflow +--------------------------- + +Development happens internally; publication to a public fork is an explicit, audited step. This is common where compliance, IP, or privacy constraints apply. + +Common reasons + +- Organizational policies requiring internal vetting before public exposure +- Need to shield proprietary assets +- Need to restrict author visibility + +Workflow overview + +Just an example, obviously adapt to your needs. + +- Development in ``company-internal/feature_unverified`` (branched of from ``eclipse-score/main``) +- Pull request to ``company-internal/feature_verified`` +- Internal review of the PR and automated checks (e.g. that no secrets are contained) +- If passed, merge to ``company-internal/feature_verified`` +- Transfer to ``company-contrib/feature`` (manual or automated transformation) +- Open PR to ``eclipse-score/main`` (manual or automated) + +The following diagram illustrates this workflow and also highlights the boundaries between public (Internet) and (company) internal space. + +.. image:: ../_assets/internal-first-workflow.drawio.svg + :alt: repository layout + :width: 500 + :align: center + +Use when + +- Your organization mandates internal control and vetting before any public push. + +Pros + +- Good for protecting IP and meeting regulatory/compliance requirements. + +Constraints + +- Requires internal infrastructure and operational processes to manage branches, reviews, and syncing. +- Demands disciplined synchronization from upstream to avoid painful drift and costly merges. +- Typically increases TTM (time-to-merge) for open contributions; may hinder collaborative workflows. + +Note: internal forks do not need to live on GitHub; choose infrastructure that meets your needs. + +2.3 Mixing Both Workflows +------------------------- + +Some organizations choose a pragmatic mix: public-first for small changes, internal-first for large or sensitive changes. + +Use when + +- You need both, efficiency and internal-first workflows. + +Pros + +- Flexible: reduce friction for frequent contributions while protecting sensitive work. Lets you apply lightweight public workflows for small items and/or trusted contributors, and heavier internal processes for sensitive work. See when to use-sections in internal-first and public-first workflows for guidance. + +Constraints + +- Adds process complexity and requires clear tooling and ownership to avoid confusion and double-work. +- Requires careful documentation and automation to keep transformations, authorship, and history coherent across boundaries. + + + +3. How To work with forks +========================= + +First and foremost see `GitHub's guide to working with forks `_ + +Note that in enterprise environments forks will usually be created by forking into an company organization (e.g. ``my_company/score``) rather than a personal account. And those will be created by infrastructure administrators rather than individual developers. + +You can create such a fork e.g. via the GitHub CLI, `gh repo fork eclipse-score/score `_, or via an infrastructure-as-code process. + +The default remote names will be: + +- ``origin``: your fork (e.g. ``my_company/score``) +- ``upstream``: the original repo (e.g. ``eclipse-score/score``) + +Flow of a feature +----------------- + +There is a number of ways to achieve the same result in git, and it comes down to personal/team preference. Here is one possible approach. + +.. code:: + + # Update local main + git switch main + git pull upstream main + + # Create a feature branch + git switch -c + + # Commit and push + git add . + git commit -m "" + git push -u origin + + +Now you can create PRs from ```` to ``upstream/main`` directly. See `GitHub Docs - Creating a pull request from a fork `_ for details. +Alternatively you can use ``gh pr create`` to create PRs from the command line. + +Opinionated Alternative: change main reference +---------------------------------------------- + +If you prefer to keep your local ``main`` tracking upstream directly (and avoid maintaining ``my_company/main``), set upstream as the branch's upstream and fast-forward when needed: + +.. code:: + + git switch main + git branch --set-upstream-to=upstream/main + git reset --hard upstream/main + + +This makes daily flow trivial: ``git pull`` on ``main`` gives you the latest upstream state. + +Rest, unsorted +---------------- + +Transformation / Filtering Pipeline (Copybara Implementation) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Adds controlled publication with filtering and metadata normalization. + + +Overview +^^^^^^^^ + +`Copybara `_ synchronizes code between repositories and can +- Mirror internal → public +- Filter files +- Transform content and metadata +- Preserve coherent history + +Key Benefits +^^^^^^^^^^^^ + +Iterative (non-squash) commits: + +- Retain individual commits +- Preserve messages & timestamps +- Avoid history compression + +File filtering: + +- Exclude internal-only assets (e.g., ``.github/workflows``, ``copy.bara.sky``) +- Publish only OSS-relevant content + +Author preservation: + +.. code:: + + authoring = authoring.pass_thru("Qorix Bot ") + + +Preserves original commit authors for traceability. + +Transformations: +Supports ``core.replace``, ``core.move``, ``core.transform``, header injection, folder renames. + +Example: + +.. code:: + + transformations = [ + core.replace( + before = "INTERNAL_PATH", + after = "PUBLIC_PATH", + ) + ] + + +Minimal Configuration Example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: + + origin = git.origin( + url = "https://github.com/qorix-group/inc_orchestrator_internal.git", + ref = "main", + ) + + destination = git.destination( + url = "https://github.com/qorix-group/inc_orchestrator.git", + fetch = "refs/heads/main", + push = "refs/heads/{{BRANCH}}", + ) + + core.workflow( + name = "publish_branch", + mode = "ITERATIVE", + origin = origin, + origin_files = glob([ + "**", + ], exclude=[ + "copy.bara.sky", + "sync.sky", + ".github/workflows/copybara.yml", + ".github/workflows/sync.yml", + ]), + destination = destination, + authoring = authoring.pass_thru("Qorix Bot "), + transformations = [], + ) + + +CI Integration {#ci-integration} +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Example CI steps to generate a GitHub App token, configure git, and run Copybara: + +.. code:: + + - name: Generate GitHub App token + id: generate_token + uses: tibdex/github-app-token@v2 + with: + app_id: ${{ secrets.GH_APP_ID }} + private_key: ${{ secrets.GH_APP_PRIVATE_KEY }} + + - name: Configure Git + run: | + git config --global user.name "Qorix Bot" + git config --global user.email "bot@qorix.dev" + echo "https://x-access-token:${{ steps.generate_token.outputs.token }}@github.com" > ~/.git-credentials + + - name: Run Copybara + run: | + sed -i "s/{{BRANCH}}/${{ github.event.inputs.branch_name }}/g" copy.bara.sky + curl -LO https://github.com/qorix-group/copybara/releases/download/v20250508/copybara_deploy.jar + java -jar copybara_deploy.jar migrate copy.bara.sky publish_branch + + +Local Usage +^^^^^^^^^^^ + +.. code:: + + java -jar copybara_deploy.jar --init-history --force copy.bara.sky publish_branch + + +Use local runs to preview migrations or sync new branches outside CI. + +Challenges & Trade-offs +^^^^^^^^^^^^^^^^^^^^^^^ + ++--------------------------------------+----------------------------------+ +| Challenge | Impact | ++======================================+==================================+ +| No native GH default token support | Extra auth setup | +| Requires state for first branch push | One-time `--init-history` nuance | +| Credential & git config ceremony | Boilerplate in CI | +| Additional maintenance | Long-term ownership needed | ++--------------------------------------+----------------------------------+ + +Summary +^^^^^^^ +Copybara offers a controlled, scriptable way to synchronize repositories while filtering content and preserving authorship. Use it when manual workflows no longer scale or policy filtering is mandatory. + +Keeping Your Fork Updated +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Periodically update your fork's ``main`` from S-CORE ``main`` and run internal checks (tests, linting, compliance) before accepting changes. Neglecting regular syncs increases integration cost over time. + +Prefer GitHub Apps instead of (Fine Grained) Personal Access Tokens +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Prefer GitHub Apps for automated CI access where possible; fine-grained PATs increase token-management overhead and invite accidental long-lived credential exposure. + +TODO: add short examples and links to recommended app installation steps. diff --git a/docs/contribute/development/ide/clion.rst b/docs/contribute/development/ide/clion_guide.rst similarity index 86% rename from docs/contribute/development/ide/clion.rst rename to docs/contribute/development/ide/clion_guide.rst index 128036bfda3..4355191b998 100644 --- a/docs/contribute/development/ide/clion.rst +++ b/docs/contribute/development/ide/clion_guide.rst @@ -12,10 +12,20 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -CLion -##### +.. _clion_guide: -For CLion some of the configuration can be provided via the *.clwb* directory. But with this approach not all plugins can be configured. +CLion Guide +########### + +.. document:: CLion Guide + :id: doc__clion_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + +For `CLion ` some of the configuration can be provided via the *.clwb* directory. But with this approach not all plugins can be configured. Starlark ======== diff --git a/docs/contribute/development/ide/vscode.rst b/docs/contribute/development/ide/vscode_guide.rst similarity index 93% rename from docs/contribute/development/ide/vscode.rst rename to docs/contribute/development/ide/vscode_guide.rst index 53fdb3f57ad..6248511db49 100644 --- a/docs/contribute/development/ide/vscode.rst +++ b/docs/contribute/development/ide/vscode_guide.rst @@ -12,10 +12,22 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -VS Code -####### +.. _vscode_guide: -For VS Code any preexisting configuration is provided via the workspace configuration in the directory . It includes +VS Code Guide +############# + +.. document:: VSCode Guide + :id: doc__vscode_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + + + +For `VS Code ` any preexisting configuration is provided via the workspace configuration in the directory . It includes * some formatting rules * configuration for recommended plugins diff --git a/docs/contribute/development/index.rst b/docs/contribute/development/index.rst deleted file mode 100644 index 2cb371a6ce9..00000000000 --- a/docs/contribute/development/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2024 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Development -########### - -.. toctree:: - :maxdepth: 1 - - development_environment - traceability_tooling - api_guideline - cpp/index - rust/index - python/index diff --git a/docs/contribute/development/python/index.rst b/docs/contribute/development/python/index.rst deleted file mode 100644 index 6c521fe1dbf..00000000000 --- a/docs/contribute/development/python/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Python -###### - -.. toctree:: - :maxdepth: 1 - - coding_guidelines diff --git a/docs/contribute/development/python/coding_guidelines.rst b/docs/contribute/development/python/python_coding_guidelines.rst similarity index 91% rename from docs/contribute/development/python/coding_guidelines.rst rename to docs/contribute/development/python/python_coding_guidelines.rst index eab1845ecb8..f0c323c2635 100644 --- a/docs/contribute/development/python/coding_guidelines.rst +++ b/docs/contribute/development/python/python_coding_guidelines.rst @@ -12,8 +12,10 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Writing Python Code -################### +.. _python_coding_guidelines: + +Python Coding Guidelines +######################## .. document:: Coding Guidelines Python :id: doc__python_coding_guidelines @@ -68,7 +70,7 @@ Testing implementation details. Overly fine-grained tests lead to brittle code and high maintenance. - **Boundary conditions:** - Edge cases often break things. Think about invalid input, large data sets, empty cases, and concurrency issues. -- **Enesure Traceability** - Make sure to use the pytest decorator where applicable to enable traceabillity throughout. More infos on how to use it `example here `_ and `more through documentation here `_ +- **Ensure Traceability** - Make sure to use the pytest decorator where applicable to enable traceabillity throughout. More infos on how to use it `example here `_ and `more through documentation here `_ Documentation -------------------- diff --git a/docs/contribute/development/rust/certification/index.rst b/docs/contribute/development/rust/certification/index.rst deleted file mode 100644 index f28df729dfb..00000000000 --- a/docs/contribute/development/rust/certification/index.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2024 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Certification -############## - - -Rust Certification Guidance -=========================== - -This section summarizes certification-relevant guidance for Rust and its -tooling, especially in the context of ISO 26262 and RTCA DO-178C/DO-332. - -Key points for practice: - -* Determine tool confidence per S-CORE Tool Management process (TI/TD -> TCL). - TCL is HIGH unless TI=YES and TD=NO; in that case TCL is LOW. -* If TCL is LOW, tool qualification is required. Apply the "validation of - software tool" method with requirements, tests, and report updates in the - Tool Verification Report workflow. -* Confidence/qualification evidence is valid only for the exact tool version, - target architecture, and relevant tool configuration; changes require impact - analysis and re-validation as needed. -* Proven-in-use is not used as a safety argument in S-CORE (tailored out in - platform safety management). -* Use stable toolchains for safety-related development; nightly features are - not recommended. -* Configuration management must include compiler, as well as tools like rustup/cargo, clippy/rustdoc, - CodeQL, runtime libraries, and external crates. - -For S-CORE, this baseline guidance should be used for certification -strategy, while project-specific safety case evidence is documented in the -corresponding plans and work products. - -.. toctree:: - :maxdepth: 1 - - toolchain/index - tools/index diff --git a/docs/contribute/development/rust/certification/toolchain/compiler.rst b/docs/contribute/development/rust/certification/toolchain/compiler.rst deleted file mode 100644 index 101807e1c75..00000000000 --- a/docs/contribute/development/rust/certification/toolchain/compiler.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Certified compiler -################## diff --git a/docs/contribute/development/rust/certification/toolchain/index.rst b/docs/contribute/development/rust/certification/toolchain/index.rst deleted file mode 100644 index 6fcd8239278..00000000000 --- a/docs/contribute/development/rust/certification/toolchain/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2024 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Toolchain -######### - -.. toctree:: - :maxdepth: 1 - - compiler - libcore - libstd diff --git a/docs/contribute/development/rust/certification/toolchain/libcore.rst b/docs/contribute/development/rust/certification/toolchain/libcore.rst deleted file mode 100644 index 7993ff70ad6..00000000000 --- a/docs/contribute/development/rust/certification/toolchain/libcore.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Certified libcore -################# diff --git a/docs/contribute/development/rust/certification/toolchain/libstd.rst b/docs/contribute/development/rust/certification/toolchain/libstd.rst deleted file mode 100644 index f1a48a1f684..00000000000 --- a/docs/contribute/development/rust/certification/toolchain/libstd.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Certified libstd -################# diff --git a/docs/contribute/development/rust/certification/tools/coverage.rst b/docs/contribute/development/rust/certification/tools/coverage.rst deleted file mode 100644 index 3d0806bef7b..00000000000 --- a/docs/contribute/development/rust/certification/tools/coverage.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Coverage -######### diff --git a/docs/contribute/development/rust/certification/tools/formatting.rst b/docs/contribute/development/rust/certification/tools/formatting.rst deleted file mode 100644 index 4e774d4ccdf..00000000000 --- a/docs/contribute/development/rust/certification/tools/formatting.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Formatting -########### diff --git a/docs/contribute/development/rust/certification/tools/index.rst b/docs/contribute/development/rust/certification/tools/index.rst deleted file mode 100644 index 3cf46bfae4e..00000000000 --- a/docs/contribute/development/rust/certification/tools/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2024 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Tools -######### - -.. toctree:: - :maxdepth: 1 - - formatting - coverage - static_analysis diff --git a/docs/contribute/development/rust/certification/tools/static_analysis.rst b/docs/contribute/development/rust/certification/tools/static_analysis.rst deleted file mode 100644 index 26990586865..00000000000 --- a/docs/contribute/development/rust/certification/tools/static_analysis.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Static Analysis -############### diff --git a/docs/contribute/development/rust/rust_api_design.rst b/docs/contribute/development/rust/rust_api_design.rst index 814eb99679a..308c638dc4b 100644 --- a/docs/contribute/development/rust/rust_api_design.rst +++ b/docs/contribute/development/rust/rust_api_design.rst @@ -12,16 +12,18 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Rust API design guidelines +.. _rust_api_design_guidelines: + +Rust API Design Guidelines ########################## -.. document:: Rust API design guidelines +.. document:: Rust API Design Guidelines :id: doc__rust_api_design :status: draft :version: 1 :safety: QM :security: NO - :realizes: wp__training_path[version==1] + :realizes: wp__sw_development_plan[version==1] Preface ======= diff --git a/docs/contribute/development/rust/coding_guidelines.rst b/docs/contribute/development/rust/rust_coding_guidelines.rst similarity index 99% rename from docs/contribute/development/rust/coding_guidelines.rst rename to docs/contribute/development/rust/rust_coding_guidelines.rst index 060bd7cc073..b55c4b5b594 100644 --- a/docs/contribute/development/rust/coding_guidelines.rst +++ b/docs/contribute/development/rust/rust_coding_guidelines.rst @@ -12,8 +12,10 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Writing Rust Code incl. Coding Guidelines -######################################### +.. _rust_coding_guidelines: + +Rust Coding Guidelines +###################### .. document:: Coding Guidelines Rust :id: doc__rust_coding_guidelines diff --git a/docs/contribute/development/development_environment.rst b/docs/contribute/development/setup_dev_environment.rst similarity index 91% rename from docs/contribute/development/development_environment.rst rename to docs/contribute/development/setup_dev_environment.rst index 114dca48826..ce1ec7c5d89 100644 --- a/docs/contribute/development/development_environment.rst +++ b/docs/contribute/development/setup_dev_environment.rst @@ -12,21 +12,23 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. document:: Development Environment - :id: doc__develop_environment +.. _setup_dev_environment: + +Set Up the Development Environment +################################## + +.. document:: Development Environment Set Up + :id: doc__develop_environment_set_up :status: valid :version: 1 - :safety: ASIL_B - :realizes: wp__sw_development_plan[version==1] - :security: YES - -.. _setting_up_dev_env: + :safety: QM + :realizes: wp__training_path[version==1] + :security: NO -Setting Up the Development Environment -###################################### -*The development environment may vary depending on the repository you want to contribute to. This -document describes the setup for the `score` repository. Others should be similar.* +.. note:: + The development environment may vary depending on the repository you want to contribute to. This + document describes the setup for the `score` repository. Others should be similar. Devcontainer Setup ================== @@ -149,8 +151,8 @@ IDE Guides .. toctree:: :maxdepth: 1 - ide/vscode - ide/clion + ide/vscode_guide + ide/clion_guide WSL2 Settings ============= diff --git a/docs/contribute/development/traceability_tooling.rst b/docs/contribute/development/traceability_guidelines.rst similarity index 90% rename from docs/contribute/development/traceability_tooling.rst rename to docs/contribute/development/traceability_guidelines.rst index f0a1ef3b511..c51cf0cc32d 100644 --- a/docs/contribute/development/traceability_tooling.rst +++ b/docs/contribute/development/traceability_guidelines.rst @@ -1,4 +1,4 @@ -.. +.. # ******************************************************************************* # Copyright (c) 2026 Contributors to the Eclipse Foundation # @@ -12,29 +12,30 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _traceability_guideline: -.. document:: Traceability Tooling - :id: doc__traceability_tooling +Traceability Guideline +###################### + +.. document:: Traceability Guide + :id: doc__traceability_guide :status: valid :version: 1 - :safety: QM - :security: NO - :realizes: wp__requirements_proc_tool[version==1] + :safety: ASIL_B + :security: YES + :realizes: wp__sw_development_plan[version==1] -Traceability Tooling -#################### This document describes tools or some functionality of them, that can be used regardless of source code language.These tools are also provided by S-CORE projects, like Docs-As-Code. - -Link Requirements to Source Code +Link Requirements to Source Code ******************************** This functionality provides the ability to link any requirement to any part of the source code. It is possible to link as many places of source code as are needed. All of them will show up in the requirement. -All that is needed is to write the 'template string' that the program is looking for. +All that is needed is to write the 'template string' that the program is looking for. It is either `# req-Id: ` or `# req-traceability: ` If there is multiple requirements that need to be linked to this place in the source code, repeat the line for each one. @@ -75,8 +76,8 @@ It skips all files that end with one of the following: The template string works regardless of the language. This means both following examples are valid and will work. -.. code-block:: cpp - +.. code-block:: cpp + // # req-Id: comp_req__containers_rust__fixed_vector int your_function() { ... @@ -91,9 +92,9 @@ This means both following examples are valid and will work. } -Here is how this would look rendered: +Here is how this would look rendered: -.. image:: assets/example_rust_source_code_link.png +.. image:: _assets/example_rust_source_code_link.png @@ -110,7 +111,7 @@ In rough terms the data flow looks as follows. Your testing framework produces XML files with pre-defined properties. These XML files are loaded and parsed. The test needs to get build details from the parsed data and link it to the requirements mentioned. -You can now also do statistics on your tests. +You can now also do statistics on your tests. .. code-block:: rst @@ -120,7 +121,7 @@ You can now also do statistics on your tests. :tags: TEST :columns: name as "testcase";result;fully_verifies;partially_verifies;test_type;derivation_technique;id as "link" - + .. needpie:: Test Results :labels: passed, failed, skipped :colors: green, red, orange @@ -138,4 +139,3 @@ Find More Information ===================== If you need more information, you can read it all in the `Docs as Code Documentation `_ - diff --git a/docs/contribute/documentation/assets/docs-as-code/drawio-editing.png b/docs/contribute/documentation/_assets/drawio-editing.png similarity index 100% rename from docs/contribute/documentation/assets/docs-as-code/drawio-editing.png rename to docs/contribute/documentation/_assets/drawio-editing.png diff --git a/docs/contribute/documentation/assets/docs-as-code/example.drawio.svg b/docs/contribute/documentation/_assets/example.drawio.svg similarity index 100% rename from docs/contribute/documentation/assets/docs-as-code/example.drawio.svg rename to docs/contribute/documentation/_assets/example.drawio.svg diff --git a/docs/contribute/documentation/assets/docs-as-code/example.puml b/docs/contribute/documentation/_assets/example.puml similarity index 100% rename from docs/contribute/documentation/assets/docs-as-code/example.puml rename to docs/contribute/documentation/_assets/example.puml diff --git a/docs/contribute/documentation/docs-as-code.rst b/docs/contribute/documentation/docs-as-code_guide.rst similarity index 79% rename from docs/contribute/documentation/docs-as-code.rst rename to docs/contribute/documentation/docs-as-code_guide.rst index ad1f9c8e5b1..15c4f007c2d 100644 --- a/docs/contribute/documentation/docs-as-code.rst +++ b/docs/contribute/documentation/docs-as-code_guide.rst @@ -12,13 +12,24 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Docs-As-Code -============ +.. _docs_as_code_guide: + +Docs-As-Code Guide +================== + +.. document:: Docs-As-Code Guide + :id: doc__docs_as_code_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] Introduction ------------ -This document describes how to write and publish documentation using the S-CORE Docs-As-Code approach. +This document gives an overview how to write and publish documentation using the S-CORE Docs-As-Code approach. +Details to be found at : https://eclipse-score.github.io/docs-as-code/main/ Diagrams -------- @@ -35,7 +46,7 @@ The easiest way to use Draw.io is to create a new file in VS Code and use the Dr The new file must be named with the `.drawio.svg` extension. When you click on the file, the Draw.io editor will open within VS Code: -.. image:: assets/docs-as-code/drawio-editing.png +.. image:: _assets/drawio-editing.png :alt: Draw.io Editor in VS Code :scale: 20% @@ -49,7 +60,7 @@ Then you can embed the image in .rST files like this: Which will render like this: -.. image:: assets/docs-as-code/example.drawio.svg +.. image:: _assets/example.drawio.svg :alt: Example Diagram PlantUML @@ -87,5 +98,5 @@ Alternatively you can include them as .puml files like this: Which will render like this: -.. uml:: assets/docs-as-code/example.puml +.. uml:: _assets/example.puml :alt: Example Diagram diff --git a/docs/contribute/documentation/index.rst b/docs/contribute/documentation/index.rst deleted file mode 100644 index 64fd22b4e5a..00000000000 --- a/docs/contribute/documentation/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2024 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -Documentation -############# - -.. toctree:: - :maxdepth: 1 - - docs-as-code diff --git a/docs/contribute/ci/publishing-gh-pages.rst b/docs/contribute/documentation/publishing-gh-pages.rst similarity index 94% rename from docs/contribute/ci/publishing-gh-pages.rst rename to docs/contribute/documentation/publishing-gh-pages.rst index 3d9cfd6bac4..ca33176065c 100644 --- a/docs/contribute/ci/publishing-gh-pages.rst +++ b/docs/contribute/documentation/publishing-gh-pages.rst @@ -12,8 +12,18 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Pushing to GitHub Pages from a Forked Pull Request -=================================================== +.. _publishing_github_pages: + +Publishing Github Pages from Pull Request +========================================= + +.. document:: Publishing Github Pages from Pull Request + :id: doc__pub_gh_pages_from_pr + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] Introduction ------------ diff --git a/docs/contribute/contribution_request/feature_request.rst b/docs/contribute/feature_request/feature_request.rst similarity index 98% rename from docs/contribute/contribution_request/feature_request.rst rename to docs/contribute/feature_request/feature_request.rst index 15418764b46..b098511168e 100644 --- a/docs/contribute/contribution_request/feature_request.rst +++ b/docs/contribute/feature_request/feature_request.rst @@ -12,9 +12,10 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _feature_request_guideline: -Feature & Enhancement Proposal (FEP) -##################################### +Feature Request Guideline +######################### .. document:: Feature Request Guideline :id: doc__feature_request_guideline @@ -22,9 +23,7 @@ Feature & Enhancement Proposal (FEP) :version: 2 :safety: QM :security: NO - :realizes: wp__training_path[version==1] - -.. _feature_request_guideline: + :realizes: wp__sw_development_plan, wp__training_path[version==1] This guide describes the **Feature & Enhancement Proposal (FEP)**: part of S-CORE's change process, and the Analyze step for *Feature* change requests and *Feature Modification* change diff --git a/docs/contribute/fork/index.md b/docs/contribute/fork/index.md deleted file mode 100644 index b22481730be..00000000000 --- a/docs/contribute/fork/index.md +++ /dev/null @@ -1,329 +0,0 @@ -# Enterprise Forking Guide for S-CORE Repositories - -## 1. Purpose & Context - -This guide helps companies (tool vendors, integrators, OEMs, suppliers) decide how to structure forks of S-CORE repositories to: - -- Contribute efficiently upstream -- Integrate internal compliance & security workflows -- Keep proprietary or distribution-specific assets separate -- Avoid accidental leakage of secrets or internal IP -- Automate promotion of reviewed code to the public community - -> S-CORE spans 50+ repositories. You don't need a one-size-fits-all approach — pick the minimal model per repository and evolve as needs grow. - -### 1.1 Audience - -Engineering organizations managing both internal and external code flows; platform/DevEx teams formalizing contribution and publication pipelines; compliance and security stakeholders. - -### 1.2 Goals -Provide a decision and execution framework that reduces friction and risk while keeping the path to upstream contribution short. - -### 1.3 Out of Scope -License interpretation, export control, internal HR / policy approvals. You must comply with S-CORE licensing independently. - -### 1.4 Private vs Public Forks - -Each model description focuses on WHEN to use it and inherent CONSTRAINTS. Implementation details are in Section 2. - -#### Public Fork - -- Use when: You only need to contribute upstream or maintain a long-lived divergence openly. -- Pros: Simple, no internal infra, no delays for daily work. -- Constraints: No internal-only code separation; risk of accidental leakage if you try to “hide” things manually. Review happens in public, which may not suit all contributions. All authors must be comfortable with public exposure. - -#### Internal Fork - -- Use when: You passively consume S-CORE (read-only) or maintain internal extensions not (yet) publishable. -- Pros: Freedom to experiment internally; shield proprietary assets. -- Constraints: Requires disciplined syncing from upstream to avoid drift. Requires internal infrastructure. No contributions possible. - -Note that internal forks can use any infrastructure and do not need to be on GitHub. - -#### Hybrid (Both) - -- Use when: You both maintain internal-only additions AND contribute upstream regularly. - ---- - -## 2. Implementing the Hybrid Approach - -When organizations need both internal-only work and a path to upstream contribution, adopt a hybrid approach. Below each variant includes a short "use / pros / constraints" summary and recommended practices. - -Depending on policy and compliance constraints, pick the simplest viable variant and document ownership for sync and publication tooling. - -### 2.1 Public-first Workflow - -All S-CORE targeting contributions happen directly on the public fork. - -Recommendations - -1. Short-lived feature branches (e.g., `topic` or `/`) -2. Open an individual PR for each change upstream -3. Delete merged branches - -Notes - -- Your fork's `main` may either track upstream or remain unused. -- Use pre-commit checks to detect internal-only patterns before pushing. - -Use when - -- You primarily contribute upstream or maintain public divergences. - -Pros - -- Simple: little infrastructure needed and fewer delays for day-to-day work. - -Constraints - -- No built-in separation for internal-only code; manual hiding is error-prone. -- History and reviews are public; not suitable for all compliance/privacy needs. -- Potentially not suitable for large or sensitive contributions. - -### 2.2 Internal-first Workflow - -Development happens internally; publication to a public fork is an explicit, audited step. This is common where compliance, IP, or privacy constraints apply. - -Common reasons - -- Organizational policies requiring internal vetting before public exposure -- Need to shield proprietary assets -- Need to restrict author visibility - -Workflow overview - -Just an example, obviously adapt to your needs. - -- Development in `company-internal/feature_unverified` (branched of from `eclipse-score/main`) -- Pull request to `company-internal/feature_verified` -- Internal review of the PR and automated checks (e.g. that no secrets are contained) -- If passed, merge to `company-internal/feature_verified` -- Transfer to `company-contrib/feature` (manual or automated transformation) -- Open PR to `eclipse-score/main` (manual or automated) - -The following diagram illustrates this workflow and also highlights the boundaries between public (Internet) and (company) internal space. - -![Internal contribution workflow](assets/internal-first-workflow.drawio.svg) - -Use when - -- Your organization mandates internal control and vetting before any public push. - -Pros - -- Good for protecting IP and meeting regulatory/compliance requirements. - -Constraints - -- Requires internal infrastructure and operational processes to manage branches, reviews, and syncing. -- Demands disciplined synchronization from upstream to avoid painful drift and costly merges. -- Typically increases TTM (time-to-merge) for open contributions; may hinder collaborative workflows. - -Note: internal forks do not need to live on GitHub; choose infrastructure that meets your needs. - -### 2.3 Mixing Both Workflows - -Some organizations choose a pragmatic mix: public-first for small changes, internal-first for large or sensitive changes. - -Use when - -- You need both, efficiency and internal-first workflows. - -Pros - -- Flexible: reduce friction for frequent contributions while protecting sensitive work. Lets you apply lightweight public workflows for small items and/or trusted contributors, and heavier internal processes for sensitive work. See when to use-sections in internal-first and public-first workflows for guidance. - -Constraints - -- Adds process complexity and requires clear tooling and ownership to avoid confusion and double-work. -- Requires careful documentation and automation to keep transformations, authorship, and history coherent across boundaries. - - - -## 3. How To work with forks - -First and foremost see [GitHub's guide to working with forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) - -Note that in enterprise environments forks will usually be created by forking into an company organization (e.g. `my_company/score`) rather than a personal account. And those will be created by infrastructure administrators rather than individual developers. - -You can create such a fork e.g. via the GitHub CLI, [`gh repo fork eclipse-score/score`](https://cli.github.com/manual/gh_repo_fork), or via an infrastructure-as-code process. - -The default remote names will be: - -- `origin`: your fork (e.g. `my_company/score`) -- `upstream`: the original repo (e.g. `eclipse-score/score`) - -### Flow of a feature - -There is a number of ways to achieve the same result in git, and it comes down to personal/team preference. Here is one possible approach. - -```bash -# Update local main -git switch main -git pull upstream main - -# Create a feature branch -git switch -c - -# Commit and push -git add . -git commit -m "" -git push -u origin -``` - -Now you can create PRs from `` to `upstream/main` directly. See [GitHub Docs - Creating a pull request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) for details. -Alternatively you can use `gh pr create` to create PRs from the command line. - - -#### Opinionated Alternative: change main reference - -If you prefer to keep your local `main` tracking upstream directly (and avoid maintaining `my_company/main`), set upstream as the branch's upstream and fast-forward when needed: - -```bash -git switch main -git branch --set-upstream-to=upstream/main -git reset --hard upstream/main -``` - -This makes daily flow trivial: `git pull` on `main` gives you the latest upstream state. - ---- - -## Rest, unsorted - -### Transformation / Filtering Pipeline (Copybara Implementation) - -Adds controlled publication with filtering and metadata normalization. - -#### Overview - -[Copybara](https://github.com/google/copybara) synchronizes code between repositories and can: - -- Mirror internal → public -- Filter files -- Transform content and metadata -- Preserve coherent history - -#### Key Benefits - -Iterative (non-squash) commits: - -- Retain individual commits -- Preserve messages & timestamps -- Avoid history compression - -File filtering: - -- Exclude internal-only assets (e.g., `.github/workflows`, `copy.bara.sky`) -- Publish only OSS-relevant content - -Author preservation: - -```python -authoring = authoring.pass_thru("Qorix Bot ") -``` - -Preserves original commit authors for traceability. - -Transformations: -Supports `core.replace`, `core.move`, `core.transform`, header injection, folder renames. - -Example: - -```python -transformations = [ - core.replace( - before = "INTERNAL_PATH", - after = "PUBLIC_PATH", - ) -] -``` - -#### Minimal Configuration Example - -```python -origin = git.origin( - url = "https://github.com/qorix-group/inc_orchestrator_internal.git", - ref = "main", -) - -destination = git.destination( - url = "https://github.com/qorix-group/inc_orchestrator.git", - fetch = "refs/heads/main", - push = "refs/heads/{{BRANCH}}", -) - -core.workflow( - name = "publish_branch", - mode = "ITERATIVE", - origin = origin, - origin_files = glob([ - "**", - ], exclude=[ - "copy.bara.sky", - "sync.sky", - ".github/workflows/copybara.yml", - ".github/workflows/sync.yml", - ]), - destination = destination, - authoring = authoring.pass_thru("Qorix Bot "), - transformations = [], -) -``` - -#### CI Integration {#ci-integration} - -Example CI steps to generate a GitHub App token, configure git, and run Copybara: - -```yaml -- name: Generate GitHub App token - id: generate_token - uses: tibdex/github-app-token@v2 - with: - app_id: ${{ secrets.GH_APP_ID }} - private_key: ${{ secrets.GH_APP_PRIVATE_KEY }} - -- name: Configure Git - run: | - git config --global user.name "Qorix Bot" - git config --global user.email "bot@qorix.dev" - echo "https://x-access-token:${{ steps.generate_token.outputs.token }}@github.com" > ~/.git-credentials - -- name: Run Copybara - run: | - sed -i "s/{{BRANCH}}/${{ github.event.inputs.branch_name }}/g" copy.bara.sky - curl -LO https://github.com/qorix-group/copybara/releases/download/v20250508/copybara_deploy.jar - java -jar copybara_deploy.jar migrate copy.bara.sky publish_branch -``` - -#### Local Usage - -```bash -java -jar copybara_deploy.jar --init-history --force copy.bara.sky publish_branch -``` - -Use local runs to preview migrations or sync new branches outside CI. - -#### Challenges & Trade-offs - -| Challenge | Impact | -|-----------|--------| -| No native GH default token support | Extra auth setup | -| Requires state for first branch push | One-time `--init-history` nuance | -| Credential & git config ceremony | Boilerplate in CI | -| Additional maintenance | Long-term ownership needed | - -#### Summary - -Copybara offers a controlled, scriptable way to synchronize repositories while filtering content and preserving authorship. Use it when manual workflows no longer scale or policy filtering is mandatory. - -### Keeping Your Fork Updated - -Periodically update your fork's `main` from S-CORE `main` and run internal checks (tests, linting, compliance) before accepting changes. Neglecting regular syncs increases integration cost over time. - -### Prefer GitHub Apps instead of (Fine Grained) Personal Access Tokens - -Prefer GitHub Apps for automated CI access where possible; fine-grained PATs increase token-management overhead and invite accidental long-lived credential exposure. - -TODO: add short examples and links to recommended app installation steps. diff --git a/docs/contribute/contribution_request/_assets/score_discussion_request_options.drawio.svg b/docs/contribute/general/_assets/issue_pull_request_relation.drawio.svg similarity index 100% rename from docs/contribute/contribution_request/_assets/score_discussion_request_options.drawio.svg rename to docs/contribute/general/_assets/issue_pull_request_relation.drawio.svg diff --git a/docs/contribute/contribution_request/_assets/score_contribution_request_simple.drawio.svg b/docs/contribute/general/_assets/pull_request_simple.drawio.svg similarity index 100% rename from docs/contribute/contribution_request/_assets/score_contribution_request_simple.drawio.svg rename to docs/contribute/general/_assets/pull_request_simple.drawio.svg diff --git a/docs/contribute/contribution_request/_assets/score_contribution_request_standard.drawio.svg b/docs/contribute/general/_assets/pull_request_standard.drawio.svg similarity index 100% rename from docs/contribute/contribution_request/_assets/score_contribution_request_standard.drawio.svg rename to docs/contribute/general/_assets/pull_request_standard.drawio.svg diff --git a/docs/contribute/general/contribution_attribution.rst b/docs/contribute/general/contribution_attribution_guide.rst similarity index 88% rename from docs/contribute/general/contribution_attribution.rst rename to docs/contribute/general/contribution_attribution_guide.rst index 44d0518d1fa..d20ec6f344f 100644 --- a/docs/contribute/general/contribution_attribution.rst +++ b/docs/contribute/general/contribution_attribution_guide.rst @@ -13,10 +13,10 @@ # ******************************************************************************* -.. _contribution_attribution: +.. _contribution_attribution_guide: -Actions to Ensure Proper Contribution Attribution in Eclipse S-CORE -=================================================================== +Contribution Attribution Guide +============================== To ensure that contributions are correctly attributed to organizations in the **Eclipse S-CORE** project, follow these steps: @@ -56,8 +56,6 @@ Actions for Employers 3. **Assist Employees in Aligning Emails** - If an employee has used an alternative email, **help them update their account** to include the relevant email address. - - Expected Outcome ----------------- @@ -65,7 +63,9 @@ Expected Outcome - **Member companies** will get proper recognition for their contributions. - The **chart updates overnight**, so changes will be reflected the next day. -🔹 **Note:** The **chart only displays contributions** from **Eclipse Foundation member companies**. -Contributions from individuals not associated with a member company will be listed under **"Contributor"**. +.. note:: + The **chart only displays contributions** from **Eclipse Foundation member companies**. + Contributions from individuals not associated with a member company will be listed under **"Contributor"**. + By following these steps, we can **ensure accurate reporting and better visibility** for organizational contributions. diff --git a/docs/contribute/general/folder.rst b/docs/contribute/general/folder_structure_convention.rst similarity index 98% rename from docs/contribute/general/folder.rst rename to docs/contribute/general/folder_structure_convention.rst index 6aa8f714bb7..45c3bce4389 100644 --- a/docs/contribute/general/folder.rst +++ b/docs/contribute/general/folder_structure_convention.rst @@ -12,15 +12,27 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Folder Structure -================ +.. _folder_structure_conventions: + +Folder Structure Conventions +============================ + + +.. document:: Folder Structure Conventions + :id: doc__git_folder_structure_conventions + :status: valid + :version: 1 + :safety: ASIL_B + :security: NO + :realizes: wp__sw_development_plan[version==1] + .. _platform_folder_structure: Platform Folder Structure ------------------------- -The following shows the folder structure of the platform repository (ordered alphabetically). The ordering of the documentation in the rendered documentation can be in a different order. +The following shows the folder structure of the platform repository Requirements on platform level │ ├── stakeholder/ -> Stakeholder requirements [:need:`wp__requirements_stkh`] - │ ├── tool/ -> Tool requirements (not covered in tool repositories) - │ │ [:need:`wp__requirements_proc_tool`] │ └── platform_assumptions/ -> Assumptions of use on platform level [:need:`wp__requirements_sw_platform_aou`] ├── safety/ -> Safety documentation on platform level (SEooC): │ [:need:`wp__platform_dfa`], [:need:`wp__platform_safety_manual`], │ [:need:`wp__platform_safety_package`], [:need:`wp__fdr_reports`], │ [:need:`wp__audit_report`] ├── score_tools/ -> Tool list and [:need:`wp__tool_verification_report`] + │ └── tools_requirements/ -> Tool requirements [:need:`wp__requirements_proc_tool`] ├── security/ -> Security documentation on platform level: │ [:need:`wp__platform_security_manual`], [:need:`wp__platform_security_package`], │ [:need:`wp__sw_platform_sbom`], [:need:`wp__platform_security_analysis`], diff --git a/docs/contribute/general/git.rst b/docs/contribute/general/git.rst index 894c3ebc130..8c1b40beb64 100644 --- a/docs/contribute/general/git.rst +++ b/docs/contribute/general/git.rst @@ -12,22 +12,20 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _git_guidelines: + +Git Guidelines +############## + .. document:: Git Guidelines - :id: doc__git_coding_guidelines + :id: doc__git_guidelines :status: valid :version: 1 :safety: ASIL_B :security: NO :realizes: wp__sw_development_plan[version==1] -.. _git_guidelines: - -################ - Git Guidelines -################ - -*********** - Motivation +Motivation *********** The commit history and especially the commit messages are part of a @@ -38,9 +36,8 @@ bugs). Git supports powerful tools to find out which commit introduced a bug (e.g., git bisect, git blame). Their level of usefulness depends on the quality of the commits and their respective commit messages. -****************** - Git Configuration -****************** +Git Configuration +***************** Authors name and e-mail address are part of the commit (and thus be part of the commit history). They must match the name and e-mail used for Eclipse registration. They can be specified via the @@ -52,9 +49,8 @@ They must match the name and e-mail used for Eclipse registration. They can be s email = (e.g. max.mustermann@something.com) name = Max Mustermann -*************** - Merging PRs -*************** +Merging PRs +*********** When merging a PR via the GitHub user interface: @@ -84,9 +80,8 @@ Use ``Rebase & Merge`` or ``Merge Commit`` in case: Keep in mind that upon merge the commit history of your branch will be preserved in the main branch of the repo as well. -********************** - Commit Message Format -********************** +Commit Message Format +********************* In S-CORE it is checked if git commit messages are written according to guidelines. However, it cannot enforce the meaningfulness of the @@ -181,9 +176,9 @@ Example Also-by: Some Bodyelse -******************** - Tips and Tricks -******************** + +Tips and Tricks +*************** Deal with Long-Living Feature Branches ====================================== diff --git a/docs/contribute/general/index.rst b/docs/contribute/general/index.rst deleted file mode 100644 index ca99824c62e..00000000000 --- a/docs/contribute/general/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2024 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -General -####### - -.. toctree:: - :maxdepth: 1 - - naming - git - folder - feature_flags - contribution_attribution - release_guide diff --git a/docs/contribute/general/issue.rst b/docs/contribute/general/issue.rst new file mode 100644 index 00000000000..3a3248664ed --- /dev/null +++ b/docs/contribute/general/issue.rst @@ -0,0 +1,41 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. _issue: + +Issue Guide +=========== + +.. document:: Issue Guide + :id: doc__issue_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + + +A *GitHub Issue* is the way to report bugs or propose improvements without knowing the solution and to request features (incl. scope changes). + +For creating *GitHub Issue* compare here: `Creating a GitHub Issue (Github Docs) `_. + +Create an *GitHub Issue* to collect feedback, before investing too much effort into a *PR*. *GitHub Issues* may be accompanied by draft *PRs* if code is to be shown. + +It can also be used to collect community input and for planning and tracking activities. + + +.. figure:: _assets/issue_pull_request_relation.drawio.svg + :width: 400 + :align: center + :alt: Issue PR Relation diff --git a/docs/contribute/general/release_guide.rst b/docs/contribute/general/module_release_guide.rst similarity index 100% rename from docs/contribute/general/release_guide.rst rename to docs/contribute/general/module_release_guide.rst diff --git a/docs/contribute/general/naming.rst b/docs/contribute/general/naming_conventions.rst similarity index 88% rename from docs/contribute/general/naming.rst rename to docs/contribute/general/naming_conventions.rst index fcf91712486..aa1d6436e57 100644 --- a/docs/contribute/general/naming.rst +++ b/docs/contribute/general/naming_conventions.rst @@ -12,6 +12,11 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _naming_conventions: + +Naming Conventions +================== + .. document:: Naming Conventions :id: doc__naming_conventions :status: valid @@ -20,13 +25,11 @@ :security: YES :realizes: wp__sw_development_plan[version==1] -Naming Conventions -================== .. _naming_convention_files: -Naming Conventions of Files ---------------------------- +Naming Convention of Files +-------------------------- The overall naming convention is to use snake case for all files and folders (all files are named lowercase and spaces are replaced by underscores). @@ -34,10 +37,10 @@ For drawio pictures use the extension .drawio.svg - this enables the tooling to .. _naming_convention_needs: -Naming Convention for UIDs --------------------------- +Naming Convention for Sphinx Needs UIDs +--------------------------------------- -The naming convention for the UIDs of **all** elements shall be defined as follows: +The naming convention for the Sphinx Needs UIDs of **all** elements shall be defined as follows: * It should not exceed 30 characters * It shall show a meaningful name @@ -63,9 +66,9 @@ Only for **process UIDs** the structural element is optional: * gd_temp__review * gd_req__req__structure -.. _branch_naming: +.. _naming_convention_branches: -Naming convention for git branches +Naming Convention for Git Branches ---------------------------------- In order to keep an overview which branch belongs to whom the branch diff --git a/docs/contribute/general/pullrequest.rst b/docs/contribute/general/pullrequest.rst new file mode 100644 index 00000000000..8a18008d494 --- /dev/null +++ b/docs/contribute/general/pullrequest.rst @@ -0,0 +1,85 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. _pull_request: + +Pull Request (PR) Guide +======================= + +.. document:: Pull Request Guide + :id: doc__pull_request_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + +A Pull Request (**PR**) is the **ONLY** way to contribute **CODE** to the *S-CORE* project. + +The figure below shows a simplified workflow for a PR. + +* The contributor (:need:`Contributor `) starts by creating a PR: `Creating a Pull Request (Github Docs) `_. +* Required reviewers will be automatically assigned based on the contributed content (via CODEOWNERS). +* If the content fulfills the review and acceptance criteria, a committer (:need:`Committer `) will approve the *PR* and thus it can be merged. + +.. figure:: _assets/pull_request_simple.drawio.svg + :width: 600 + :align: center + :alt: Simple *PR* based contribution workflow overview + + Simple *PR* based contribution workflow overview + +Content in general may contain features, requirements, architectural designs, modules, components, detailed designs, implementations and source code, tests, process descriptions, any documentations, guidelines, tutorials, tools, or infrastructure topics and more of the *S-CORE* project. In case of doubt or for any other input we strongly encourage to open a *GitHub Issue* (:need:`doc__issue_guide`) first. + +The *PR* should provide all required information of the new or changed content. Therefore the *S-CORE* project provides content specific templates, which the contributor (:need:`Contributor `) must use for their *PR* (ToDo link here to the templates overview). Templates may be *PR* templates, *GitHub Issue* templates and also additional document or work product templates. + +The content of any *PR* is the commit content and the description as well as the comments given in GitHub and is kept in a versioned repository, their revision history is the historical record of the PR. + +This historical record is available by the normal git commands for retrieving older revisions, and can also be browsed on GitHub. + + +Detailed *S-CORE* Pull Request Workflow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This chapter is only for optional read to understand the details for the Pull Request workflow defined in *S-CORE*. + +The figure below gives an overview about all the possible steps for a *PR* until it is either accepted or rejected. + +.. figure:: _assets/pull_request_standard.drawio.svg + :width: 100% + :align: center + :alt: Detailed *S-CORE* Pull request workflow overview + + Detailed *S-CORE* Pull request workflow overview + +Create a PR +^^^^^^^^^^^ + +The contributor (:need:`Contributor `) creates a PR. + +Reviewers will be automatically assigned (:need:`Committer `) based on the contributed content (ruleset as defined by the committers). In addition several checks for the contributed content (ToDo: Link to the description of the checks) will be started. + +Review and merge a PR +^^^^^^^^^^^^^^^^^^^^^ + +A *PR* is reviewed with all content that adds/modifies it. As long as a *PR* requires further work by the contributor (:need:`Contributor `), the *PR* is not approved and thus not merged and further changes are requested. Once the contributor (:need:`Contributor `) considers all review comments as resolved, :need:`Contributor ` can re-request a review. The committer (:need:`Committer `) reviews the *PR* content according the *S-CORE* review and acceptance criteria (ToDo link here to the criteria). +Further the contributor (:need:`Contributor `) must resolve found issues from the automated checks, if they do not pass. + +As long as the *PR* does not meet the defined criteria and the checks does not pass, it will not be approved. If it does not follow the required templates, based on the provided content or the templates are not filled out properly, the committer as reviewer (:need:`Committer `) will place the *PR* to the "Draft" state. + +It is then the responsibility of the contributor (:need:`Contributor `) to add the missing information and to re-start the contribution by placing the *PR* back for review. + +To change from "Draft" to "Open" see `Changing the stage of a pull request (Github Docs) `_. + +At any point the contributor (:need:`Contributor `) may decide not to continue with the PR, then the contributor (:need:`Contributor `) just closes the PR. diff --git a/docs/contribute/index.rst b/docs/contribute/index.rst index 4f6715c7ca8..8cca05ea832 100644 --- a/docs/contribute/index.rst +++ b/docs/contribute/index.rst @@ -12,42 +12,60 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. document:: Contribution - :id: doc__contribution_guideline +.. _contribution_guide: + +Contribution Guide +################## + + +.. document:: Contribution Guide + :id: doc__contribution_guide :status: valid :version: 1 - :safety: ASIL_B - :security: YES - :realizes: wp__sw_development_plan[version==1] + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + + +.. note:: + + There is no single path: you can fix a small bug, implement a requested feature, or simply start a + conversation with the community. The sections below describe the most common entry points. + + **Join Us in Building S-CORE** + + + - **Have a New Idea?** + Start by raising a new feature request to help expand the scope of our platform. -.. _contribute: + - **Ready to Code?** + Submit a contribution pitch for a specific feature request if you have a solution you'd like to share. + + - **Looking to Improve What's Already There?** + Contribute enhancements to existing implementations or get involved with one of our Feature Teams (FTs). + + We're excited to have you on board. Together, we can shape S-CORE into a platform that's not only innovative but also a joy to be a part of. -Contribute -########## How to get in contact with S-CORE ================================= If you want to get into contact with S-CORE, these are your primary entry points: -:Project Mailing List: score-dev@eclipse.org - -:Architectural Discussion: `#score-project-channel-public `__ - -| **General Information / Alignment regarding S-CORE as a basis for distributions & products:** -| Contact one of the project leads of S-CORE https://projects.eclipse.org/projects/automotive.score/who +- `Project/Technical Leads `__ +- `Platform Architects `__ How to get involved into S-CORE =============================== -The only way to influence S-CORE is TO CONTRIBUTE. Everybody can contribute - S-CORE is open. +The only way to influence S-CORE is **TO CONTRIBUTE**. Everybody can contribute - S-CORE is open. Active Contributions to the S-CORE project are the basis for getting involved. The S-CORE Project works according to the Eclipse Project Handbook and has named and elected project leads and committers (see `Eclipse Safe Open Vehicle Core `_). The direction of the S-CORE project is discussed and decided in the project lead circle, the technical direction is created and upfront in the tech lead circle. Meeting notes are transparent via the `S-CORE GitHub Discussions `_. -We aim to build a safety ready full stack architecture, where components fit to each other in automotive grade Software Quality and performance. To achieve this, we follow a strict :ref:`feature roadmap and architecture ` and a `rigid software development process `_ (currently under development). +We aim to build a safety ready full stack architecture, where components fit to each other in automotive grade Software Quality and performance. To achieve this, we follow a strict :ref:`feature roadmap and architecture ` and a `rigid software development process `_ (currently under development). -Contributions to the S-CORE project must therefore follow the technical direction of the project and the S-CORE architecture. For an introduction on how to contribute, please check out our :need:`Contribution Guideline `. +Contributions to the S-CORE project must therefore follow the technical direction of the project and the S-CORE architecture. Based on successful code contributions to the S-CORE roadmap, further steps in involvement (like becoming a committer) will be handled according to the rules of the Eclipse Foundation Project Handbook. We value real code based collaboration and will judge new potential contributors and committers mainly on the validity of their work. Active and sustaining contributions are the basis for the ability to shape S-CORE. @@ -55,22 +73,159 @@ Based on successful code contributions to the S-CORE roadmap, further steps in i How is S-CORE organized ======================= -Eclipse S-CORE is an open source project, so everyone is welcome to contribute. Since we are organized within the Eclipse Foundation, you must have an Eclipse Foundation account to participate - please see :ref:`contribution_attribution` for details. +Eclipse S-CORE is an open source project, so everyone is welcome to contribute. Since we are organized within the Eclipse Foundation, you must have an Eclipse Foundation account to participate - please see :ref:`contribution_attribution_guide` for details. The project is structured into various :ref:`communities `, which focus on cross-cutting topics and :ref:`feature teams ` responsible for the implementation of specific functionalities. Their meetings are public; feel free to join or review the minutes via our `GitHub Discussions `_. -Additionally, two :ref:`steering committees `, the Technical Lead Circle and the Project Lead Circle, oversee the overall steering and planning of S-CORE. +Additionally, :ref:`steering committees `, the Technical / Project Lead Circle, oversee the overall steering and planning of S-CORE. For further details on our project structure and planning, please refer to the :need:`Project Management Plan `. +How to Set Up your Environment +=============================== + +Find the necessary information for setting up your :ref:`Development Environment ` ready. + +How to become a Contributor +=========================== + +#. **Read the Introduction** — Work through the complete :ref:`Introduction ` from top to bottom to + build a solid foundation of S-CORE knowledge. + +#. **Start the S-CORE test application "scrample"** — Run `Scrample `_ locally to experience the + full development loop (build, test, CI/CD) on a real, self-contained project. + +#. **Implement an open issue and create a pull request** — Pick up an open issue in any S-CORE + module repository, implement your fix or improvement, and go through the pull-request review + process. + +#. **Get in touch with the project leads** — Once you have proven basic S-CORE knowledge, + contact the project leads. If your capability and planned capacity are substantial, you may + qualify for a **Buddy Program**: a dedicated project lead guides you (or your team) + personally until your first task is assigned, and stays available for potential long-term + support on request. + +#. **Become an Eclipse S-CORE Contributor** - Steps to be done for ensuring contributions are correctly attributed to organizations in the **Eclipse S-CORE** project: :ref:`Contribution Attribution `. + + + + +How we Work +=========== + +At S-CORE, we believe that every contribution makes our platform stronger. +Whether you're a seasoned developer or just starting out in open source, your ideas and work are warmly welcomed. +We follow a structured yet flexible process rooted in our change management principles and overall lifecycle concept. +For more details on our processes, feel free to explore our `Life Cycle Concept `_ +and the :need:`doc__platform_change_management_plan`. + +Issues and Pull Requests +------------------------ + +All activities shall be planned and documented with the help of :ref:`Issues ` and :ref:`Pull Requests ` + +Feature Requests +---------------- + +Feature requests are at the heart of our evolution. They describe the intended functionality of the S-CORE platform and serve as a collaborative starting point where maintainers and contributors align on new ideas. These requests not only define the motivation and requirements but also shape the technical roadmap for future developments. We invite you to check out all current feature requests on our +`Feature Request Board `_. + +New Feature and major Feature Modification requests go through the :ref:`Feature Request Guideline `, where an Architecture Community Shepherd guides the proposal to a Final Comment Period before it's decided. Component-level and single-Feature-Team changes are handled directly by the responsible team, as described in the :need:`doc__platform_change_management_plan`. + +From Vision to Reality: Calling for Contributions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once a feature request is embraced by the community, it becomes a targeted opportunity for innovation. At this stage, we issue a call for contributions, inviting anyone with a solution - whether in-house or open source - to submit a contribution pitch. We ask that your pitch focuses on the technical aspects and clearly outlines how you plan to meet the feature goals (and not a sales pitch 😉). Don't worry if you're still polishing your idea; as long as the source code is already available (or will be within about three weeks with a publicly committed roadmap), you're ready to join in the conversation. + +How We Evaluate Contributions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We work together with contributors to review each pitch based on several criteria: + +- **Alignment with the Feature Request:** + Your solution should fully or partially meet the specified functionality, with room for further enhancements as needed. + +- **Availability of the Source Code:** + We value open source solutions under an OSI-compliant license. If your code isn't public yet, a clear plan to open source it is just as welcome. + +- **Technical Maturity:** + We look at whether your implementation is built in a safety-certifiable subset of C++ or Rust, or if it might need some refinements. + +- **Initial Impact Assessment:** + Please state the assumed impact on other systems. It makes a significant difference if your solution requires other components to refactor versus extending functionality through existing APIs. + +- **Supporting Artifacts:** + To ensure everything is in order for certification and further development, we check that all necessary artifacts are available or that there's a plan to make them available. + +For a deeper dive into our evaluation process, you can review the notes from our very first call for contributions on our +`Architecture Community F2F Workshop [2025-02-11 - 2025-02-13] `_. + +Once a contribution is selected, it not only implements a new feature but also helps guide the ongoing evolution of S-CORE. + +**Replacement of existing functionality** +In S-CORE we aim for having only one solution for a specific problem. If you have an idea for improving an existing feature, you're welcome to pitch a replacement implementation. Just be sure to highlight clearly the benefits over the current solution. + + + + +What rules to follow +==================== + +.. needtable:: Parts of SW Development Plan + :style: table + :columns: title;id;status + :colwidths: 45,45,10 + :sort: docname + :filter: "wp__sw_development_plan" in realizes + + +Where to find more trainings +============================ + +.. needtable:: Training Documents + :style: table + :columns: title;id;status + :colwidths: 45,45,10 + :sort: docname + :filter: "wp__training_path" in realizes + + + + .. toctree:: :hidden: :maxdepth: 2 - contribution_request/index - general/index - documentation/index - development/index - ci/index - fork/index + contribute_new_module/index + + documentation/docs-as-code_guide + documentation/publishing-gh-pages + + development/api_guideline + development/setup_dev_environment + development/traceability_guidelines + + development/cpp/cpp_code_analysis + development/cpp/cpp_coding_guidelines + development/cpp/cpp_misra_rules + + development/fork/index + + + development/rust/rust_api_design + development/rust/rust_coding_guidelines + + development/python/python_coding_guidelines + + feature_request/feature_request + + general/naming_conventions + general/git + general/issue + general/pullrequest + + general/folder_structure_convention + general/feature_flags + general/contribution_attribution_guide + general/module_release_guide diff --git a/docs/design_decisions/DR-008-int.rst b/docs/design_decisions/DR-008-int.rst index 21febecfc99..18bf4721640 100644 --- a/docs/design_decisions/DR-008-int.rst +++ b/docs/design_decisions/DR-008-int.rst @@ -114,7 +114,7 @@ Module-side activities required for an S-CORE release integration: * Automated quality checks (static analysis, unit tests, CITs) using the tooling and versions agreed centrally and tracked in the S-CORE tools evaluation list — see - `score_tools_evaluation_list `_ + `tools_evaluation_list `_ (single source of truth for tool versions, classification, and qualification reports). * Manual quality checks per the S-CORE quality workflow, including `process conformance checks `_, diff --git a/docs/design_decisions/index.rst b/docs/design_decisions/index.rst index 166b34e8447..a02e7cf5329 100644 --- a/docs/design_decisions/index.rst +++ b/docs/design_decisions/index.rst @@ -12,8 +12,10 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Decision Records -================ +.. _platform_design_decisions: + +Platform Design Decisions +========================= Strategy ~~~~~~~~ diff --git a/docs/index.rst b/docs/index.rst index 25172bb3dab..ff4ebdaac1c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,9 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +Platform Handbook +================= + .. document:: Handbook :id: doc__platform_handbook :status: valid @@ -25,9 +28,6 @@
-S-CORE Platform Documentation -============================= - .. raw:: html
@@ -45,8 +45,8 @@ S-CORE Platform Documentation -Introduction ------------- +What it is about +---------------- .. grid:: 1 :class-container: score-grid score-grid-intro @@ -67,53 +67,53 @@ Introduction Responsibility for ASPICE, ISO 21434 (cybersecurity), and ISO 26262 (functional safety) compliance of the final system always remains with the series project. -Get started with S-CORE ------------------------ +Getting Started +--------------- .. grid:: 3 :gutter: 3 :class-container: score-grid score-grid-getstarted .. grid-item-card:: - :link: users_guide/project_basics/index + :link: introduction/index :link-type: doc :text-align: center :octicon:`book;1.5em` - Overview + Introduction ^^^ - Explore the S-CORE platform structure, technology stack and software - architecture. Understand the core concepts before you start building. + Explore the Platform Structure, Technology, Architecture Meta Model. + Understand the Core Concepts before you start. .. grid-item-card:: - :link: users_guide/building_simple_application/index + :link: contribute/index :link-type: doc :text-align: center :octicon:`code-square;1.5em` - Contribute own module + Contribution Guideline ^^^ Follow a step-by-step guide to build and integrate your first S-CORE module — from source code to CI/CD and doc .. grid-item-card:: - :link: users_guide/whats_next/index + :link: users_guide/index :link-type: doc :text-align: center :octicon:`rocket;1.5em` - What's next? + User's Guide ^^^ - Check how you can start being productive immediately + Check how you can start building Applications on top of S-CORE. Platform Architecture --------------------- -.. grid:: 1 1 3 3 +.. grid:: 1 1 4 4 :class-container: score-grid score-grid-artifacts .. grid-item-card:: @@ -147,25 +147,42 @@ Platform Architecture ^^^ Understand the main goals of the S-CORE platform by reading the :ref:`Stakeholder requirements ` and - :ref:`SW-platform Assumptions `. + :ref:`Platform Assumptions `. + + .. grid-item-card:: + + :octicon:`graph;1.5em` + Platform Status + ^^^ + Inform yourself about the status of the Platform ..... [tbd] -Project structure and processes +Project Structure and Processes ------------------------------- .. grid:: 1 1 3 3 :class-container: score-grid score-grid-processes + .. grid-item-card:: + + :octicon:`organization;1.5em` + + Platform Management + ^^^^^^^^^^^^^^^^^^^ + Read about our project and organization structure in the + `Project Management Plan `_. + And learn how we deal with :ref:`Safety Plan Platform` or care about :ref:`Software Verification Plan `. + .. grid-item-card:: :octicon:`workflow;1.5em` Process ^^^ - Check the `main idea `_ - and `concepts `_ - to understand the reasons behind our software development process. + Check the `Main Ideas `_ + and `Concepts `_ + of the Process to understand the reasons behind our software development process. .. grid-item-card:: @@ -173,18 +190,8 @@ Project structure and processes Process Areas ^^^ - Check the detailed `documentation of every process area `_, - which contains requirements, guidances, workflows and a list of work products for every process area in S-CORE. - - .. grid-item-card:: - - :octicon:`organization;1.5em` - - Platform Management Plan (PMP) - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Read about our project and organization structure in the - `Project Handbook `_. - And learn how we deal with :ref:`Platform Safety Plan ` or care about :ref:`Software Verification Plan `. + Check the detailed `Documentation of every Process Area `_, + which contains requirements, guidances, workflows and a list of work products for every process. Reference Integration --------------------- @@ -194,12 +201,12 @@ Reference Integration .. grid-item-card:: - :octicon:`git-merge;1.5em` + :octicon:`iterations;1.5em` - Integration Baseline + Reference Integration Process ^^^ - Discover how all platform modules are continuously built and tested together - to form the authoritative `S-CORE integration baseline `_. + Follow the `Integration Process `_ + to understand how Platform Modules are integrated together. .. grid-item-card:: :link: https://eclipse-score.github.io/reference_integration/main/s_core_v_1/releases/releases.html @@ -207,23 +214,22 @@ Reference Integration :octicon:`package-dependents;1.5em` - Releases Overview + Reference Releases ^^^ Browse the `release notes `_ and see the current state of the platform. .. grid-item-card:: - :octicon:`iterations;1.5em` + :octicon:`pivot-column;1.5em` - Integration Process + Integration Status ^^^ - Follow the `integration process `_ - to understand how platform modules are integrated together. Consult the `cross-repo metrics report `_ and the `integration status `_ for details. + Infrastructure and Tooling -------------------------- @@ -234,35 +240,36 @@ Infrastructure and Tooling :link: https://eclipse-score.github.io/infrastructure/dev/index.html :link-type: url - :octicon:`tools;1.5em` + :octicon:`gear;1.5em` - Documentation + Infrastructure Landscape ^^^ Get to know the S-CORE tool stack, testing and CI infrastructure. Read the `infra & tooling docs `_. + .. grid-item-card:: + + :octicon:`tools;1.5em` + + Toolchains + ^^^ + S-CORE provides hermetic Bazel toolchains for building its modules. + Explore the `C++ toolchains `_ + and the `Rust toolchains `_ used across the platform. + .. grid-item-card:: :link: https://eclipse-score.github.io/infrastructure/dev/explanation/index.html :link-type: url - :octicon:`mark-github;1.5em` + :octicon:`graph;1.5em` - Status + Infrastructure Status ^^^ Get insights into the current state of the S-CORE tooling and infrastructure. Check the status `overview `_ to see how the build and CI components are set up and maintained. - .. grid-item-card:: - - :octicon:`tools;1.5em` - - Toolchains - ^^^ - S-CORE provides hermetic Bazel toolchains for building its modules. - Explore the `C++ toolchains `_ - and the `Rust toolchains `_ used across the platform. .. raw:: html @@ -303,27 +310,25 @@ Infrastructure and Tooling :maxdepth: 1 :hidden: - users_guide/index + introduction/index + contribute/index architecture/index features/index + users_guide/index requirements/index - contribute/index - Quality - Releases - Tools - PMP - Safety - Eclipse + score_releases/index + quality/qms_report + + score_tools/index + platform_management_plan/index + safety/index design_decisions/index + modules/index + + Eclipse -.. toctree:: - :maxdepth: 1 - :hidden: - introduction/index - users_guide/index - modules/index .. raw:: html diff --git a/docs/introduction/_assets/architecture_overview.drawio.svg b/docs/introduction/_assets/architecture_overview.drawio.svg new file mode 100644 index 00000000000..d1b13cba2c5 --- /dev/null +++ b/docs/introduction/_assets/architecture_overview.drawio.svg @@ -0,0 +1,371 @@ + + + + + + + + + + + +
+
+
+ Base Libraries +
+
+
+ + + Base Libraries + + + + + + + + + + + +
+
+
+ Development Environment +
+
+
+ + + Development Environment + + + + + + + + + + + +
+
+
+ Platform API (native APIs for Rust and C++) +
+
+
+ + + Platform API (native APIs for Rust and C++) + + + + + + + + + + + +
+
+
+ System Services +
+
+
+ + + System Services + + + + + + + + + + + +
+
+
+ Communication +
+
+
+ + + Communication + + + + + + + + + + + +
+
+
+ Operating System +
+
+
+ + + Operating System + + + + + + + + + + + +
+
+
+ Hypervisor / Hardware +
+
+
+ + + Hypervisor / Hardware + + + + + + + + + + + +
+
+
+ Architecture Overview +
+
+
+ + + Architecture Overview + + + + + + + + + + + +
+
+
+ ADAS +
+
+
+ + + ADAS + + + + + + + + + + + +
+
+
+ Telematics and Connectivity +
+
+
+ + + Telematics and Connectivity + + + + + + + + + + + +
+
+
+ ... +
+
+
+ + + ... + + + + + + + + + + + +
+
+
+ Non-converged system, e.g. IVI with Android +
+
+
+ + + Non-converged system,... + + + + + + + + + + + +
+
+
+ Apps +
+
+
+ + + Apps + + + + + + + + + + + +
+
+
+ API +
+
+
+ + + API + + + + + + + + + + + +
+
+
+ Platform +
+
+
+ + + Platform + + + + + + + + + + + +
+
+
+ OS +
+
+
+ + + OS + + + + + + + + + + + +
+
+
+ Artificial Intelligence +
+
+
+ + + Artificial Intelligence + + + + + + + + + + Text is not SVG - cannot display + + + + diff --git a/docs/users_guide/_assets/generated_doc_in_score_github.png b/docs/introduction/_assets/generated_doc_in_score_github.png similarity index 100% rename from docs/users_guide/_assets/generated_doc_in_score_github.png rename to docs/introduction/_assets/generated_doc_in_score_github.png diff --git a/docs/users_guide/_assets/module_deps.drawio.svg b/docs/introduction/_assets/module_deps.drawio.svg similarity index 100% rename from docs/users_guide/_assets/module_deps.drawio.svg rename to docs/introduction/_assets/module_deps.drawio.svg diff --git a/docs/users_guide/_assets/process_areas.png b/docs/introduction/_assets/process_areas.png similarity index 100% rename from docs/users_guide/_assets/process_areas.png rename to docs/introduction/_assets/process_areas.png diff --git a/docs/users_guide/_assets/release_integration_concept.drawio.svg b/docs/introduction/_assets/release_integration_concept.drawio.svg similarity index 100% rename from docs/users_guide/_assets/release_integration_concept.drawio.svg rename to docs/introduction/_assets/release_integration_concept.drawio.svg diff --git a/docs/users_guide/_assets/release_verification.png b/docs/introduction/_assets/release_verification.png similarity index 100% rename from docs/users_guide/_assets/release_verification.png rename to docs/introduction/_assets/release_verification.png diff --git a/docs/introduction/_assets/score_architecture_core_stack_target_picture.png b/docs/introduction/_assets/score_architecture_core_stack_target_picture.png deleted file mode 100644 index 18ee8054cae..00000000000 Binary files a/docs/introduction/_assets/score_architecture_core_stack_target_picture.png and /dev/null differ diff --git a/docs/introduction/_assets/score_architecture_high_level_overview.png b/docs/introduction/_assets/score_architecture_high_level_overview.png deleted file mode 100644 index 5210eb0c33a..00000000000 Binary files a/docs/introduction/_assets/score_architecture_high_level_overview.png and /dev/null differ diff --git a/docs/introduction/_assets/score_roadmap.drawio.svg b/docs/introduction/_assets/score_roadmap.drawio.svg deleted file mode 100644 index 86472f76f29..00000000000 --- a/docs/introduction/_assets/score_roadmap.drawio.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
Project set-up
Release v0.1
Definition v1.0

Release v0.5
Release v1.0
Dec, 2024
Beginning of 2025
Mid of 2025
End of 2025
2026
MVP Phase
Alignment Phase
Development Phase
Product Versions based on S-CORE Release 1.x
Release v1.x
Series Stability & Evolution Phase
2030
  • Creation of S-CORE project in Eclipse SDV
  • Initial set-up of toolchain and infrastructure
  • ASIL Software Development process is defined
  • Proof of automotive grade "Qualification ability" (Safety Audit)
  • Definition of platform architecture and feature requirements for S-CORE v1.0
  • Provides first public implementation of the most important modules, e.g. IPC, that can be used to build first distributions
  • S-CORE v1.0 release should contain all common modules of an autonomous driving platform
 diff --git a/docs/users_guide/_assets/score_tooling.drawio.svg b/docs/introduction/_assets/score_tooling.drawio.svg similarity index 100% rename from docs/users_guide/_assets/score_tooling.drawio.svg rename to docs/introduction/_assets/score_tooling.drawio.svg diff --git a/docs/users_guide/project_basics/software_architecture_overview.rst b/docs/introduction/architecture_introduction.rst similarity index 64% rename from docs/users_guide/project_basics/software_architecture_overview.rst rename to docs/introduction/architecture_introduction.rst index ddf84bdaf97..a082128a90c 100644 --- a/docs/users_guide/project_basics/software_architecture_overview.rst +++ b/docs/introduction/architecture_introduction.rst @@ -12,26 +12,40 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Software Architecture Overview -================================ +.. _architecture_introduction: -Please note that the Eclipse S-CORE´s software architecture is continuously refined and will evolve in future releases. +Architecture Introduction +========================= -.. image:: ../_assets/architecture_0_6.drawio.svg + +.. document:: Architecture introduction + :id: doc__architecture_introduction + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + + +.. note:: + Have a look on the current :ref:`Platform Architektur `. + +.. image:: _assets/architecture_overview.drawio.svg :width: 1000 :alt: Architecture overview :align: center -| +.. note:: + The corresponding Architectural Elements are described in :need:`Building Block Concept `. -Eclipse S-CORE has a `software architecture community `_ +Eclipse S-CORE has a `Software Architecture Community `_ **responsible for maintaining and evolving the architecture**. -Structural changes and new functionality are proposed through a **FEP**. -All **past feature requests** are documented in the corresponding +Structural changes and new functionality are proposed through a **Feature and Enhancement Proposal (FEP)** . +All past **Feature Requests** are documented in the corresponding `Feature Requests / Modification `_ GitHub project. -**Submitting a FEP** is described in the :ref:`Feature & Enhancement Proposal (FEP) `. +**Submitting a FEP** is described in the :ref:`Feature & Enhancement Proposal Guideline `. Participation in the architecture process is encouraged. The **software architecture community regularly organizes workshops** where contributors can: diff --git a/docs/introduction/index.rst b/docs/introduction/index.rst index 8e5d5bba106..d3d1a7f84ae 100644 --- a/docs/introduction/index.rst +++ b/docs/introduction/index.rst @@ -1,6 +1,6 @@ .. # ******************************************************************************* - # Copyright (c) 2024 Contributors to the Eclipse Foundation + # Copyright (c) 2026 Contributors to the Eclipse Foundation # # See the NOTICE file(s) distributed with this work for additional # information regarding copyright ownership. @@ -12,19 +12,79 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Eclipse S-CORE (Eclipse Safe Open Vehicle Core) -############################################### +.. _introduction: -.. raw:: html +Introduction +============ - - - +.. document:: Introduction + :id: doc__introduction + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] +This section gives you the conceptual foundation for working with S-CORE. +Before diving into code or contribution workflows, read through these pages +to understand how the platform is structured and what drives its design: -

- If you are not redirected automatically, follow this link to Eclipse S-CORE Introduction page. -

+* **Technologies** (:ref:`technology_introduction`) — the toolchain and infrastructure that power S-CORE, from + build system to documentation and CI/CD. +* **Architecture** (:ref:`architecture_introduction`) — the high-level decomposition of the platform into + features and modules, and the principles behind it. +* **Module Structure** (:ref:`module_introduction`) — how an individual S-CORE module is laid out on disk, + what each folder contains, and the conventions every module follows. +* **Integration Process** (:ref:`integration_introduction`) — how modules are continuously built, tested, and + assembled into the reference integration. + +.. grid:: 3 + :gutter: 3 + :class-container: score-grid score-grid-getstarted + + .. grid-item-card:: + :link: ../contribute/index + :link-type: doc + :text-align: center + + :octicon:`code-square;1.5em` + + Contribution Guideline + ^^^ + Follow a step-by-step guide to build and integrate your first S-CORE + module — from source code to CI/CD and doc + + .. grid-item-card:: + :link: ../users_guide/index + :link-type: doc + :text-align: center + + :octicon:`rocket;1.5em` + + User`s Guide + ^^^ + Check how you can start building Applications on top of S-CORE. + + .. grid-item-card:: + :link: useful_links + :link-type: doc + :text-align: center + + :octicon:`link;1.5em` + + Useful links + ^^^ + A collection of useful links for getting more information. + + +.. toctree:: + :maxdepth: 1 + :hidden: + :glob: + + version_control_introduction + technology_introduction + architecture_introduction + module_introduction.rst + integration_introduction.rst + useful_links.rst diff --git a/docs/users_guide/project_basics/integration_process.rst b/docs/introduction/integration_introduction.rst similarity index 93% rename from docs/users_guide/project_basics/integration_process.rst rename to docs/introduction/integration_introduction.rst index f06d85d586c..c3ed925b226 100644 --- a/docs/users_guide/project_basics/integration_process.rst +++ b/docs/introduction/integration_introduction.rst @@ -11,17 +11,26 @@ # # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. _integration_process: -Integration process -==================== +.. _integration_introduction: + +Integration Introduction +======================== + +.. document:: Integration Introduction + :id: doc__integration_introduction + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] The integration process is a core activity within Eclipse S-CORE and is still evolving as the project gathers experience. Several discussions and concepts have shaped the current approach. A detailed description is available in the following `decision record `_. This chapter provide a high-level overview of how integration works in Eclipse S-CORE. -.. image:: ../_assets/release_integration_concept.drawio.svg +.. image:: _assets/release_integration_concept.drawio.svg :alt: release_integration_concept :align: center diff --git a/docs/users_guide/project_basics/module_structure_overview.rst b/docs/introduction/module_introduction.rst similarity index 94% rename from docs/users_guide/project_basics/module_structure_overview.rst rename to docs/introduction/module_introduction.rst index 18258a6a2e8..2346eadbbb7 100644 --- a/docs/users_guide/project_basics/module_structure_overview.rst +++ b/docs/introduction/module_introduction.rst @@ -12,15 +12,26 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Module Structure Overview -========================== +.. _module_introduction: -As described in the :ref:`Technology Overview ` chapter, Eclipse S-CORE consists of multiple bazel modules, +Module Introduction +=================== + + +.. document:: Module Introduction + :id: doc__module_introduction + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + +As described in :ref:`Technology Introduction `, Eclipse S-CORE consists of multiple bazel modules, typically stored in separate repositories. Most modules reside in the `Eclipse S-CORE GitHub organization `_, while some originate from other Eclipse projects and are reused here. This chapter introduces the most important bazel modules and repositories in Eclipse S-CORE GitHub organization. -.. image:: ../_assets/module_deps.drawio.svg +.. image:: _assets/module_deps.drawio.svg :alt: Overview of the most important S-CORE modules an application should reference :align: center @@ -47,7 +58,7 @@ Process Description We automatically generate for every repository html documentation from rst files. You can easily open it as shown at the picture below. -.. image:: ../_assets/generated_doc_in_score_github.png +.. image:: _assets/generated_doc_in_score_github.png :alt: Generated Doc in GitHub :width: 500 :align: center @@ -59,7 +70,7 @@ The process repository describes the Eclipse S-CORE software development process - how work products such as requirements and architecture must be specified - PMP describes, how the processes are deployed within S-CORE `Project Management Plan `_ -.. image:: ../_assets/process_areas.png +.. image:: _assets/process_areas.png :alt: Process areas :width: 500 :align: center diff --git a/docs/users_guide/project_basics/technology_overview.rst b/docs/introduction/technology_introduction.rst similarity index 93% rename from docs/users_guide/project_basics/technology_overview.rst rename to docs/introduction/technology_introduction.rst index fb72a7c236e..1819e4fcd49 100644 --- a/docs/users_guide/project_basics/technology_overview.rst +++ b/docs/introduction/technology_introduction.rst @@ -12,10 +12,18 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. _technology_overview: +.. _technology_introduction: -Overview of technologies -=========================== +Technology Introduction +======================= + +.. document:: Technology Introduction + :id: doc__technology_introduction + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] S-CORE Tooling ---------------- @@ -29,7 +37,7 @@ of each tool and process step. This chapter provides a general overview of the S-CORE toolchain. For a deeper technical dive, refer to the `Infrastructure Community page `_. -.. image:: ../_assets/score_tooling.drawio.svg +.. image:: _assets/score_tooling.drawio.svg :alt: Score tooling :align: center @@ -59,7 +67,7 @@ However, modularity introduces organizational and technical challenges: for more details regarding S-CORE´s organizational structure. Technical integration and dependency management require clear processes. -Eclipse S-CORE´s approach for technical integration is described in the :ref:`integration process `. +Eclipse S-CORE´s approach for technical integration is described in the :ref:`Integration Introduction `. - However, a basic support for handling dependencies among bazel modules is provided by the build system. For publishing of official modules versions, a mechanism called `bazel registry `_ @@ -77,7 +85,7 @@ The CI/CD pipeline follows modern industry practices. It is based on GitHub infrastructure and uses `GitHub actions `_ for automation and for executing all CI/CD checks. -.. image:: ../_assets/release_verification.png +.. image:: _assets/release_verification.png :alt: release_verification :width: 400 :align: center diff --git a/docs/users_guide/useful_links.rst b/docs/introduction/useful_links.rst similarity index 87% rename from docs/users_guide/useful_links.rst rename to docs/introduction/useful_links.rst index 4ff41e6d773..71082e11e0e 100644 --- a/docs/users_guide/useful_links.rst +++ b/docs/introduction/useful_links.rst @@ -16,11 +16,22 @@ Useful Links ============ +.. document:: Useful Links + :id: doc__useful_links + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + + + + Community & Governance ---------------------- -- `Eclipse SDV Slack `_ — join the community chat to ask questions and connect with contributors -- `Eclipse S-CORE Project Leads `_ — official list of project leads and committers +- `Eclipse SDV Slack `_ — join the community chat to ask questions and connect with contributors +- `Eclipse S-CORE Members `_ — official list of project leads and committers - `Architecture Community Discussions `_ — GitHub discussion board for architecture topics - `Feature Requests & Modifications Board `_ — overview of open feature requests and planned changes - `Eclipse Community Calendar `_ — public calendar with Feature Team and Community meetings @@ -43,8 +54,8 @@ Project Documentation - `S-CORE Documentation `_ — rendered project documentation (requirements, architecture, safety) - `Decision Records `_ — architectural and process decision records for the S-CORE project - `Platform Management Plan `_ — project governance and management plan -- `Contribution Guidelines `_ — step-by-step guide for common contribution workflows -- `Contribution Attribution `_ — how to properly attribute contributions +- `Contribution Guidelines `_ — step-by-step guide for common contribution workflows +- `Contribution Attribution `_ — how to properly attribute contributions - `Process Description Documentation `_ — general concepts of the S-CORE process - `Verification Concept `_ — verification approach and testing strategy - `Docs-as-Code How-To `_ — guide for writing and generating documentation diff --git a/docs/contribute/development/rust/index.rst b/docs/introduction/version_control_introduction.rst similarity index 56% rename from docs/contribute/development/rust/index.rst rename to docs/introduction/version_control_introduction.rst index d230b8671e3..19a93378aa7 100644 --- a/docs/contribute/development/rust/index.rst +++ b/docs/introduction/version_control_introduction.rst @@ -1,6 +1,6 @@ .. # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation + # Copyright (c) 2026 Contributors to the Eclipse Foundation # # See the NOTICE file(s) distributed with this work for additional # information regarding copyright ownership. @@ -12,17 +12,18 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Rust -#### -For safety- and security-related Rust development, S-CORE uses -adopted safety- and cybersecurity-oriented Rust guidance as a -baseline reference for recommended practices, in addition to the -project-specific guidance linked below. +.. _version_control_introduction: -.. toctree:: - :maxdepth: 1 +Version Control Introduction +============================ - certification/index - coding_guidelines - rust_api_design +.. document:: Version Control Introduction + :id: doc__version_control_introduction + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] + +GitHub is used as general Version Control Tool. (see https://docs.github.com/) diff --git a/docs/modules/communication/docs/safety_mgt/module_safety_plan.rst b/docs/modules/communication/docs/safety_mgt/module_safety_plan.rst index c7f3f65b962..5ff75399d31 100644 --- a/docs/modules/communication/docs/safety_mgt/module_safety_plan.rst +++ b/docs/modules/communication/docs/safety_mgt/module_safety_plan.rst @@ -28,7 +28,7 @@ Module Safety Plan Functional Safety Management Context ==================================== -This Safety Plan adds to the :need:`doc__score_platform_safety_plan` all the module development relevant work products needed for ISO 26262 conformity. +This Safety Plan adds to the :need:`doc__safety_plan_platform` all the module development relevant work products needed for ISO 26262 conformity. Functional Safety Management Scope ================================== @@ -54,7 +54,7 @@ Functional Safety Management Roles Tailoring ========= -Additional to the tailoring in the SW platform project as defined in the :need:`doc__score_platform_safety_plan` we define here the additional tailoring on module level. +Additional to the tailoring in the SW platform project as defined in the :need:`doc__safety_plan_platform` we define here the additional tailoring on module level. - Excluded for this module are additionally the following work products (and their related requirements): diff --git a/docs/modules/feo/docs/safety_mgt/module_safety_plan.rst b/docs/modules/feo/docs/safety_mgt/module_safety_plan.rst index ccbb6653331..4b709195e75 100644 --- a/docs/modules/feo/docs/safety_mgt/module_safety_plan.rst +++ b/docs/modules/feo/docs/safety_mgt/module_safety_plan.rst @@ -28,7 +28,7 @@ FEO Module Safety Plan Functional Safety Management Context ==================================== -This Safety Plan adds to the :need:`doc__score_platform_safety_plan` all the module development relevant work products needed for ISO 26262 conformity. +This Safety Plan adds to the :need:`doc__safety_plan_platform` all the module development relevant work products needed for ISO 26262 conformity. Functional Safety Management Scope ================================== @@ -54,7 +54,7 @@ Functional Safety Management Roles Tailoring ========= -Additional to the tailoring in the SW platform project as defined in the :need:`doc__score_platform_safety_plan` we define here the additional tailoring on module level. +Additional to the tailoring in the SW platform project as defined in the :need:`doc__safety_plan_platform` we define here the additional tailoring on module level. - Excluded for this module are additionally the following work products (and their related requirements): - No work products excluded diff --git a/docs/platform_management_plan/change_management.rst b/docs/platform_management_plan/change_management.rst index e52463670bd..4a6408509c1 100644 --- a/docs/platform_management_plan/change_management.rst +++ b/docs/platform_management_plan/change_management.rst @@ -56,7 +56,7 @@ Change Request Execution ^^^^^^^^^^^^^^^^^^^^^^^^ Contributions in general to the **S-CORE** project are described here -(compare :need:`doc__contr_guideline`). +(compare :need:`doc__contribution_guide`). A Change Request is a specific contribution, and it is the **ONLY** way to contribute new features/components or to modify the scope of existing features/components in the **S-CORE** @@ -65,10 +65,10 @@ project. Change Request Infrastructure and Types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:need:`GitHub Issues (ISSUE) ` are used for managing Change Requests. +:need:`GitHub Issues (ISSUE) ` are used for managing Change Requests. The tool is used to create, analyze, implement and monitor Change Requests within **S-CORE**. -:need:`GitHub Pull Requests (PR) ` are used for the documentation and +:need:`GitHub Pull Requests (PR) ` are used for the documentation and implementation of Change Requests. The tool is used to document, implement and verify Change Requests within **S-CORE**. diff --git a/docs/platform_management_plan/problem_resolution.rst b/docs/platform_management_plan/problem_resolution.rst index 31607ac0ac0..bf7ba4b4cee 100644 --- a/docs/platform_management_plan/problem_resolution.rst +++ b/docs/platform_management_plan/problem_resolution.rst @@ -51,7 +51,7 @@ Problem Resolution Execution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Contributions in general to the **S-CORE** project are described here -(compare :need:`doc__contr_guideline`). +(compare :need:`doc__contribution_guide`). A Problem Resolution is a specific contribution, and it is the **ONLY** way to report problems in the **S-CORE** project. @@ -59,7 +59,7 @@ it is the **ONLY** way to report problems in the **S-CORE** project. Problem Resolution Infrastructure ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:need:`GitHub Issues (ISSUE) ` are used for managing problems and their +:need:`GitHub Issues (ISSUE) ` are used for managing problems and their potential resolution. The tool is used to create, analyze, initiate and to monitor the problem reported within **S-CORE**. diff --git a/docs/platform_management_plan/safety_management.rst b/docs/platform_management_plan/safety_management.rst index dac594861a5..785dc86d946 100644 --- a/docs/platform_management_plan/safety_management.rst +++ b/docs/platform_management_plan/safety_management.rst @@ -12,8 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. document:: Platform Safety Plan - :id: doc__score_platform_safety_plan +.. document:: Safety Plan Platform + :id: doc__safety_plan_platform :status: draft :version: 1 :safety: ASIL_B @@ -22,7 +22,7 @@ :tags: platform_management -.. _score_platform_safety_plan: +.. _safety_plan_platform: Safety management / Platform Safety Plan ---------------------------------------- @@ -407,8 +407,8 @@ Functional Safety/Security Management SW Platform Work Products * - :need:`wp__tool_verification_report` - :ndf:`copy('status', need_id='wf__tool_create_tool_verification_report')` - - :need:`doc__tool_evaluation_list` - - :ndf:`copy('status', need_id='doc__tool_evaluation_list')` + - :need:`doc__tools_evaluation_list` + - :ndf:`copy('status', need_id='doc__tools_evaluation_list')` Functional Safety Specific SW Platform Work Products @@ -434,18 +434,18 @@ Functional Safety Specific SW Platform Work Products * - :need:`wp__fdr_reports` (platform Safety Plan) - :ndf:`copy('status', need_id='wf__p_formal_rv')` - - :need:`doc__score_platform_safety_plan_fdr` - - :ndf:`copy('status', need_id='doc__score_platform_safety_plan_fdr')` + - :need:`doc__safety_plan_fdr_platform` + - :ndf:`copy('status', need_id='doc__safety_plan_fdr_platform')` * - :need:`wp__fdr_reports` (platform Safety Package) - :ndf:`copy('status', need_id='wf__p_formal_rv')` - - :need:`doc__score_platform_safety_package_fdr` - - :ndf:`copy('status', need_id='doc__score_platform_safety_package_fdr')` + - :need:`doc__safety_package_fdr_platform` + - :ndf:`copy('status', need_id='doc__safety_package_fdr_platform')` * - :need:`wp__fdr_reports` (feature's Safety Analyses & DFA) - :ndf:`copy('status', need_id='wf__p_formal_rv')` - - :need:`doc__score_platform_safety_analysis_fdr` - - :ndf:`copy('status', need_id='doc__score_platform_safety_analysis_fdr')` + - :need:`doc__safety_analysis_fdr_platform` + - :ndf:`copy('status', need_id='doc__safety_analysis_fdr_platform')` * - :need:`wp__audit_report` - performed by external experts @@ -454,17 +454,17 @@ Functional Safety Specific SW Platform Work Products * - :need:`wp__platform_dfa` - :ndf:`copy('status', need_id='wf__analyse_platform_featarch')` - - :need:`doc__score_platform_dfa` - - :ndf:`copy('status', need_id='doc__score_platform_dfa')` + - :need:`doc__dfa_platform` + - :ndf:`copy('status', need_id='doc__dfa_platform')` * - :need:`wp__platform_safety_manual` - :ndf:`copy('status', need_id='wf__cr_mt_safety_manual')` - - :need:`doc__score_platform_safety_manual` - - :ndf:`copy('status', need_id='doc__score_platform_safety_manual')` + - :need:`doc__safety_manual_platform` + - :ndf:`copy('status', need_id='doc__safety_manual_platform')` * - :need:`wp__safety_tailoring` (generic) - :ndf:`copy('status', need_id='wf__def_app_process_description')` - - :need:`wp__tailoring_work_products` & :need:`doc__score_platform_safety_plan` + - :need:`wp__tailoring_work_products` & :need:`doc__safety_plan_platform` - :ndf:`copy('status', need_id='wp__tailoring_work_products')` Process status: Status of the workflow which "outputs" the work product, derived from the docs it "has" and guidances it "contains". @@ -482,7 +482,7 @@ Platform Management Plan - Feature Work Product Lists `Lifecycle Safety Planning `__ -Note: list of features according to :ref:`releases` +Note: list of features according to :ref:`platform_releases` Platform Management Plan - Documents Status Chart diff --git a/docs/platform_management_plan/software_development.rst b/docs/platform_management_plan/software_development.rst index 1ede6c6acfd..69226f66727 100644 --- a/docs/platform_management_plan/software_development.rst +++ b/docs/platform_management_plan/software_development.rst @@ -11,7 +11,7 @@ # # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. _sw_development: +.. _sw_development_plan: Software Development Plan ------------------------- @@ -101,7 +101,7 @@ The design guideline is defined in :need:`doc_concept__imp_concept` and :need:`g API guidelines ^^^^^^^^^^^^^^ -To provide the user with a consistent approach on the use of APIs, there are guidelines documented in :need:`doc__api_guidelines` +To provide the user with a consistent approach on the use of APIs, there are guidelines documented in :need:`doc__api_guide` and :need:`doc__rust_api_design`, this defines for example the error handling concept or rules to improve user experience. Coding guidelines @@ -119,7 +119,7 @@ The configuration of the software is done by the code. Which means that there ar SW development tools ^^^^^^^^^^^^^^^^^^^^ -This list will evolve into the complete "Tool List" :ref:`tools` for the S-CORE project used for +This list will evolve into the complete "Tool List" :ref:`platform_tools` for the S-CORE project used for tool evaluation and qualification. In the moment the :need:`doc__verification_plan` contains additional tools used in verification. Tools for code analysis (static/dynamic) as discussed in :need:`doc__cpp_code_analysis` are documented here. @@ -128,7 +128,7 @@ Tools for code analysis (static/dynamic) as discussed in :need:`doc__cpp_code_an is used for hosting, versioning and contribution of the software. Within pull requests it's possible to contribute. For contribution a separate process description is -:need:`doc__contr_guideline` available. In the discussion section the information regarding meeting +:need:`doc__contribution_guide` available. In the discussion section the information regarding meeting minutes and Working Sections were stored. Within issues can bugfixes, improvements, blank issues set up. It's also possible to report there Security vulnerabilities. GitHub Actions is used as a support for continuous integration. @@ -209,3 +209,16 @@ The qualified `Ferrocene `__ compiler is planned t The main build environment of the project is based on `Bazel `__. It it used to build software components, documentation, and automated tests. + + +Software Development Plan Elements +---------------------------------- + +Here you find the summary of the relevant documents for the SW Development Plan + +.. needtable:: Software Development Plan Elements + :style: table + :columns: title;id;safety;security;status + :colwidths: 25,45,10,10,10 + :sort: docname + :filter: "wp__sw_development_plan" in realizes diff --git a/docs/platform_management_plan/software_verification.rst b/docs/platform_management_plan/software_verification.rst index 5a99921df78..35fbc34e18a 100644 --- a/docs/platform_management_plan/software_verification.rst +++ b/docs/platform_management_plan/software_verification.rst @@ -101,11 +101,11 @@ automated software build at any time. The following types of integrations are applicable: -#. **New software elements** get integrated according to the :need:`doc__contr_guideline` +#. **New software elements** get integrated according to the :need:`doc__contribution_guide` #. **Fixes of defects** get integrated based on their prioritization described by the :doc:`problem_resolution`. #. **Changes** get integrated based on the :need:`wf__change_create_cr` and will follow - the :need:`doc__pull_request_guideline` as any other artifact. + the :need:`doc__pull_request_guide` as any other artifact. The test methods and techniques shall be selected based on the characteristics and specified behavior of the software element under test. This shall ensure proper testing from unit level to platform integration level. @@ -141,7 +141,7 @@ There are the following different levels of integration and verification defined **Note:** These three levels translate to the levels of ISO 26262 part 6 clauses 9 to 11, where compliant testing with full coverage is tailored out for the embedded software. - The specific tailoring is described in the :need:`doc__score_platform_safety_plan`. + The specific tailoring is described in the :need:`doc__safety_plan_platform`. The full Platform Integration Testing will be executed by the integrator. S-CORE project only executes tests on reference hardware. These tests serve as an optional base for the integrator and will also be part of the :need:`wp__verification_platform_ver_report`, but more on an informative character. The full scope diff --git a/docs/platform_management_plan/tool_management.rst b/docs/platform_management_plan/tool_management.rst index 4fc518ed64e..db3d6bb5dc1 100644 --- a/docs/platform_management_plan/tool_management.rst +++ b/docs/platform_management_plan/tool_management.rst @@ -171,4 +171,4 @@ development, as the respective methods are not used: Tool List ^^^^^^^^^ -The S-CORE tools overview can be found here: :ref:`tools` +The S-CORE tools overview can be found here: :ref:`platform_tools` diff --git a/docs/quality/qms_report.rst b/docs/quality/qms_report.rst index 0e489b2556d..dd4d085c6db 100644 --- a/docs/quality/qms_report.rst +++ b/docs/quality/qms_report.rst @@ -12,11 +12,13 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _platform_quality_report: -Quality Report -============== +Platform Quality Report +======================= -.. document:: Quality Report + +.. document:: Platform Quality Report :id: doc__score_qms_report :status: draft :version: 1 @@ -26,6 +28,8 @@ Quality Report :tags: + + This document implements :need:`wp__qms_report` and based on the :need:`wp__qms_plan`. It summarizes the results of the quality related activities. It shall be referred in the :need:`wp__platform_sw_release_note` of a platform release. @@ -314,24 +318,24 @@ Quality Management Generic work products - - * - :need:`wp__platform_dfa` - - :need:`doc__score_platform_dfa` - - :ndf:`copy('status', need_id='doc__score_platform_dfa')` + - :need:`doc__platform_dfa` + - :ndf:`copy('status', need_id='doc__platform_dfa')` * - :need:`wp__platform_handbook` - :need:`doc__platform_handbook` - :ndf:`copy('status', need_id='doc__platform_handbook')` * - :need:`wp__fdr_reports` - - :need:`doc__score_platform_safety_analysis_fdr` - - :ndf:`copy('status', need_id='doc__score_platform_safety_analysis_fdr')` + - :need:`doc__platform_safety_analysis_fdr` + - :ndf:`copy('status', need_id='doc__platform_safety_analysis_fdr')` * - :need:`wp__platform_safety_manual` - - :need:`doc__score_platform_safety_manual` - - :ndf:`copy('status', need_id='doc__score_platform_safety_manual')` + - :need:`doc__platform_safety_manual` + - :ndf:`copy('status', need_id='doc__platform_safety_manual')` * - :need:`wp__platform_safety_plan` - - :need:`doc__score_platform_safety_plan` - - :ndf:`copy('status', need_id='doc__score_platform_safety_plan')` + - :need:`doc__platform_safety_plan` + - :ndf:`copy('status', need_id='doc__platform_safety_plan')` * - :need:`wp__platform_security_manual` - - @@ -346,8 +350,8 @@ Quality Management Generic work products - - * - :need:`wp__fdr_reports` - - :need:`doc__score_platform_safety_plan_fdr` - - :ndf:`copy('status', need_id='doc__score_platform_safety_plan_fdr')` + - :need:`doc__platform_safety_plan_fdr` + - :ndf:`copy('status', need_id='doc__platform_safety_plan_fdr')` * - :need:`wp__platform_sw_release_note` - - diff --git a/docs/requirements/platform_assumptions/index.rst b/docs/requirements/platform_assumptions/index.rst index 8805571e99c..106c69ae736 100644 --- a/docs/requirements/platform_assumptions/index.rst +++ b/docs/requirements/platform_assumptions/index.rst @@ -254,7 +254,7 @@ This is the highest level of integration. This is the level where the S-CORE SW- If the system using the SW-platform has safety goals, the system integrator shall check for correctness and completeness of SW-platform testing and add verification where needed. Note: The SW-platform integtion tests provided by S-CORE for :need:`aou_req__platform__testing` are for demonstration purpose only, - as described in the tailoring section of :need:`doc__score_platform_safety_plan` and thus do not claim correctness and completeness. + as described in the tailoring section of :need:`doc__safety_plan_platform` and thus do not claim correctness and completeness. .. aou_req:: Integrator safety anomaly reporting :id: aou_req__platform__integration_safety_anomaly diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index 807e8a38c1e..811f1be3d16 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -17,7 +17,7 @@ Stakeholder Requirements ======================== -.. document:: SW-platform stakeholder requirements +.. document:: Stakeholder requirements :id: doc__stakeholder_requirements :status: draft :version: 1 diff --git a/docs/safety/fdr_reports_safety_analyses_DFA.rst b/docs/safety/fdr_reports_safety_analyses_DFA.rst index 611333174be..1af4a8dcba7 100644 --- a/docs/safety/fdr_reports_safety_analyses_DFA.rst +++ b/docs/safety/fdr_reports_safety_analyses_DFA.rst @@ -13,11 +13,11 @@ # ******************************************************************************* -Safety Analysis Formal Review Report -==================================== +Safety Analysis Formal Review Report Platform +============================================= -.. document:: Safety Analysis Formal Review Report - :id: doc__score_platform_safety_analysis_fdr +.. document:: Safety Analysis Formal Review Report Platform + :id: doc__safety_analysis_fdr_platform :status: draft :version: 1 :safety: ASIL_B @@ -56,7 +56,7 @@ Please note that it is mandatory to fill in the "passed" column with "yes" or "n - * - REQ_01_02 - Are the templates for Safety Analysis used? - - See :need:`doc__score_platform_dfa` + - See :need:`doc__platform_dfa` - Templates are used to generate the Safety Analysis. - - diff --git a/docs/safety/fdr_reports_safety_package.rst b/docs/safety/fdr_reports_safety_package.rst index de59cfd638f..6ae860f0454 100644 --- a/docs/safety/fdr_reports_safety_package.rst +++ b/docs/safety/fdr_reports_safety_package.rst @@ -13,11 +13,11 @@ # ******************************************************************************* -Safety Package Formal Review Report -=================================== +Safety Package Formal Review Report Platform +============================================ -.. document:: Platform Safety Package Formal Review - :id: doc__score_platform_safety_package_fdr +.. document:: Safety Package Formal Review + :id: doc__safety_package_fdr_platform :status: draft :version: 1 :safety: ASIL_B diff --git a/docs/safety/fdr_reports_safety_platform_safety_plan.rst b/docs/safety/fdr_reports_safety_platform_safety_plan.rst index 9db978d9434..5ba15540dff 100644 --- a/docs/safety/fdr_reports_safety_platform_safety_plan.rst +++ b/docs/safety/fdr_reports_safety_platform_safety_plan.rst @@ -13,11 +13,11 @@ # ******************************************************************************* -Safety Plan Formal Review Report -================================ +Safety Plan Formal Review Report Platform +========================================= -.. document:: S-CORE Platform Safety Plan Formal Review - :id: doc__score_platform_safety_plan_fdr +.. document:: Safety Plan Formal Review Platform + :id: doc__safety_plan_fdr_platform :status: draft :version: 1 :safety: ASIL_B diff --git a/docs/safety/index.rst b/docs/safety/index.rst index 4f4afbc0eef..0021745b214 100644 --- a/docs/safety/index.rst +++ b/docs/safety/index.rst @@ -12,15 +12,35 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. +.. _platform_safety: + +Platform Safety Documents +========================= + +.. document:: Platform Safety Documents + :id: doc__safety_documents_platform + :status: draft + :version: 1 + :safety: ASIL_B + :security: NO + :realizes: wp__safety_tailoring[version==1] + :tags: + +.. needtable:: Platform Safety Documents + :style: table + :columns: title;id;safety;security;status + :colwidths: 25,45,10,10,10 + :sort: docname -Safety documentation -==================== + results = [] -Safety specific documentation for Platform is listed here + for need in needs.filter_types(["document"]): + if need["docname"] is not None and "safety/" in need["docname"] and need["docname"] != "safety/index": + results.append(need) .. toctree:: :maxdepth: 1 + :hidden: fdr_reports_safety_analyses_DFA fdr_reports_safety_package diff --git a/docs/safety/platform_dfa.rst b/docs/safety/platform_dfa.rst index cdca7528ac1..7cd218a30a6 100644 --- a/docs/safety/platform_dfa.rst +++ b/docs/safety/platform_dfa.rst @@ -13,11 +13,11 @@ # ******************************************************************************* -Platform DFA (Dependent Failure Analysis) +DFA (Dependent Failure Analysis) Platform ========================================= .. document:: Platform DFA - :id: doc__score_platform_dfa + :id: doc__dfa_platform :status: draft :version: 1 :safety: ASIL_B diff --git a/docs/safety/platform_safety_manual.rst b/docs/safety/platform_safety_manual.rst index 7d264d741fd..1ae4d3aa13c 100644 --- a/docs/safety/platform_safety_manual.rst +++ b/docs/safety/platform_safety_manual.rst @@ -13,11 +13,11 @@ # ******************************************************************************* -Platform Safety Manual +Safety Manual Platform ====================== -.. document:: Platform Safety Manual - :id: doc__score_platform_safety_manual +.. document:: Safety Manual Platform + :id: doc__safety_manual_platform :status: draft :version: 1 :safety: ASIL_B diff --git a/docs/score_releases/index.rst b/docs/score_releases/index.rst index 069a297d784..6c85b4a099d 100644 --- a/docs/score_releases/index.rst +++ b/docs/score_releases/index.rst @@ -1,6 +1,6 @@ -.. _releases: +.. _platform_releases: -Releases and Roadmap -==================== +Platform Releases +================= Releases and roadmap are documented under the following link: `Reference Integration V1.0 `_. diff --git a/docs/score_tools/index.rst b/docs/score_tools/index.rst index 98a7af4fce7..102f016d5e4 100644 --- a/docs/score_tools/index.rst +++ b/docs/score_tools/index.rst @@ -12,10 +12,10 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. _tools: +.. _platform_tools: -S-CORE Tools Overview -===================== +Platform Tools +============== .. .. needtable:: Tools List .. :tags: tool_management @@ -26,15 +26,14 @@ S-CORE Tools Overview .. :colwidths: 30,30,30,30,30,30,30 .. toctree:: - :hidden: - :maxdepth: 2 + :maxdepth: 1 - score_tools_evaluation_list - tools_documentation/index tools_requirements/index + tools_evaluation_list + tools_compiler/index tools_static_analysis_code_quality/index - tools_testing_frameworks/index tools_build_development/index - tools_compiler/index + tools_testing_frameworks/index tools_vc_cicd/index + tools_documentation/index tools_license_security/index diff --git a/docs/score_tools/score_tools_evaluation_list.rst b/docs/score_tools/tools_evaluation_list.rst similarity index 96% rename from docs/score_tools/score_tools_evaluation_list.rst rename to docs/score_tools/tools_evaluation_list.rst index 70af0234290..1075f793a25 100644 --- a/docs/score_tools/score_tools_evaluation_list.rst +++ b/docs/score_tools/tools_evaluation_list.rst @@ -12,8 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. document:: Tool Evaluation List - :id: doc__tool_evaluation_list +.. document:: Tools Evaluation List + :id: doc__tools_evaluation_list :status: draft :version: 1 :safety: ASIL_B @@ -27,11 +27,8 @@ :local: -S-CORE - Complete Tool List for Tool Evaluation -=============================================== - -Overview --------- +Tools Evaluation List +===================== This document provides a comprehensive initial inventory of all tools used across the Eclipse S-CORE project. @@ -45,11 +42,13 @@ of the tool management process defined in the S-CORE Tool Management Plan. In future iterations, the list will be completed and updated, and delivered with every platform release, as part of the Tool Verification Report. +1 Compiler +---------- -1 Documentation Tools ---------------------- +1a C++ Compiler ++++++++++++++++ -.. list-table:: Documentation Tools +.. list-table:: C++ Compiler :header-rows: 1 :widths: 5 15 15 10 10 10 40 40 @@ -61,76 +60,59 @@ release, as part of the Tool Verification Report. - Tool ownership - Link to Verification Report (if relevant) - Confirmation of Use [YES|NO] (if relevant) - * - 1-1 - - Doc-as-Code - - Documentation generation tool - - 7.0.1 (see [1]_) - - YES - - :need:`rl__infrastructure_tooling_community` - - :need:`doc_tool__doc_as_code` - - YES - * - 1-2 - - Sphinx - - Python documentation generator (underlying Doc-as-Code) - - Latest (see [1]_) - - NO - - :need:`rl__infrastructure_tooling_community` - - N/A - - YES - * - 1-3 - - sphinx-needs - - Requirements tracking extension for Sphinx - - T.B.D. (see [1]_) - - YES - - :need:`rl__infrastructure_tooling_community` - - N/A + * - 1a-1 + - GCC + - Host C++ compiler with linker, generates compiler warnings, builds unit tests and binaries for SW integration testing + - 12+ (see [1]_) - YES - * - 1-4 - - PlantUML - - UML diagram generation - - T.B.D. (see [1]_) - - NO - :need:`rl__infrastructure_tooling_community` - - N/A + - :need:`doc_tool__gcc` - YES - * - 1-5 - - Graphviz - - Graph visualization software - - T.B.D. (see [1]_) - - NO - - :need:`rl__infrastructure_tooling_community` - - N/A + * - 1a-2 + - QNX 8.x SDP + - Qualified compiler/linker from BlackBerry for QNX, used for target compilation + - 12+ (see [1]_) - YES - * - 1-6 - - sphinxcontrib.plantuml - - PlantUML integration for Sphinx - - T.B.D. (see [1]_) - - NO - :need:`rl__infrastructure_tooling_community` + - :need:`doc_tool__qcc` - N/A - - YES - * - 1-7 - - TRLC - - BMW Requirements Traceability Language and Compiler - - 2.0.2 (see [1]_) + + +1b Rust Compiler +++++++++++++++++ + +.. list-table:: Rust Compiler + :header-rows: 1 + :widths: 5 15 15 10 10 10 40 40 + + * - ID + - Tool Name + - Description + - Version + - Relevant [YES|NO] + - Tool ownership + - Link to Verification Report (if relevant) + - Confirmation of Use [YES|NO] (if relevant) + * - 1b-1 + - Ferrocene + - Qualified Rust compiler (planned for target, safety-critical use), see https://github.com/ferrocene + - 1.90.0 (see [1]_) - YES - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 1-8 - - LOBSTER - - BMW Requirements traceability and documentation tool - - T.B.D. (see [1]_) + * - 1b-2 + - Rust (standard) + - For host development, no current selection for S-CORE host compiler + - 1.90.0 (see [1]_) - YES - :need:`rl__infrastructure_tooling_community` - N/A - - YES - + - NO 2 Static Analysis & Code Quality -------------------------------- - 2a C++ ++++++ @@ -350,50 +332,7 @@ release, as part of the Tool Verification Report. - N/A - YES - -3 Testing Frameworks --------------------- - -.. list-table:: Testing Frameworks - :header-rows: 1 - :widths: 5 15 15 10 10 10 40 40 - - * - ID - - Tool Name - - Description - - Version - - Relevant [YES|NO] - - Tool ownership - - Link to Verification Report (if relevant) - - Confirmation of Use [YES|NO] (if relevant) - * - 3-1 - - gtest (GoogleTest) - - C++ testing framework - - 1.15.0 (see [1]_) - - YES - - :need:`rl__testing_community` - - :need:`doc_tool__gtest` - - YES - * - 3-2 - - ITF - - Integration Testing Framework, pytest-based - - 0.1.0 (see [1]_) - - YES - - :need:`rl__testing_community` - - :need:`doc_tool__itf` - - YES - * - 3-3 - - pytest - - Python testing framework - - T.B.D. (see [1]_) - - YES - - :need:`rl__testing_community` - - N/A - - YES - - - -4 Build & Development Tools +3 Build & Development Tools --------------------------- .. list-table:: Build & Development Tools @@ -408,7 +347,7 @@ release, as part of the Tool Verification Report. - Tool ownership - Link to Verification Report (if relevant) - Confirmation of Use [YES|NO] (if relevant) - * - 4-1 + * - 3-1 - Bazel - Main build system - 8.3.0 (see [1]_) @@ -416,7 +355,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - :need:`doc_tool__bazel` - YES - * - 4-2 + * - 3-2 - buildifier - Bazel file formatter and linter - 8.2.0.2 (see [1]_) @@ -424,7 +363,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 4-3 + * - 3-3 - rules_python - Bazel Python build rules - 1.4.1 (see [1]_) @@ -432,7 +371,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 4-4 + * - 3-4 - aspect_rules_py - Enhanced Python rules (provides py_venv) - 1.6.3 (see [1]_) @@ -440,7 +379,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 4-5 + * - 3-5 - aspect_rules_lint - Generic linting and formatting rules - 1.5.3 (see [1]_) @@ -448,7 +387,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 4-6 + * - 3-6 - rules_pkg - Packaging dependencies - 1.1.0 (see [1]_) @@ -456,7 +395,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 4-7 + * - 3-7 - rules_java - Java build rules - 8.15.1 (see [1]_) @@ -464,7 +403,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 4-8 + * - 3-8 - rules_cc - C/C++ build rules - 0.2.1 (see [1]_) @@ -472,7 +411,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 4-9 + * - 3-9 - rules_rust - Rust build rules for Bazel - 0.63.0 (see [1]_) @@ -480,7 +419,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 4-10 + * - 3-10 - score_toolchains_qnx - QNX SDP toolchain including compiler, linker, image creation tools - 0.5 (see [1]_) @@ -488,7 +427,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 4-11 + * - 3-11 - score_toolchains_gcc - GCC toolchain packages for various targets - 0.5 (see [1]_) @@ -496,7 +435,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 4-12 + * - 3-12 - toolchains_llvm - LLVM toolchain rules for Bazel (host configuration, C++17 standard) - 1.4.0 (see [1]_) @@ -504,7 +443,7 @@ release, as part of the Tool Verification Report. - :need:`rl__infrastructure_tooling_community` - N/A - N/A - * - 4-13 + * - 3-13 - score_toolchains_rust - Rust toolchains for SCORE project - T.B.D. (see [1]_) @@ -513,13 +452,10 @@ release, as part of the Tool Verification Report. - N/A - YES -5 Compiler ----------- - -5a C++ Compiler -+++++++++++++++ +4 Testing Frameworks +-------------------- -.. list-table:: C++ Compiler +.. list-table:: Testing Frameworks :header-rows: 1 :widths: 5 15 15 10 10 10 40 40 @@ -531,28 +467,35 @@ release, as part of the Tool Verification Report. - Tool ownership - Link to Verification Report (if relevant) - Confirmation of Use [YES|NO] (if relevant) - * - 5a-1 - - GCC - - Host C++ compiler with linker, generates compiler warnings, builds unit tests and binaries for SW integration testing - - 12+ (see [1]_) + * - 4-1 + - gtest (GoogleTest) + - C++ testing framework + - 1.15.0 (see [1]_) - YES - - :need:`rl__infrastructure_tooling_community` - - :need:`doc_tool__gcc` + - :need:`rl__testing_community` + - :need:`doc_tool__gtest` - YES - * - 5a-2 - - QNX 8.x SDP - - Qualified compiler/linker from BlackBerry for QNX, used for target compilation - - 12+ (see [1]_) + * - 4-2 + - ITF + - Integration Testing Framework, pytest-based + - 0.1.0 (see [1]_) - YES - - :need:`rl__infrastructure_tooling_community` - - :need:`doc_tool__qcc` + - :need:`rl__testing_community` + - :need:`doc_tool__itf` + - YES + * - 4-3 + - pytest + - Python testing framework + - T.B.D. (see [1]_) + - YES + - :need:`rl__testing_community` - N/A + - YES +5 Version Control & CI/CD +------------------------- -5b Rust Compiler -++++++++++++++++ - -.. list-table:: Rust Compiler +.. list-table:: Version Control and CI/CD Tools :header-rows: 1 :widths: 5 15 15 10 10 10 40 40 @@ -564,28 +507,35 @@ release, as part of the Tool Verification Report. - Tool ownership - Link to Verification Report (if relevant) - Confirmation of Use [YES|NO] (if relevant) - * - 5b-1 - - Ferrocene - - Qualified Rust compiler (planned for target, safety-critical use), see https://github.com/ferrocene - - 1.90.0 (see [1]_) + * - 5-1 + - Git + - Version control system + - 2.x (see [1]_) - YES - :need:`rl__infrastructure_tooling_community` - N/A - YES - * - 5b-2 - - Rust (standard) - - For host development, no current selection for S-CORE host compiler - - 1.90.0 (see [1]_) + * - 5-2 + - GitHub + - Code hosting and collaboration platform + - cloud + - YES + - :need:`rl__infrastructure_tooling_community` + - :need:`doc_tool__github` + - YES + * - 5-3 + - GitHub Actions + - CI/CD automation platform + - T.B.D. (see [1]_) - YES - :need:`rl__infrastructure_tooling_community` - N/A - - NO - + - YES -6 Version Control & CI/CD -------------------------- +6 Documentation Tools +--------------------- -.. list-table:: Version Control and CI/CD Tools +.. list-table:: Documentation Tools :header-rows: 1 :widths: 5 15 15 10 10 10 40 40 @@ -598,30 +548,69 @@ release, as part of the Tool Verification Report. - Link to Verification Report (if relevant) - Confirmation of Use [YES|NO] (if relevant) * - 6-1 - - Git - - Version control system - - 2.x (see [1]_) + - Doc-as-Code + - Documentation generation tool + - 7.0.1 (see [1]_) - YES - :need:`rl__infrastructure_tooling_community` - - N/A + - :need:`doc_tool__doc_as_code` - YES * - 6-2 - - GitHub - - Code hosting and collaboration platform - - cloud - - YES + - Sphinx + - Python documentation generator (underlying Doc-as-Code) + - Latest (see [1]_) + - NO - :need:`rl__infrastructure_tooling_community` - - :need:`doc_tool__github` + - N/A - YES * - 6-3 - - GitHub Actions - - CI/CD automation platform + - sphinx-needs + - Requirements tracking extension for Sphinx + - T.B.D. (see [1]_) + - YES + - :need:`rl__infrastructure_tooling_community` + - N/A + - YES + * - 6-4 + - PlantUML + - UML diagram generation + - T.B.D. (see [1]_) + - NO + - :need:`rl__infrastructure_tooling_community` + - N/A + - YES + * - 6-5 + - Graphviz + - Graph visualization software + - T.B.D. (see [1]_) + - NO + - :need:`rl__infrastructure_tooling_community` + - N/A + - YES + * - 6-6 + - sphinxcontrib.plantuml + - PlantUML integration for Sphinx + - T.B.D. (see [1]_) + - NO + - :need:`rl__infrastructure_tooling_community` + - N/A + - YES + * - 6-7 + - TRLC + - BMW Requirements Traceability Language and Compiler + - 2.0.2 (see [1]_) + - YES + - :need:`rl__infrastructure_tooling_community` + - N/A + - YES + * - 6-8 + - LOBSTER + - BMW Requirements traceability and documentation tool - T.B.D. (see [1]_) - YES - :need:`rl__infrastructure_tooling_community` - N/A - YES - 7 License & Security -------------------- diff --git a/docs/users_guide/_assets/architecture_0_6.drawio.svg b/docs/users_guide/_assets/architecture_0_6.drawio.svg deleted file mode 100755 index 331c1f2cca2..00000000000 --- a/docs/users_guide/_assets/architecture_0_6.drawio.svg +++ /dev/null @@ -1,2307 +0,0 @@ - - - - - - - - - - - - - - - - - - - - -
-
-
- C++ Base Libraries -
-
-
- - - C++ Base Libraries - - - - - - - - - - - -
-
-
- Development Environment -
-
-
- - - Development Environment - - - - - - - - - - - -
-
-
- Platform API (native APIs for Rust and C++) -
-
-
- - - Platform API (native APIs for Rust and C++) - - - - - - - - - - - -
-
-
- System Services -
-
-
- - - System Services - - - - - - - - - - - -
-
-
- Communication -
-
-
- - - Communication - - - - - - - - - - - -
-
-
- Operating System -
-
-
- - - Operating System - - - - - - - - - - - -
-
-
- Hypervisor / Hardware -
-
-
- - - Hypervisor / Hardware - - - - - - - - - - - -
-
-
- Rust Base Libraries -
-
-
- - - Rust Base Libraries - - - - - - - - - - - -
-
-
- Filesystem -
-
-
- - - Filesystem - - - - - - - - - - - -
-
-
- FutureCpp -
-
-
- - - FutureCpp - - - - - - - - - - - -
-
-
- SafeCpp -
-
-
- - - SafeCpp - - - - - - - - - - - -
-
-
- Static Reflection with Serialization -
-
-
- - - Static Reflectio... - - - - - - - - - - - -
-
-
- Utils -
-
-
- - - Utils - - - - - - - - - - - -
-
-
- Logging Frontend -
-
-
- - - Logging Fro... - - - - - - - - - - - -
-
-
- Logging Frontend -
-
-
- - - Logging Fro... - - - - - - - - - - - -
-
-
- Containers -
-
-
- - - Containers - - - - - - - - - - - -
-
-
- Rust async runtime -
-
-
- - - Rust async runti... - - - - - - - - - - - -
-
-
- Network -
-
-
- - - Network - - - - - - - - - - - -
-
-
- S-CORE Architecture -
-
-
- - - S-CORE Architecture - - - - - - - - - - - -
-
-
- ADAS -
-
-
- - - ADAS - - - - - - - - - - - -
-
-
- ADASApplications / Functions -
-
-
- - - ADASApplications / Functions - - - - - - - - - - - -
-
-
- Fixed Execution Order (FEO) Framework -
-
-
- - - Fixed Execution Order (FEO) F... - - - - - - - - - - - -
-
-
- Telematics and Connectivity -
-
-
- - - Telematics and Connectivity - - - - - - - - - - - -
-
-
- Telematics & Connectivity Applications / Functions -
-
-
- - - Telematics & Connectivity App... - - - - - - - - - - - -
-
-
- TCU Framework -
-
-
- - - TCU Framework - - - - - - - - - - - -
-
-
- ... -
-
-
- - - ... - - - - - - - - - - - -
-
-
- Domain-Specific Applications / Functions -
-
-
- - - Domain-Specific Applications... - - - - - - - - - - - -
-
-
- Domain-Specific Framework -
-
-
- - - Domain-Specific Framework - - - - - - - - - - - -
-
-
- S-CORE v1.0 (proposal) -
-
-
- - - S-CORE v1.0 (pro... - - - - - - - - - - - -
-
-
- S-CORE v0.6 -
-
-
- - - S-CORE v0.6 - - - - - - - - - - - -
-
-
- Part of OS or HW specific implementation -
-
-
- - - Part of OS or HW speci... - - - - - - - - - - - -
-
-
- to be discussed for future releases -
-
-
- - - to be discussed for... - - - - - - - - - - - -
-
-
- Video API -
-
-
- - - Video API - - - - - - - - - - - -
-
-
- Crypto API -
-
-
- - - Crypto API - - - - - - - - - - - -
-
-
- HW Acceleration API -
-
-
- - - HW Acceleration... - - - - - - - - - - - -
-
-
- Persistency API -
-
-
- - - Persistency API - - - - - - - - - - - -
-
-
- Communication API -
-
-
- - - Communication API - - - - - - - - - - - -
-
-
- Lifecycle & Health API -
-
-
- - - Lifecycle & Heal... - - - - - - - - - - - -
-
-
- Configuration API -
-
-
- - - Configuration API - - - - - - - - - - - -
-
-
- Time API -
-
-
- - - Time API - - - - - - - - - - - -
-
-
- Logging API -
-
-
- - - Logging API - - - - - - - - - - - -
-
-
- Fault API -
-
-
- - - Fault API - - - - - - - - - - - -
-
-
- Runtime orchestrator API -
-
-
- - - Runtime orchestr... - - - - - - - - - - - -
-
-
- User / Capability management -
-
-
- - - User / Capabilit... - - - - - - - - - - - -
-
-
- Mandatory Access Control -
-
-
- - - Mandatory Access... - - - - - - - - - - - -
-
-
- Key / Certificate Mgmt -
-
-
- - - Key / Certificat... - - - - - - - - - - - -
-
-
- Intrusion Detection System -
-
-
- - - Intrusion Detect... - - - - - - - - - - - -
-
-
- Config Mgmt -
-
-
- - - Config Mgmt - - - - - - - - - - - -
-
-
- Storage Mgmt -
-
-
- - - Storage Mgmt - - - - - - - - - - - -
-
-
- Video Frame-server -
-
-
- - - Video Frame-serv... - - - - - - - - - - - -
-
-
- Fault Mgmt. -
-
-
- - - Fault Mgmt. - - - - - - - - - - - -
-
-
- Lifecycle & Health Mgmt -
-
-
- - - Lifecycle & Heal... - - - - - - - - - - - -
-
-
- HW Health Mgmt -
-
-
- - - HW Health Mgmt - - - - - - - - - - - -
-
-
- Logging / Data Collection -
-
-
- - - Logging / Data C... - - - - - - - - - - - -
-
-
- Software Update -
-
-
- - - Software Update - - - - - - - - - - - -
-
-
- Firewall -
-
-
- - - Firewall - - - - - - - - - - - -
-
-
- Tunneling -
-
-
- - - Tunneling - - - - - - - - - - - -
-
-
- zero-copy communication -
-
-
- - - zero-copy commun... - - - - - - - - - - - -
-
-
- SOME/IP Gateway -
-
-
- - - SOME/IP Gateway - - - - - - - - - - - -
-
-
- Any other Gateway -
-
-
- - - Any other Gateway - - - - - - - - - - - -
-
-
- Kernel -
-
-
- - - Kernel - - - - - - - - - - - -
-
-
- Time Sync -
-
-
- - - Time Sync - - - - - - - - - - - -
-
-
- Hardware Supervision -
-
-
- - - Hardware Supervi... - - - - - - - - - - - -
-
-
- Container Support -
-
-
- - - Container Support - - - - - - - - - - - -
-
-
- Video / Camera Support -
-
-
- - - Video / Camera S... - - - - - - - - - - - -
-
-
- Audio Support -
-
-
- - - Audio Support - - - - - - - - - - - -
-
-
- Peripheral Support -
-
-
- - - Peripheral Suppo... - - - - - - - - - - - -
-
-
- Ethernet (TCP/IP) -
-
-
- - - Ethernet (TCP/IP) - - - - - - - - - - - -
-
-
- AVB -
-
-
- - - AVB - - - - - - - - - - - -
-
-
- Board Support Package -
-
-
- - - Board Support Pa... - - - - - - - - - - - -
-
-
- Secure Boot -
-
-
- - - Secure Boot - - - - - - - - - - - -
-
-
- Hardware Acceleration Support -
-
-
- - - Hardware Acceleration... - - - - - - - - - - - -
-
-
- Hardware Security Support -
-
-
- - - Hardware Securit... - - - - - - - - - - - -
-
-
- Startup -
-
-
- - - Startup - - - - - - - - - - - -
-
-
- Inter-Partition Communication -
-
-
- - - Inter-Partition... - - - - - - - - - - - -
-
-
- Hardware Virtualization Support -
-
-
- - - Hardware Virtualizatio... - - - - - - - - - - - -
-
-
- Compiler -
- (gcc, clang, rustc) -
-
-
- - - Compiler... - - - - - - - - - - - -
-
-
- Debugg & Trace -
- (gdb, lldb, lttng ..) -
-
-
- - - Debugg & Trace... - - - - - - - - - - - -
-
-
- Testing -
- (Unit, Integration, ...) -
-
-
- - - Testing... - - - - - - - - - - - -
-
-
- Analysis -
- (Perf, SCAS, ...) -
-
-
- - - Analysis... - - - - - - - - - - - -
-
-
- Tools -
- (IDE, Networking, …) -
-
-
- - - Tools... - - - - - - - - - - - -
-
-
- Collaboration -
- (GitHub, …) -
-
-
- - - Collaboration... - - - - - - - - - - - -
-
-
- Simulation -
- (OpenDUT, scenario, xIL) -
-
-
- - - Simulation... - - - - - - - - - - - -
-
-
- Automation -
- (GitHub, …) -
-
-
- - - Automation... - - - - - - - - - - - -
-
-
- Non-converged system, e.g. IVI with Android -
-
-
- - - Non-converged system,... - - - - - - - - - - - -
-
-
- Apps -
-
-
- - - Apps - - - - - - - - - - - -
-
-
- API -
-
-
- - - API - - - - - - - - - - - -
-
-
- Platform -
-
-
- - - Platform - - - - - - - - - - - -
-
-
- OS -
-
-
- - - OS - - - - - - - - - - - -
-
-
- API with vendor specific dependency -
-
-
- - - API with vendor spe... - - - - - - - - - - - -
-
-
- Diagnostic Handler (SOVD, UDS) -
-
-
- - - Diagnostic Handle... - - - - - - - - - - - -
-
-
- Concurrency -
-
-
- - - Concurrency - - - - - - - - - - - -
-
-
- Memory -
-
-
- - - Memory - - - - - - - - - - - -
-
-
- Bit Manipulation -
-
-
- - - Bit Manipulation - - - - - - - - - - - -
-
-
- Containers -
-
-
- - - Containers - - - - - - - - - - - -
-
-
- JSON -
-
-
- - - JSON - - - - - - - - - - - -
-
-
- OS Abstraction -
-
-
- - - OS Abstraction - - - - - - - - - - - -
-
-
- Result -
-
-
- - - Result - - - - - - - - - - - -
-
-
- Binary compatible datatypes -
-
-
- - - Binary compatible... - - - - - - - - - - - -
-
-
- JSON -
-
-
- - - JSON - - - - - - - - - - - -
-
-
- Serialization -
-
-
- - - Serialization - - - - - - - - - - - -
-
-
- Hash -
-
-
- - - Hash - - - - - - - - - - - -
-
-
- Binary compatible datatypes -
-
-
- - - Binary compatible... - - - - - - - - - - - -
-
-
- OS Abstraction -
-
-
- - - OS Abstraction - - - - - - - - - - - -
-
-
- Artificial Intelligence -
-
-
- - - Artificial Intelligence - - - - - - - - - - - -
-
-
- AI based Functionalities -
-
-
- - - AI based Functionalities - - - - - - - - - - - -
-
-
- AI Framework -
-
-
- - - AI Framework - - - - - - - - - - - -
-
-
- System launch and monitor -
-
-
- - - System launch an... - - - - - - - - - - Text is not SVG - cannot display - - - - diff --git a/docs/users_guide/building_simple_application/index.rst b/docs/users_guide/building_simple_application/index.rst deleted file mode 100644 index 01d40a0eea0..00000000000 --- a/docs/users_guide/building_simple_application/index.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2026 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -.. _contribute_own_module: - -Contribute own module -===================== - -This guide walks you through contributing a new platform module to Eclipse S-CORE end-to-end. -As a running example you will build a small demo application called -`scrample `_, which shows how -to compose existing S-CORE platform modules into new functionality. - -By the end of this section you will have: - -- Created a properly structured S-CORE module from scratch. -- Generated documentation from source and integrated it into the platform docs. -- Built the module with Bazel and verified it compiles cleanly. -- Wired up CI/CD workflows so every change is automatically validated. -- Plugged the module into the reference integration so it becomes part of the platform. - -.. toctree:: - :maxdepth: 1 - - first_score_module.rst - doc_generation.rst - building_source_code.rst - cicd_workflows.rst - reference_integration.rst diff --git a/docs/users_guide/index.rst b/docs/users_guide/index.rst index 45ea4b4a570..95af810f1b4 100644 --- a/docs/users_guide/index.rst +++ b/docs/users_guide/index.rst @@ -15,56 +15,19 @@ .. _users_guide: User's Guide -============ +############ -This guide helps you get started with Eclipse S-CORE as a user or module contributor. -It walks you through the project structure, shows you how to build a simple application -on top of S-CORE, and points you to further resources for deeper involvement. -.. toctree:: - :hidden: +.. document:: User`s Guide + :id: doc__users_guide + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__training_path[version==1] - project_basics/index.rst - building_simple_application/index.rst - whats_next/index.rst - useful_links.rst -.. grid:: 2 - :gutter: 3 - :class-container: score-grid +This guide helps you get started with Eclipse S-CORE as a user. +It shows you how to build a simple application on top of S-CORE. - .. grid-item-card:: - :link: project_basics/index - :link-type: doc - - Project Basics - ^^^^^^^^^^^^^^ - Learn about the S-CORE module structure, repositories, and key concepts. - - .. grid-item-card:: - :link: building_simple_application/index - :link-type: doc - - Building a Simple Application - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Step-by-step guide to building and integrating your first application with S-CORE. - -.. grid:: 2 - :gutter: 3 - :class-container: score-grid - - .. grid-item-card:: - :link: whats_next/index - :link-type: doc - - What's Next? - ^^^^^^^^^^^^ - Ideas and pointers for your next steps after the initial setup. - - .. grid-item-card:: - :link: useful_links - :link-type: doc - - Useful Links - ^^^^^^^^^^^^ - A curated collection of important references, tools, and documentation. +TBD diff --git a/docs/users_guide/project_basics/index.rst b/docs/users_guide/project_basics/index.rst deleted file mode 100644 index 07db38a9742..00000000000 --- a/docs/users_guide/project_basics/index.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2026 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* -.. _project_basics: - -Overview -======== - -This section gives you the conceptual foundation for working with S-CORE. -Before diving into code or contribution workflows, read through these pages -to understand how the platform is structured and what drives its design: - -- **Technologies** — the toolchain and infrastructure that power S-CORE, from - build system to documentation and CI/CD. -- **Software Architecture** — the high-level decomposition of the platform into - features and modules, and the principles behind it. -- **Module Structure** — how an individual S-CORE module is laid out on disk, - what each folder contains, and the conventions every module follows. -- **Integration Process** — how modules are continuously built, tested, and - assembled into the reference integration. - -.. toctree:: - :maxdepth: 1 - :glob: - - technology_overview.rst - software_architecture_overview.rst - module_structure_overview.rst - integration_process.rst -.. */index diff --git a/docs/users_guide/whats_next/index.rst b/docs/users_guide/whats_next/index.rst deleted file mode 100644 index 2015f582f9c..00000000000 --- a/docs/users_guide/whats_next/index.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2026 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* -.. _whats_next: - -What's Next? -============ - -There is no single path: you can fix a small bug, implement a requested feature, or simply start a -conversation with the community. The sections below describe the most common entry points. - -A prerequisite for all of this is to become an active S-CORE contributor. -The steps below outline how to get there. - -Becoming a contributor ------------------------ - -#. **Read the User's Guide** — Work through the complete :ref:`users_guide` from start to finish to - build a solid foundation of S-CORE knowledge. - -#. **Start the S-CORE test application "scrample"** — Run `scrample `_ locally to experience the - full development loop (build, test, CI/CD) on a real, self-contained project. - -#. **Implement an open issue and create a pull request** — Pick up an open issue in any S-CORE - module repository, implement your fix or improvement, and go through the pull-request review - process. - -#. **Get in touch with the project leads** — Once you have proven basic S-CORE knowledge, - contact the project leads. If your capability and planned capacity are substantial, you may - qualify for the **Buddy Program**: a dedicated project lead guides you (or your team) - personally until your first task is assigned, and stays available for potential long-term - support on request. - - -Good first issue ----------------- - -S-CORE consists of many `repositories `_, each -maintained by a dedicated *Feature Team* or *Community*. Every team has a -`Discussion section `_ on GitHub and most have -a pinned post with contact information, such as the Feature Team lead and the corresponding Slack -channel — see this `example discussion `_. - -A great first step is to browse issues labelled **"good first issue"** in any module repository, -like `this example issue `_. Before picking -one up, it is always worth dropping a message in the team's Slack channel so the community knows -you are working on it and can point you in the right direction. - -You can also join any Feature Team or Community online meeting — all meetings are publicly listed in -the `Eclipse community calendar `_. - - -Explore Feature Requests -------------------------- - -S-CORE maintains a public backlog of accepted feature requests in the GitHub Project -`Feature Requests/Modifications `_. - -If you want to **propose a new feature** or **take ownership of an already approved one**, reach -out to the project leads via the -`Slack channel `_. -They will guide you through the process of scoping the work and getting started. - - -Reach out to Project Leads ---------------------------- - -Not sure where to begin? Feel free to contact the S-CORE Project Leads directly. They will either -add your topic to the agenda of the *Project Lead Circle* (held every Monday) or suggest an -alternative time slot. - -Reach them through: - -- `Slack channel `_ — for quick questions and informal discussions -- `Developer Mailing List `_ (score-dev@eclipse.org) — for more formal inquiries and reaching a broader audience