From d655d4cf1ebbcd400bc741d8e37ce454ea7df9ae Mon Sep 17 00:00:00 2001 From: Maximilian Pollak Date: Thu, 31 Jul 2025 10:55:20 +0200 Subject: [PATCH 1/4] Fixing rst errors & Upgrading README & version Recent upgrade was missing a commit with RST changes => here included. Changed the README to reflect new commands Updated versions to prepare for new release --- MODULE.bazel | 4 +- README.md | 54 +++++-------------- docs/contribute/general/folder.rst | 4 +- .../ipc/docs/safety_planning/index.rst | 2 +- .../quality_management.rst | 18 +++---- .../safety_management.rst | 6 +-- .../software_verification.rst | 4 +- 7 files changed, 31 insertions(+), 61 deletions(-) diff --git a/MODULE.bazel b/MODULE.bazel index 8a3889fabe..8bb8b2a1e3 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -13,7 +13,7 @@ module( name = "score_platform", - version = "1.0.1", + version = "1.1.0", compatibility_level = 0, ) @@ -73,7 +73,7 @@ bazel_dep(name = "rules_java", version = "8.13.0") # ############################################################################### -bazel_dep(name = "score_python_basics", version = "0.3.3") +bazel_dep(name = "score_python_basics", version = "0.3.4") ############################################################################### # diff --git a/README.md b/README.md index adfb454304..58ecf98da0 100644 --- a/README.md +++ b/README.md @@ -28,44 +28,25 @@ bazel run //:copyright.fix ### Building Documentation Score supports multiple methods for generating documentation, tailored to different workflows: -1. **Bazel-based builds** for clean, sandboxed outputs. -2. **Incremental builds** for quick iterations during development. -3. **IDE integration** for live previews, live warnings and even faster iterations. +2. **Documentation builds** for building the documentation. 4. **IDE independent live preview** for live previews of documentation without IDE integration. - -#### Bazel-based Build - -This method ensures clean and isolated documentation builds in a controlled Bazel environment. -It is best suited for CI pipelines or production-ready outputs, although it takes longer compared to -incremental builds. -Here it is possible to build it either with the current 'main' branch of [process](https://github.com/eclipse-score/process_description) or with the imported release version of it. - - -> Note: 'latest' might not work if it's executed behind a proxy or vpn. If this is the case please use 'release' +3. **IDE integration** for live previews, live warnings and even faster iterations. ```sh -bazel build //docs:docs_latest # use current main branch of imported docs repositories (e.g. process_description) -bazel build //docs:docs_release # use release version imported in MODULE.bazel +bazel run //:docs # use versions of the dependencies needed for documentation build that are imported in MODULE.bazel ``` -The output will be located here,depending on which way was chosen: -- bazel-bin/docs/docs_latest/_build/html. -- bazel-bin/docs/docs_release/_build/html. - - +The output will be located in `_build` -#### Incremental build -For local changes and faster feedback, use the incremental build. -This method generates the documentation directly in the _build directory. +#### IDE independent live preview +For a documentation live preview independent of an IDE (CLI + browser only), `sphinx-autobuild` can be used. +This will automatically rebuild the preview after save and have it available at http://127.0.0.1:8000 +Release and latest are both available here as well. ```sh -bazel run //docs:incremental_latest # use current main branch of imported docs repositories (e.g. process_description) -bazel run //docs:incremental_release # use release version imported in MODULE.bazel +bazel run //:live_preview # use versions of the dependencies needed for documentation build that are imported in MODULE.bazel ``` -Unlike IDE integration, which renders only the current file, this approach is ideal for quickly -verifying edits across the entire documentation during development. - #### IDE integration @@ -73,7 +54,7 @@ For live previews, warnings, and linting during development, integrate Esbonio with your IDE (e.g., VS Code): ```sh -bazel run //docs:ide_support +bazel run //:ide_support ``` VS Code: Install the Esbonio extension in VS Code. After installation, restart your IDE. @@ -86,15 +67,6 @@ point your IDE to the .venv_docs virtual environment. Re-run //docs:ide_support if you update Sphinx extensions or other dependencies. -#### IDE independent live preview - -For a documentation live preview independent of an IDE (CLI + browser only), `sphinx-autobuild` can be used. -This will automatically rebuild the preview after save and have it available at http://127.0.0.1:8000 -Release and latest are both available here as well. -```sh -bazel run //docs:live_preview_latest # use current main branch of imported docs repositories (e.g. process_description) -bazel run //docs:live_preview_release # use release version imported in MODULE.bazel -``` ### Testing @@ -145,13 +117,11 @@ sudo apt install lcov ### Notes #### Output Locations -* Bazel builds output, depending on which build was chosen: - - bazel-bin/docs/docs_latest/_build/html. - - bazel-bin/docs/docs_release/_build/html. +* Bazel builds output in the `_build` directory (cmd: `bazel run //:docs`) * Incremental builds output to _build, regardless of chosen way. #### Troubleshooting * Restart your IDE if live previews or warnings are not working after running ide_support. * Ensure your virtual environment is up-to-date by re-running //docs:ide_support when dependencies change. -* Ensure you ran //docs:ide_support before executing //:format.check or //:format.fix +* Ensure you ran //:ide_support before executing //:format.check or //:format.fix diff --git a/docs/contribute/general/folder.rst b/docs/contribute/general/folder.rst index 8934271053..8f444cbc73 100644 --- a/docs/contribute/general/folder.rst +++ b/docs/contribute/general/folder.rst @@ -31,7 +31,7 @@ The following shows the folder structure of the platform repository (ordered alp docs/ -> Documentation of the feature architecture/ -> Feature architecture [:need:`PROCESS_wp__feature_arch`] requirements/ -> Feature requirements [:need:`PROCESS_wp__requirements__feat`] - safety_analysis/ -> Safety analysis on feature level [:need:`PROCESS_wp__feature_safety_analysis`] + safety_analysis/ -> Safety analysis on feature level [:need:`PROCESS_wp__feature_fmea`, :need:`PROCESS_wp__feature_dfa`] safety_planning/ -> Feature specific safety workproducts planning verification/ -> Feature verification report (reporting all feature verifications) [:need:`PROCESS_wp__verification__platform_ver_report`] @@ -102,7 +102,7 @@ The modules and components shall follow the folder structure which was presented [:need:`PROCESS_wp__component_arch`]. requirements/ -> Component requirements [:need:`PROCESS_wp__requirements__comp`] safety_analysis/ -> Safety analysis on component level - [:need:`PROCESS_wp__sw_component_safety_analysis`] + [:need:`PROCESS_wp__sw_component_fmea`, :need:`PROCESS_wp__sw_component_dfa` ] verification/ -> Architecture review [:need:`PROCESS_wp__sw_arch_verification`], code inspection [:need:`PROCESS_wp__sw_implementation_inspection`] / -> Lower level component following folder structure diff --git a/docs/features/communication/ipc/docs/safety_planning/index.rst b/docs/features/communication/ipc/docs/safety_planning/index.rst index c60d1fc885..2ba14afe36 100644 --- a/docs/features/communication/ipc/docs/safety_planning/index.rst +++ b/docs/features/communication/ipc/docs/safety_planning/index.rst @@ -58,7 +58,7 @@ Inter-process Communication Safety Work Products - :doc:`../architecture/index` - see below - * - :need:`PROCESS_wp__feature_safety_analysis` + * - :need:`PROCESS_wp__feature_fmea`, :need:`PROCESS_wp__feature_dfa` - - - diff --git a/docs/platform_management_plan/quality_management.rst b/docs/platform_management_plan/quality_management.rst index aa68ca430e..db68003b5e 100644 --- a/docs/platform_management_plan/quality_management.rst +++ b/docs/platform_management_plan/quality_management.rst @@ -372,13 +372,6 @@ None - - - * - :need:`PROCESS_wp__feature_safety_analysis` - - :need:`PROCESS_gd_guidl__safety_analysis` - - :ndf:`copy('status', need_id='PROCESS_gd_guidl__safety_analysis')` - - - - - - - * - :need:`PROCESS_wp__module_safety_manual` - :need:`PROCESS_gd_guidl__saf_plan_definitions` - :ndf:`copy('status', need_id='PROCESS_gd_guidl__saf_plan_definitions')` @@ -414,7 +407,7 @@ None - - - * - :need:`PROCESS_wp__platform_feature_dfa` + * - :need:`PROCESS_wp__platform_dfa` - :need:`PROCESS_gd_guidl__safety_analysis` - :ndf:`copy('status', need_id='PROCESS_gd_guidl__safety_analysis')` - @@ -582,7 +575,14 @@ None - - - * - :need:`PROCESS_wp__sw_component_safety_analysis` + * - :need:`PROCESS_wp__sw_component_fmea` + - :need:`PROCESS_gd_guidl__safety_analysis` + - :ndf:`copy('status', need_id='PROCESS_gd_guidl__safety_analysis')` + - + - + - + + * - :need:`PROCESS_wp__sw_component_dfa` - :need:`PROCESS_gd_guidl__safety_analysis` - :ndf:`copy('status', need_id='PROCESS_gd_guidl__safety_analysis')` - diff --git a/docs/platform_management_plan/safety_management.rst b/docs/platform_management_plan/safety_management.rst index cfdd6d8e43..e20fc2efff 100644 --- a/docs/platform_management_plan/safety_management.rst +++ b/docs/platform_management_plan/safety_management.rst @@ -16,7 +16,7 @@ :id: doc__platform_safety_plan :status: draft :safety: ASIL_B - :realizes: PROCESS_wp__platform_safety_plan,PROCESS_wp__tailoring + :realizes: PROCESS_wp__platform_dfa,PROCESS_wp__tailoring :tags: platform_management Safety management / Platform Safety Plan @@ -226,7 +226,7 @@ To exchange general information and to clarify general topics the following comm The safety management status is reported in the Technical Lead Circle Meeting which is defined in :need:`doc__project_mgt_plan`. The status report is based on safety plans work product lists (see below) and verification reports on platform and module level: -* :need:`PROCESS_wp__platform_safety_plan` +* :need:`PROCESS_wp__platform_dfa` * :need:`PROCESS_wp__module_safety_plan` * :need:`PROCESS_wp__verification__platform_ver_report` * :need:`PROCESS_wp__verification__module_ver_report` @@ -353,7 +353,7 @@ Functional Safety Management SW Platform Work Products - `Process community issues `_ - - * - :need:`PROCESS_wp__platform_safety_plan` + * - :need:`PROCESS_wp__platform_dfa` - :need:`PROCESS_gd_guidl__saf_plan_definitions` - :ndf:`copy('status', need_id='PROCESS_gd_guidl__saf_plan_definitions')` - `#381 `_ diff --git a/docs/platform_management_plan/software_verification.rst b/docs/platform_management_plan/software_verification.rst index e0ade6494a..cf14f98782 100644 --- a/docs/platform_management_plan/software_verification.rst +++ b/docs/platform_management_plan/software_verification.rst @@ -325,8 +325,8 @@ Beside :need:`PROCESS_wp__verification__comp_int_test` and :need:`PROCESS_wp__ve following aspects define the coverage of the architectural design. - :need:`PROCESS_wp__sw_arch_verification` - done by walkthrough (QM) or inspection (safety-critical parts) -- :need:`PROCESS_wp__sw_component_safety_analysis` for safety-critical parts -- :need:`PROCESS_wp__feature_safety_analysis` for safety-critical parts +- :need:`PROCESS_wp__sw_component_fmea` and :need:`PROCESS_wp__sw_component_dfa` for safety-critical parts +- :need:`PROCESS_wp__feature_fmea` and :need:`PROCESS_wp__feature_dfa` for safety-critical parts Each architectural element has at least one test case linked with attribute "fully verified" or multiple test cases with attribute "partially verified". From c79cd2800604a2e253cbec10a9f9e41bd77aac96 Mon Sep 17 00:00:00 2001 From: Maximilian Pollak Date: Thu, 31 Jul 2025 11:02:13 +0200 Subject: [PATCH 2/4] Update README --- README.md | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 58ecf98da0..3c94815be3 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,9 @@ bazel run //:copyright.fix ### Building Documentation -Score supports multiple methods for generating documentation, tailored to different workflows: -2. **Documentation builds** for building the documentation. -4. **IDE independent live preview** for live previews of documentation without IDE integration. +Score supports multiple methods for generating documentation, tailored to different workflows: +1. **Documentation builds** for building the documentation. +2. **IDE independent live preview** for live previews of documentation without IDE integration. 3. **IDE integration** for live previews, live warnings and even faster iterations. @@ -41,34 +41,31 @@ The output will be located in `_build` #### IDE independent live preview -For a documentation live preview independent of an IDE (CLI + browser only), `sphinx-autobuild` can be used. -This will automatically rebuild the preview after save and have it available at http://127.0.0.1:8000 -Release and latest are both available here as well. +For a documentation live preview independent of an IDE (CLI + browser only), `sphinx-autobuild` can be used. +This will automatically rebuild the preview after save and have it available at `http://127.0.0.1:8000` ```sh bazel run //:live_preview # use versions of the dependencies needed for documentation build that are imported in MODULE.bazel ``` #### IDE integration -For live previews, warnings, and linting during development, -integrate Esbonio with your IDE (e.g., VS Code): +For live previews, warnings, and linting during development, integrate Esbonio with your IDE (e.g., VS Code): ```sh bazel run //:ide_support ``` VS Code: Install the Esbonio extension in VS Code. After installation, restart your IDE. -You should now have live preview available when you open a `.rst` file. -Note: if the extension was already installed when you ran the `ide_support` command, -you will need to restart your IDE. +You should now have live preview available when you open a `.rst` file. -For features like type detection in conf.py or extensions, -point your IDE to the .venv_docs virtual environment. +> Note: if the extension was already installed when you ran the `ide_support` command, +you will need to restart your IDE. +For features like type detection in conf.py or extensions, +point your IDE to the .venv_docs virtual environment. Re-run //docs:ide_support if you update Sphinx extensions or other dependencies. - ### Testing Use the following command to run all available tests: @@ -88,8 +85,9 @@ Grouping of tests via tags is also supported: ```sh $ bazel test --test_tag_filters=docs-build ``` -You can add as many tags as you like, as long as a test has at least one of the tags it will be executed. -*Note: In order for a test to be picked up by this it has to be marked with the tag. Read more [here](/tools/testing/pytest/README.md) +You can add as many tags as you like, as long as a test has at least one of the tags it will be executed. + +> *Note: In order for a test to be picked up by this it has to be marked with the tag. Read more [here](/tools/testing/pytest/README.md) ### Test coverage for Python @@ -98,7 +96,7 @@ To generate coverage data for Python test targets, run the following command: ```sh bazel coverage --combined_report=lcov //docs:score_metamodel_test ``` -This generates a coverage file `_coverage_report.dat` in the folder `bazel-out/_coverage` for the Python test target `//docs:score_metamodel_test`. +This generates a coverage file `_coverage_report.dat` in the folder `bazel-out/_coverage` for the Python test target `//docs:score_metamodel_test`. Replace the target to execute coverage for a different test target. You can use the tool `genhtml` to generate an HTML report as follows: @@ -107,7 +105,7 @@ genhtml --ignore-errors mismatch --branch-coverage --output genhtml "$(bazel inf ``` This generates an HTML report in the folder `genhtml` which shows both line and branch coverage. Open file `genhtml/index.html` in a browser to show the report. -The tool `genhtml` is part of the `lcov` toolchain (https://github.com/linux-test-project/lcov). +The tool `genhtml` is part of the `lcov` toolchain (https://github.com/linux-test-project/lcov). You can install it on Debian/Ubuntu system as follows: ```sh sudo apt update From 9daa518e7eea293e04e30d6121978e3fde89ec4a Mon Sep 17 00:00:00 2001 From: Maximilian Pollak Date: Thu, 31 Jul 2025 11:03:09 +0200 Subject: [PATCH 3/4] Remove old comments --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3c94815be3..3dfaea8d2f 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ Score supports multiple methods for generating documentation, tailored to differ ```sh -bazel run //:docs # use versions of the dependencies needed for documentation build that are imported in MODULE.bazel +bazel run //:docs ``` The output will be located in `_build` @@ -44,7 +44,7 @@ The output will be located in `_build` For a documentation live preview independent of an IDE (CLI + browser only), `sphinx-autobuild` can be used. This will automatically rebuild the preview after save and have it available at `http://127.0.0.1:8000` ```sh -bazel run //:live_preview # use versions of the dependencies needed for documentation build that are imported in MODULE.bazel +bazel run //:live_preview ``` #### IDE integration From 36f2565bb70a3628042c3354106cea141e57173f Mon Sep 17 00:00:00 2001 From: Maximilian Pollak Date: Thu, 31 Jul 2025 12:45:17 +0200 Subject: [PATCH 4/4] Incooperate PR comments --- docs/contribute/general/folder.rst | 2 +- docs/platform_management_plan/safety_management.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/contribute/general/folder.rst b/docs/contribute/general/folder.rst index 8f444cbc73..1ae185c984 100644 --- a/docs/contribute/general/folder.rst +++ b/docs/contribute/general/folder.rst @@ -31,7 +31,7 @@ The following shows the folder structure of the platform repository (ordered alp docs/ -> Documentation of the feature architecture/ -> Feature architecture [:need:`PROCESS_wp__feature_arch`] requirements/ -> Feature requirements [:need:`PROCESS_wp__requirements__feat`] - safety_analysis/ -> Safety analysis on feature level [:need:`PROCESS_wp__feature_fmea`, :need:`PROCESS_wp__feature_dfa`] + safety_analysis/ -> Safety analysis on feature level [:need:`PROCESS_wp__feature_fmea`, :need:`PROCESS_wp__feature_dfa`, :need:`PROCESS_wp__platform_dfa`] safety_planning/ -> Feature specific safety workproducts planning verification/ -> Feature verification report (reporting all feature verifications) [:need:`PROCESS_wp__verification__platform_ver_report`] diff --git a/docs/platform_management_plan/safety_management.rst b/docs/platform_management_plan/safety_management.rst index e20fc2efff..cfdd6d8e43 100644 --- a/docs/platform_management_plan/safety_management.rst +++ b/docs/platform_management_plan/safety_management.rst @@ -16,7 +16,7 @@ :id: doc__platform_safety_plan :status: draft :safety: ASIL_B - :realizes: PROCESS_wp__platform_dfa,PROCESS_wp__tailoring + :realizes: PROCESS_wp__platform_safety_plan,PROCESS_wp__tailoring :tags: platform_management Safety management / Platform Safety Plan @@ -226,7 +226,7 @@ To exchange general information and to clarify general topics the following comm The safety management status is reported in the Technical Lead Circle Meeting which is defined in :need:`doc__project_mgt_plan`. The status report is based on safety plans work product lists (see below) and verification reports on platform and module level: -* :need:`PROCESS_wp__platform_dfa` +* :need:`PROCESS_wp__platform_safety_plan` * :need:`PROCESS_wp__module_safety_plan` * :need:`PROCESS_wp__verification__platform_ver_report` * :need:`PROCESS_wp__verification__module_ver_report` @@ -353,7 +353,7 @@ Functional Safety Management SW Platform Work Products - `Process community issues `_ - - * - :need:`PROCESS_wp__platform_dfa` + * - :need:`PROCESS_wp__platform_safety_plan` - :need:`PROCESS_gd_guidl__saf_plan_definitions` - :ndf:`copy('status', need_id='PROCESS_gd_guidl__saf_plan_definitions')` - `#381 `_