WIP: first version of score book #1932

antonkri · 2025-10-23T06:02:14Z

Very first draft, work in progress

direct link: https://eclipse-score.github.io/score/pr-1932/how_tos/score_book/introduction.html

github-actions · 2025-10-23T06:02:31Z

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

github-actions · 2025-10-23T06:08:17Z

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

masc2023

Only comments, as author labeled it with needs-rework

masc2023 · 2025-10-23T06:18:59Z

docs/how_tos/index.rst

+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+How-Tos


Why is this not called Handbook directly?

masc2023 · 2025-10-23T06:19:46Z

docs/how_tos/score_book/index.rst

@@ -0,0 +1,16 @@
+
+S-Core Book


in general we use in other documentation S-CORE (Big letters), the comment applies to the whole document

masc2023 · 2025-10-23T06:20:42Z

docs/how_tos/score_book/module_structure_overview.rst

+==========================
+
+As it was already stated in the "Overview of the technologies" part, S-Core project consists of multiple
+bazel modules, normally located in separate repositories. Majority of S-Core modules are part of S-Core


Bazel-Modules, according to our model Modules realized as Bazel-Modules

masc2023 · 2025-10-23T06:22:06Z

docs/how_tos/score_book/module_structure_overview.rst

+
+S-Core module is the central part of the s-core project, where the software architecture is defined. Here you will find the list and explanation of the features,
+that are provided by the S-Core platform, definition of the high level architecture, break down of the high level architecture to the modules
+and the definition of the functionality (logical interfaces) for every module.


You miss here PMP, which defines the deployment of the Process Definition in process_description, Tool Lists, Design Decisions, and Requirements

masc2023 · 2025-10-23T06:23:21Z

docs/how_tos/score_book/module_structure_overview.rst

+    We automatically generate for every repository html documentation from rst files.
+    You can easily open it as shown at the picture (TODO: Link)
+
+The process repository defines the S-Core process. It defines both general concepts and ideas of the S-Core software development process approach and


It defines Processes compliant to standards, a kind of Framework, Management System, independent from any tools. The PMP in the s-core repo documents, how they are deployed in S-CORE.
That's why it can also used for other projects outside S-CORE.

AlexanderLanin · 2025-10-30T15:30:07Z

dpex.txt

@@ -0,0 +1,181 @@
+<root> ([email protected])


remove file?

masc2023 · 2025-10-31T07:10:42Z

docs/how_tos/score_book/technology_overview.rst

+--------------------------------------
+For documenting our project, for specifying requirements, assumptions of use, architecture, detailed design, tests 
+and further software process related artifacts we completely rely on sphinx and sphinx-needs technology. Additionally we extend sphinx-needs
+implementation with additional checks to ensure traciability and compliance to the S-Core metamodel. The S-Core metamodel & traceability concept


typo, traceability

masc2023 · 2025-10-31T07:12:02Z

docs/how_tos/score_book/introduction.rst

+  allows to fix the problems directly on the implementation level and to ensure, that they will not happen in the future by always
+  reusing the same implementation.
+
+- Another important aspect that normally comes up by the integration of the software stack, espeicially in ASIL relevant systems, is its quality


typo espeicially, especially, propose to replace ASIL with safety and security relevant

masc2023 · 2025-10-31T07:12:16Z

docs/how_tos/score_book/introduction.rst

+  S-Core modules follow this process, mainly by automated checks and in case not yet implemented, with help of manual reviews. The clear
+  goal is to specify only those parts of software development process, that also can be validated with automated checks in the future.
+
+It is important to understand, that S-Core project is not a final product, that can be "out-of-the-box" integrated into the automotive series projects.


propose to replace ASIL with safety and security

masc2023 · 2025-10-31T07:15:23Z

docs/how_tos/score_book/module_structure_overview.rst

+---------------
+GitHub Link: https://github.com/eclipse-score
+
+S-Core module is the central part of the S-Core project, where the software architecture is defined. Here you will find the list and explanation of the features,


and not to forget the objectives in form of stakeholder requirements and the AoU for the platforms for the potential users

docs/how_tos/score_book/introduction.rst

Copilot

Pull Request Overview

This PR adds comprehensive "How-Tos" documentation for the Eclipse S-CORE project, including a tutorial-style guide called the "Eclipse S-CORE Book". It also updates a Python dependency and modifies some configuration files.

Adds extensive documentation covering technology overview, architecture, module structure, integration process, and a sample application tutorial
Updates aspect_rules_py from version 1.4.0 to 1.6.3
Adds new lock files (uv.lock, dpex.txt) for dependency tracking

Reviewed Changes

Copilot reviewed 18 out of 29 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
docs/how_tos/index.rst	Creates main index for How-Tos section
docs/how_tos/score_book/*.rst	Adds comprehensive tutorial documentation including introduction, technology overview, architecture, module structure, and integration process
docs/how_tos/score_book/sample_application/*.rst	Adds step-by-step tutorial for creating a sample S-CORE application
docs/index.rst	Links the new how_tos section to main documentation
MODULE.bazel	Updates aspect_rules_py dependency from 1.4.0 to 1.6.3
.vscode/settings.json	Adds Python analysis path configuration
uv.lock, dpex.txt	Adds new dependency lock files
.clwb/.idea/vcs.xml	Updates IDE VCS configuration

Files not reviewed (1)

.clwb/.idea/vcs.xml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-04T08:28:43Z

docs/how_tos/score_book/technology_overview.rst

+pipeline is done via bazel.
+Validation of requirements, generation of documentation, building source code, execution of unit- or integration tests, for everything
+there is a bazel target in Eclipse S-CORE. Not going into very technical details, bazel is a modern build system, that allows hermetical and
+reproduciable builds, that are for special importance for building safety systems, and additionally provides the possibility to extend


Corrected spelling of 'reproduciable' to 'reproducible'.

Suggested change

reproduciable builds, that are for special importance for building safety systems, and additionally provides the possibility to extend

reproducible builds, that are for special importance for building safety systems, and additionally provides the possibility to extend

Copilot · 2025-11-04T08:28:43Z

docs/how_tos/score_book/technology_overview.rst

+multiple repositores, as you can see here (TODO: link to decision record). At the end, the decision was taken to proceed with multiple repositories.
+The main reason for this, is that Eclipse S-CORE project should not only motivate software developers to work together on new solutions inside of Eclipse S-CORE
+project but also empower to reuse as much as possible from already existing projects and this is easier to do with an approach, where every functionality
+is encapsualted in its own repository. Such an approach has also disadvantages. First, the organizatorical approach of having so many teams working together.


Corrected spelling of 'encapsualted' to 'encapsulated'.

Suggested change

is encapsualted in its own repository. Such an approach has also disadvantages. First, the organizatorical approach of having so many teams working together.

is encapsulated in its own repository. Such an approach has also disadvantages. First, the organizatorical approach of having so many teams working together.

Copilot · 2025-11-04T08:28:44Z

docs/how_tos/score_book/technology_overview.rst

+multiple repositores, as you can see here (TODO: link to decision record). At the end, the decision was taken to proceed with multiple repositories.
+The main reason for this, is that Eclipse S-CORE project should not only motivate software developers to work together on new solutions inside of Eclipse S-CORE
+project but also empower to reuse as much as possible from already existing projects and this is easier to do with an approach, where every functionality
+is encapsualted in its own repository. Such an approach has also disadvantages. First, the organizatorical approach of having so many teams working together.


Corrected spelling of 'organizatorical' to 'organizational'.

Suggested change

is encapsualted in its own repository. Such an approach has also disadvantages. First, the organizatorical approach of having so many teams working together.

is encapsualted in its own repository. Such an approach has also disadvantages. First, the organizational approach of having so many teams working together.

Copilot · 2025-11-04T08:28:44Z

docs/how_tos/score_book/sample_application/reference_integration.rst

+let us now give it a try in the reference qnx image for the x86 platform.
+
+Reference integration repository already provides a
+`referance qnx image  <https://github.com/eclipse-score/reference_integration/tree/main/qnx_qemu>`_.


Corrected spelling of 'referance' to 'reference'.

Suggested change

`referance qnx image <https://github.com/eclipse-score/reference_integration/tree/main/qnx_qemu>`_.

`reference qnx image <https://github.com/eclipse-score/reference_integration/tree/main/qnx_qemu>`_.

Copilot · 2025-11-04T08:28:45Z

docs/how_tos/score_book/sample_application/reference_integration.rst

+Reference integration repository already provides a
+`referance qnx image  <https://github.com/eclipse-score/reference_integration/tree/main/qnx_qemu>`_.
+
+The reference QNX image is currently really rundimentary, providing minimal set of tooling in the IFS image (TODO: link to QNX IFS image desc).


Corrected spelling of 'rundimentary' to 'rudimentary'.

Suggested change

The reference QNX image is currently really rundimentary, providing minimal set of tooling in the IFS image (TODO: link to QNX IFS image desc).

The reference QNX image is currently really rudimentary, providing minimal set of tooling in the IFS image (TODO: link to QNX IFS image desc).

Copilot · 2025-11-04T08:28:46Z

docs/how_tos/score_book/introduction.rst

+   :align: center
+
+
+Welcome to the Eclipse S-CORE project. As Eclipse S-CORE project is continiously developing, the decision was taken


Corrected spelling of 'continiously' to 'continuously'.

Suggested change

Welcome to the Eclipse S-CORE project. As Eclipse S-CORE project is continiously developing, the decision was taken

Welcome to the Eclipse S-CORE project. As Eclipse S-CORE project is continuously developing, the decision was taken

Copilot · 2025-11-04T08:28:46Z

docs/how_tos/score_book/introduction.rst

+
+It is important to understand, that Eclipse S-CORE project is not a final product, that can be "out-of-the-box" integrated into the automotive series projects.
+This has multiple reasons. First of all, Eclipse S-CORE is an open-source project, meaning there is no any commercial company behind this project,
+that can be liable for anything. The strength of the Eclipse S-CORE project is that both its software development process and the corrensponding tooling


Corrected spelling of 'corrensponding' to 'corresponding'.

Suggested change

that can be liable for anything. The strength of the Eclipse S-CORE project is that both its software development process and the corrensponding tooling

that can be liable for anything. The strength of the Eclipse S-CORE project is that both its software development process and the corresponding tooling

Copilot · 2025-11-04T08:28:47Z

docs/how_tos/score_book/integration_process.rst

+--------------------------------------------------
+
+We do encourage every software module inside of the Eclipse S-CORE GitHub organization or also outside of it
+to follow the Eclipse S-CORE development process continiously and introduce it by including approtiated checks into


Corrected spelling of 'approtiated' to 'appropriate'.

Suggested change

to follow the Eclipse S-CORE development process continiously and introduce it by including approtiated checks into

to follow the Eclipse S-CORE development process continiously and introduce it by including appropriate checks into

Copilot · 2025-11-04T08:28:47Z

docs/how_tos/score_book/integration_process.rst

+to follow the Eclipse S-CORE development process continiously and introduce it by including approtiated checks into
+the CI/CD pipeline, so that compliance to the Eclipse S-CORE project is checked with every PR. But the fact is, that
+we can not enforce this, even inside of the GitHub organization. This has various reasons. One reason could be,
+that the software module already exists and is used in multiple other projecs. The other reason could be, that


Corrected spelling of 'projecs' to 'projects'.

Suggested change

that the software module already exists and is used in multiple other projecs. The other reason could be, that

that the software module already exists and is used in multiple other projects. The other reason could be, that

Copilot · 2025-11-04T08:28:47Z

.vscode/settings.json

-      ]
+    ],
+    "python.analysis.extraPaths": [
+        "./ubcode/lib/python3.12/site-packages"


Path appears to contain a typo: 'ubcode' should likely be 'vscode' or '.venv'. This will likely cause the Python analysis path to fail.

Suggested change

"./ubcode/lib/python3.12/site-packages"

"./.venv/lib/python3.12/site-packages"

antonkri requested review from PhilipPartsch, aschemmel-tech, masc2023 and pahmann as code owners October 23, 2025 06:02

antonkri added the needs-rework label Oct 23, 2025

masc2023 reviewed Oct 23, 2025

View reviewed changes

antonkri force-pushed the ankr_score_book branch 7 times, most recently from 2018000 to 68b232e Compare October 30, 2025 14:25

antonkri requested review from AlexanderLanin and dcalavrezo-qorix as code owners October 30, 2025 14:25

antonkri force-pushed the ankr_score_book branch 2 times, most recently from 6746b36 to dd73027 Compare October 30, 2025 14:53

AlexanderLanin reviewed Oct 30, 2025

View reviewed changes

dpex.txt

@@ -0,0 +1,181 @@

<root> ([email protected])

Copy link

Member

AlexanderLanin Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove file?

antonkri force-pushed the ankr_score_book branch 2 times, most recently from 35f802b to 31290aa Compare October 30, 2025 16:35

masc2023 reviewed Oct 31, 2025

View reviewed changes

first version of score book

1ee9f59

antonkri force-pushed the ankr_score_book branch from 31290aa to 1ee9f59 Compare October 31, 2025 12:50

chheis reviewed Nov 3, 2025

View reviewed changes

docs/how_tos/score_book/introduction.rst Outdated Show resolved Hide resolved

FScholPer added 2 commits November 4, 2025 09:14

fix: replaced naming score with Eclipse S-CORE

f889cad

fix: formatting

a617448

AlexanderLanin requested a review from Copilot November 4, 2025 08:26

Copilot AI reviewed Nov 4, 2025

View reviewed changes

FScholPer and others added 2 commits November 4, 2025 09:33

fix: short underlining

f2db032

correct references to bazel modules

9af78a9

antonkri force-pushed the ankr_score_book branch from 1f962f5 to 9af78a9 Compare November 5, 2025 11:50

	reproduciable builds, that are for special importance for building safety systems, and additionally provides the possibility to extend
	reproducible builds, that are for special importance for building safety systems, and additionally provides the possibility to extend

	is encapsualted in its own repository. Such an approach has also disadvantages. First, the organizatorical approach of having so many teams working together.
	is encapsulated in its own repository. Such an approach has also disadvantages. First, the organizatorical approach of having so many teams working together.

	`referance qnx image <https://github.com/eclipse-score/reference_integration/tree/main/qnx_qemu>`_.
	`reference qnx image <https://github.com/eclipse-score/reference_integration/tree/main/qnx_qemu>`_.

	The reference QNX image is currently really rundimentary, providing minimal set of tooling in the IFS image (TODO: link to QNX IFS image desc).
	The reference QNX image is currently really rudimentary, providing minimal set of tooling in the IFS image (TODO: link to QNX IFS image desc).

		:align: center


		Welcome to the Eclipse S-CORE project. As Eclipse S-CORE project is continiously developing, the decision was taken

	that can be liable for anything. The strength of the Eclipse S-CORE project is that both its software development process and the corrensponding tooling
	that can be liable for anything. The strength of the Eclipse S-CORE project is that both its software development process and the corresponding tooling

	to follow the Eclipse S-CORE development process continiously and introduce it by including approtiated checks into
	to follow the Eclipse S-CORE development process continiously and introduce it by including appropriate checks into

	that the software module already exists and is used in multiple other projecs. The other reason could be, that
	that the software module already exists and is used in multiple other projects. The other reason could be, that

	"./ubcode/lib/python3.12/site-packages"
	"./.venv/lib/python3.12/site-packages"

WIP: first version of score book #1932

Are you sure you want to change the base?

WIP: first version of score book #1932

Uh oh!

Conversation

antonkri commented Oct 23, 2025 • edited by AlexanderLanin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 23, 2025

Uh oh!

github-actions bot commented Oct 23, 2025

Uh oh!

masc2023 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

antonkri commented Oct 23, 2025 •

edited by AlexanderLanin

Loading