From 5599b62c957b810dbc6df6b301f61ef37237971e Mon Sep 17 00:00:00 2001 From: Anton Krivoborodov Date: Wed, 4 Dec 2024 17:16:56 +0100 Subject: [PATCH 1/6] tooling: add initial .vscode version Issue-ref: resolves #21 --- .vscode/extensions.json | 6 ++ .vscode/restructuredtext.code-snippets | 77 ++++++++++++++++++++++++++ .vscode/settings.json | 46 +++++++++++++++ 3 files changed, 129 insertions(+) create mode 100644 .vscode/extensions.json create mode 100644 .vscode/restructuredtext.code-snippets create mode 100644 .vscode/settings.json diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..fc07eaf --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,6 @@ +{ + "recommendations": [ + "useblocks.sphinx-needs-vscode", + "swyddfa.esbonio" + ] +} diff --git a/.vscode/restructuredtext.code-snippets b/.vscode/restructuredtext.code-snippets new file mode 100644 index 0000000..01812c0 --- /dev/null +++ b/.vscode/restructuredtext.code-snippets @@ -0,0 +1,77 @@ +{ + "stkh_req_directive": { + "prefix": "stkh_req_t", + "body": [ + ".. sthk_req:: $1", + " :id: STHK_REQ__$RANDOM_HEX${RANDOM_HEX/([a-zA-z0-9}]{2,2})(.*)/$1/} $2", + " :reqtype: ${3|Functional, Interface, Process, Legal, Non-Functional|}", + " :security: ${4|YES,NO|}", + " :safety: ${5|QM, ASIL_B, ASIL_D|}", + " :rationale: $6", + " :status: ${7|valid,invalid|}\n", + " $8" ], + "description": "Generate an stakeholder directive need with all needed option types", + }, + "feat_req_directive": + { "prefix": "feat_req_t", + "body": [ ".. feat_req:: $1", + " :id: FEAT_REQ__$RANDOM_HEX${RANDOM_HEX/([a-zA-z0-9}]{2,2})(.*)/$1/} $2", + " :reqtype: ${3|Functional, Interface, Process, Legal, Non-Functional|}", + " :security: ${4|YES,NO|}", + " :safety: ${5|QM, ASIL_B, ASIL_D|}", + " :satisfies: STHK_REQ__$6", + " :status: ${7|valid,invalid|}\n", + " $8" ], + "description": "Generate an feature directive need with all needed option types", + }, + "comp_req_directive": { "prefix": "comp_req_t", + "body": [ ".. comp_req:: $1", + " :id: COMP_REQ__$RANDOM_HEX${RANDOM_HEX/([a-zA-z0-9}]{2,2})(.*)/$1/} $2", + " :reqtype: ${3|Functional, Interface, Process, Legal, Non-Functional|}", + " :security: ${4|YES,NO|}", + " :safety: ${5|QM, ASIL_B, ASIL_D|}", + " :satisfies: FEAT_REQ__$6", + " :status: ${7|valid,invalid|}\n", + " $8" ], + "description": "Generate an component requirement directive need with all needed option types", + }, + "tool_req_directive": { "prefix": "tool_req_t", + "body": [ ".. tool_req:: $1", + " :id: TOOL_REQ__$RANDOM_HEX${RANDOM_HEX/([a-zA-z0-9}]{2,2})(.*)/$1/} $2", + " :reqtype: ${3|Functional, Interface, Process, Legal, Non-Functional|}", + " :security: ${4|YES,NO|}", + " :safety: ${5|QM, ASIL_B, ASIL_D|}", + " :satisfies: GD__$6", + " :status: ${7|valid,invalid|}\n", + " $8" ], + "description": "Generate an tool requirement directive need with all needed option types", + }, + "aou_directive": { "prefix": "aou_t", + "body": [ ".. aou:: $1", + " :id: AOU_REQ__$RANDOM_HEX${RANDOM_HEX/([a-zA-z0-9}]{2,2})(.*)/$1/} $2", + " :reqtype: ${3|Functional, Interface, Process, Legal, Non-Functional|}", + " :security: ${4|YES,NO|}", + " :safety: ${5|ASIL_B, ASIL_D|}", + " :satisfies: $6", + " :status: ${7|valid,invalid|}\n", + " $8" ], + "description": "Generate an AoU directive need with all needed option types", + }, + "feat_arc_directive": + { "prefix": "feat_arc_t", + "body": [ ".. feat_arc::", + " :id: $1", + " :satisfies: $2", + " :status: $3\n", + " $4" ], + "description": "Generate an feature directive need with all needed option types", + }, + "comp_arc_directive": { "prefix": "comp_arc_t", + "body": [ ".. comp_arc::", + " :id: $1", + " :satisfies: $2", + " :status: $3\n", + " $4" ], + "description": "Generate an component directive need with all needed option types", + }, +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..fa59ddd --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,46 @@ +{ + // General Settings + "files.insertFinalNewline": true, + "files.trimTrailingWhitespace": true, + "editor.insertSpaces": true, + "editor.tabCompletion": "on", + "editor.wordWrap": "wordWrapColumn", + "editor.wrappingIndent": "same", + "editor.wordWrapColumn": 100, + "editor.rulers": [ + 100 + ], + + // RST Settings + "[restructuredtext]": { + "editor.tabSize": 3, + }, + + // Sphinx Needs Extension + "sphinx-needs.folders": [ + { + "needsJson": "${workspaceFolder}/bazel-bin/docs/docs/_build/html/needs.json", + "srcDir": "${workspaceFolder}/docs", + }, + { + "needsJson": "${workspaceFolder}/bazel-bin/docs/docs/_build/html/needs.json", + "srcDir": "${workspaceFolder}/process/process_model", + }, + ], + + // Esbonio 0.x (Current) + // see https://github.com/swyddfa/esbonio/blob/0.x/docs/lsp/getting-started.rst + // and https://github.com/swyddfa/esbonio/blob/0.x/docs/lsp/editors/vscode/_configuration.rst + "esbonio.server.pythonPath": "${workspaceFolder}/.venv_docs/bin/python", + "esbonio.sphinx.confDir": "${workspaceFolder}", + "esbonio.sphinx.buildDir": "${workspaceFolder}/_build", + "esbonio.server.logLevel": "info", + // Do not auto-install. We'll use the one in the venv. + "esbonio.server.installBehavior": "nothing", + + // Esbonio 1.x (Preview) + "esbonio.sphinx.pythonCommand": [".venv_docs/bin/python"], + "esbonio.sphinx.buildCommand": ["-b", "html", ".", "_build", "--jobs", "auto"], + // default is "error", which doesn't show anything. + "esbonio.logging.level": "warning" +} From 5a443854113671a8adf6e48869797a9ea1799019 Mon Sep 17 00:00:00 2001 From: Anton Krivoborodov Date: Wed, 4 Dec 2024 17:18:59 +0100 Subject: [PATCH 2/6] tooling: increase line width for output html files Issue-ref: resolves #21 --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index f61fd63..bf48b22 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -45,6 +45,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "alabaster" +html_theme_options = {"page_width": "auto", "body_max_width": "1500"} # -- sphinx-needs configuration -------------------------------------------- From ff737bd91cc21caf1073d57f799dc24e63b6e640 Mon Sep 17 00:00:00 2001 From: Anton Krivoborodov Date: Wed, 4 Dec 2024 17:21:45 +0100 Subject: [PATCH 3/6] process: overview of project organization Issue-ref: resolves #21 --- docs/features/index.rst | 2 + docs/index.rst | 1 + .../_assets/project_organization.svg | 4 + docs/platform_management_plan/index.rst | 44 +++++ .../project_management.rst | 165 ++++++++++++++++++ .../guidelines/general/index.rst | 113 ++++++++++++ docs/process_description/guidelines/index.rst | 1 + 7 files changed, 330 insertions(+) create mode 100644 docs/platform_management_plan/_assets/project_organization.svg create mode 100644 docs/platform_management_plan/index.rst create mode 100644 docs/platform_management_plan/project_management.rst create mode 100644 docs/process_description/guidelines/general/index.rst diff --git a/docs/features/index.rst b/docs/features/index.rst index 058c2fc..cc9bc79 100644 --- a/docs/features/index.rst +++ b/docs/features/index.rst @@ -12,6 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _Platform_Features: + Feature documentation ===================== diff --git a/docs/index.rst b/docs/index.rst index 027268d..1779519 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,3 +23,4 @@ Documentation tool_requirements/index.rst process_description/index.rst features/index.rst + platform_management_plan/index.rst diff --git a/docs/platform_management_plan/_assets/project_organization.svg b/docs/platform_management_plan/_assets/project_organization.svg new file mode 100644 index 0000000..41d80dd --- /dev/null +++ b/docs/platform_management_plan/_assets/project_organization.svg @@ -0,0 +1,4 @@ + + + +
Main SCORE Project
Main SCORE
integration repo
SCORE GitHub organization
Software Module Repo
Software Module Repo
Software Module Repo
CODEOWNER
  • Software Module PLs
  • Software Module Committers
CODEOWNER
  • SCORE PLs
  • SCORE Committers
CODEOWNER
  • Software Module PLs
  • Software Module Committers
CODEOWNER
  • Software Module PLs
  • Software Module Committers
Software Module Repo
Software Module Repo
Software Module
GitHub organization
CODEOWNER
  • Software Module PLs
  • Software Module Committers
Software Module can later
become an Eclipse Child Project
 \ No newline at end of file diff --git a/docs/platform_management_plan/index.rst b/docs/platform_management_plan/index.rst new file mode 100644 index 0000000..e1637ba --- /dev/null +++ b/docs/platform_management_plan/index.rst @@ -0,0 +1,44 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Platform Management Plan +======================== + ++---------------------------+-------------------------------+ +| DOCUMENT IDENTIFICATION | | ++===========================+===============================+ +| Document Type | Plan | ++---------------------------+-------------------------------+ +| Document ID | PLATFORM-MANAGEMENT-PLAN | ++---------------------------+-------------------------------+ +| Project Name | | ++---------------------------+-------------------------------+ +| ASIL | B | ++---------------------------+-------------------------------+ +| Security Classification | CONFIDENTIAL | ++---------------------------+-------------------------------+ +| AUTHOR | | ++---------------------------+-------------------------------+ +| Reviewer | | ++---------------------------+-------------------------------+ +| Approver | | ++---------------------------+-------------------------------+ +| Status | [DRAFT, VERIFIED, RELEASED] | ++---------------------------+-------------------------------+ + +.. toctree:: + :maxdepth: 2 + :caption: Content + + project_management diff --git a/docs/platform_management_plan/project_management.rst b/docs/platform_management_plan/project_management.rst new file mode 100644 index 0000000..b50100d --- /dev/null +++ b/docs/platform_management_plan/project_management.rst @@ -0,0 +1,165 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Project management plan +####################### + +Project organization +==================== + +Steering committees +------------------- +Steering of the project is done by two committees: *project lead circle* and *technical lead circle*. + +* **Project lead circle** + + Members of *Project lead circle* are the project leads of the *SCORE* project. The election of project leads is done as described in the `Project Roles chapter `_ of *Eclipse Foundation Project Handbook*. In case of absence, a project lead can nominate a deputy. + + The main tasks of the *Project lead circle* are: + + * Definition, discussion of and decisions about strategical topics (e.g. which associations to approach, confirmation of roadmap, representation in public). + * Decision on which new software modules should be added or removed from the project. The decision is done based on proposal from the *Technical lead circle*. In case of changes to the existing modules and no concordant decision in the *Technical Lead Circle*, the *Project Lead Circle* has to decide about the change. + * Election of new Project Leads. + * Last instance of escalation path. + + *Project lead circle* proposes and elects a *Project lead circle Assistant* and his deputy with bare majority, who is responsible for scheduling and announcing meetings, preparing and announcing agenda, writing meeting minutes and protocols. The *Project lead circle Assistant* and his deputy can resign anytime on their own will. + +* **Technical lead circle** + + Each *Project Lead* is allowed to nominate one *Technical Lead*. The *Technical Leads* form the "Technical Lead Circle". In case of absence, a technical lead can nominate a deputy. *Technical Leads* have the following responsibilities: + + * Review and approval of *Contribution Requests* + * Project management, e.g., creation of the roadmap + * High-level project control and coordination between multiple software modules. + * Escalation instance for software module project leads and committers. + + *Technical lead circle* proposes and elects a *Technical lead circle Assistant* and his deputy with bare majority, who is responsible for scheduling and announcing meetings, preparing and announcing agenda, writing meeting minutes and protocols. The *Technical lead circle Assistant* and his deputy can resign anytime on their own will. + +Technical committees +-------------------- +* **Communities** + + *Communities* allow committers and contributors to exchange their + opinions, take architectural decisions and implement the topics of some special + technical domain, e.g. testing tooling. One of the *Communities*' important tasks + is to do define architecture, component requirements (if applicable) + and do a breakdown to the concrete tasks of the platform sagas (see `Planning`_) . + Currently following *Communities* are defined in the *SCORE* project: + + * *Tooling/Infrastructure*: *community* for all kind of infra topics: + compiler, IDE, build toolchain and e.t.c. + * *Testing*: *community* to clarify questions and define testing strategy + for the 'SCORE' project + * *Software Architecture*: *community* for clarification of software architecture topics, + e.g. discussion of new features or coding guidelines. + * *Software Development Process*: *community* for definition and maintaining + of safety, security and quality software development process. + + The planning of the activities is done by every *Community* independent of other + teams. Each *Community* has a *Community Lead*, who is nominated by the *Technical lead circle*.The prioritization of some topics can be requested by the *Technical lead circle* + in order to achieve milestones on time. All important architectural decisions + should be reported to the project as *Contribution Request* + to get the final approvement from the *Technical lead circle*. + +* **Cross functional teams** + + *Cross functional teams* are responsible for some piece + of work from the beginning (e.g. definition of the architecture) till the end + (e.g. integration tests) and are assigned to one particular software module. *Cross-functional teams* work independently from each other on *GitHub* issues in the assigned software module. *Cross-functional teams* consist of the contributors, who can specify requirements, define architecture, develop source code and implement tests afterwards. *Project Leads* and *Committers* are also *Contributors* and effectively work on processing of *GitHub* issues. + + Cross-functional team usually consists of the following roles: Project Lead, Safety Manager, Quality Manager, Security Manager, Committers and Contributors. Every *cross-functional* team has at least one committer who can approve the PRs. + +Meeting Structure +----------------- + +* **Project Lead Circle meeting** + + Regular participants of *Project Lead Circle meeting* are the *Project Leads* and *Technical Leads* of the main *SCORE* project. The main purpose of the meeting is the exchange between *Project Leads* and the reporting of the *Technical Lead Circle* to the *Project Lead Circle* and vice versa. + + The *Project Lead Circle meetings* are announced via *score-dev@eclipse.org* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as GitHub Discussions in `Project Lead Circle section `_ and can be read by everyone. Topics for the *Project lead circle meetings* can be proposed only by regular participants and will be prioritized by the *Project lead circle Assistant*. Proposals for agenda topics can be added as comment to the respective GitHub discussion or sent to the *Project lead circle Assistant*. + + Open points from the meetings will be handled by *GitHub Issues* in the *SCORE* main repository and can be filtered via *project_lead_circle* label. + + The *Project Lead Circle meeting* takes place usually once a week. + +* **Technical Lead Circle meeting** + + Regular participants of the *Technical Lead Circle meeting* are the *Technical Leads* of the main *SCORE* project. The main purpose of the meeting is the exchange between technical leads for fulfilling their responsibilities. + + The *Technical Lead Circle meetings* are announced via *score-dev@eclipse.org* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as GitHub Discussions in `Technical Lead Circle section `_ and can be read by everyone. Topics for the *Technical lead circle meetings* can be proposed only by regular participants and will be prioritized by the *Technical lead circle Assistant*. Proposals for agenda topics can be added as comment to the respective GitHub discussion or sent to the *Technical lead circle Assistant*. + + Open points from the meetings will be handled by GitHub Issues in the *SCORE* main repository and can be filtered via label *technical_lead_circle*. + + The *Technical Lead Circle meeting* takes place usually once a week. + +* **Committer Circle Meeting** + + Regular participants of the *Committer Circle meeting* are the *Committers* of the main *SCORE* project and of all software modules/child projects. The main purpose of the meeting are in-depth technical discussions and evaluation of the *Contribution Requests*. + + The *Committer Circle Meeting* is lead by the *Technical Leads*. The *Committer Circle meetings* are announced via *score-dev@eclipse.org* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as GitHub Discussions in `Committer Circle section `_ and can be read by everyone. Topics for the *Committer circle meetings* can be proposed only by regular participants and will be prioritized by the *Technical lead circle*. Proposals for agenda topics can be added as comment to the respective GitHub discussion or sent to the *Technical lead circle Assistant*. + + The *Committer Circle meeting* takes place on demand. The decision for the scheduling of the *Committer Circle Meeting* is taken by the *Technical Lead Circle*. + +Platform structure +================== +Platform consists of multiple repositories. The main repository, *SCORE*, +is the integration repository, where everything comes together. It contains: + +* :ref:`stakeholder requirements ` +* documentation of all :ref:`platform features ` and features flags, + feature requirements and architecture +* documentation of the :ref:`software development process ` +* build system and toolchain definition +* integration rules for software modules. + +The main repository references multiple other repositories, mostly repositories, where +software modules or toolchains are defined. This results in the following :ref:`Folder Structure of Platform Repository `. Every software module has its own repository, that contains multiple components, their requirements, architecture, implementation and tests. +A software module and its repository can be part of the main SCORE *Eclipse Project* and corresponding *GitHub organization* or can be moved to a standalone *Eclipse child project*, if necessary. + + .. image:: _assets/project_organization.svg + :width: 900 + :alt: Infrastructure overview + :align: center + +Platform organization +======================= +Also in case the software module repositories are not always placed +in standalone *Eclipse child projects*, we still consider all software modules +to be standalone *Eclipse child projects*, having their own *Committers* and *Project Leads* +as defined by the *Eclipse Foundation Project Handbook*. Software module committers +and software module project leads are responsible for managing the software module as if it were +a normal *Eclipse child project*. The election of the project leads and committers for software module projects should be done using the main integration *SCORE* project mailing list, *score-dev@eclipse.org*. This means, that the decision who will be the project lead and committer of the new software module will be taken by the project leads and committers of the main *SCORE* project respectively. The elected project leads or committers of the software modules are not automatically project leads and committers of the main integration *SCORE* project. Typically, before becoming a project lead or a committer of the main integration *SCORE* project, you need to build up a good reputation by contributing to the main integration *SCORE* project and being project lead or committer for one of the software modules. + +That should be a normal procedure, that before introducing a new *Eclipse child project* for a software module, it should first reside as a repository in the main *SCORE* project. If the software module later would be moved to a real standalone *Eclipse child project*, e.g., as there is a wish to use this software module independent of the *SCORE* project, then the elected project leads and committers of the software module will be simply taken over as project leads and committers of the new *Eclipse child project* and their tasks will stay the same. Further in this document differentation between a software module and *Eclipse child project* will be done only if necessary. For the software module that resides in the separate repository of the main *SCORE* project, the configuration and the control +of who is committer and project lead is done using +`CODEOWNER files `_ +located in the subfolders of the corresponding repository of the software module. + +Main task of software module committers and project leads is planning and prioritization of activities, maintaining of the backlog and ensuring, that the software development is done according +to process described in the main *SCORE* project. The planning inside of the software +modules should be done as described in the `Planning`_ chapter. +A more detailed description of their activities is given in *Eclipse Foundation Project Handbook*. + +The main project *SCORE* has certainly also project leaders and committers, but +their roles are slightly different compared to the software module committers and +project leads. The role of the *SCORE* project as the central project is, as already +described, to ensure proper integration of multiple softwarre modules, provide common +integration guidelines and mechanisms, e.g. build toolchain. Additionally *SCORE* project +takes care of all overarching topics, as e.g. roadmap and milestone planning or +definition of cross-functional topics. Therefore there exist number of additional +meetings, where such topics are discussed and decided, see `Steering committees`_ for further details. + +Planning +======== +coming soon diff --git a/docs/process_description/guidelines/general/index.rst b/docs/process_description/guidelines/general/index.rst new file mode 100644 index 0000000..f729828 --- /dev/null +++ b/docs/process_description/guidelines/general/index.rst @@ -0,0 +1,113 @@ +.. + # ******************************************************************************* + # 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 +======= + +Naming Conventions 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). + +.. _Platform_Folder_Structure: + +Folder Structure of Platform Repository +--------------------------------------- + +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. + +.. code-block:: text + + docs/ -> Global documentation of the platform. + concepts/ -> Description of overall concepts. + glossary/ -> Glossary of abbreviations used in the platform context. + guidelines/ -> Guidelines regarding ... + architecture/ -> ... architecture, e.g., documentation and tracing. + coding/ -> ... coding rules, style, formatting, best practices for the languages C++, Rust & Python. + detailed_design/ -> ... detailed design of the software components. + general/ -> ... general topics, e.g. naming conventions or the folder structure. + integration/ -> ... platform integration manual + tutorials/ -> ... general tutorials. + + overview/ -> Introduction and high-level description of the platform features. + platform_management_plan/ -> Overall Platform Management Plan [WP_PLATFORM_MGMT], consisting of ... + project_management.rst -> ... Project Management. + stakeholder_management.rst -> ... Stakeholder Management. + safety_management.rst -> ... Safety Management incl. platform safety plan [WP_SAFETY_PLAN] + risk_management.rst -> ... Risk Management. + quality_management.rst -> ... Quality Management [WP_QMS]. + config_management.rst -> ... Configuration Management. + tool_management.rst -> ... Tool Management. + release_management.rst -> ... Release Management. + problem_resolution.rst -> ... Problem Management. + change_management.rst -> ... Change Management. + requirements_management.rst -> ... Requirements Management. + software_development.rst -> ... Development [WP_SW_DEV_PLAN]. + software_verification.rst -> ... Verification [WP_VERIFICATION_PLAN]. + documentation_management.rst -> ... Documentation Management. + release/ -> [WP_SW_RELEASE_NOTE] + safety/ -> safety documentation on platform level (SEooC): [WP_SW_FEAT_DFA], [WP_SW_SAFETY_MANUAL], [WP_SAFETY_CASE], [WP_CMR_REPORTS], [WP_ASSESSMENT_REPORT] + stakeholder_requirements/ -> Stakeholder requirements of the platform [WP_STAKEHOLDER_REQ]. + + examples/ -> examples how a C++, Rust, Python module can be set up + + features/ -> All features of the platform. + / -> Folder containing all sub-folders corresponding to one feature and the contribution request [WP_CONT_REQUEST] + docs/ -> Documentation of the feature consisting of ... + architecture/ -> ... Feature architecture [WP_FEATURE_ARCHITECTURE]. + requirements/ -> ... Feature requirements [WP_FEATURE_REQ]. + safety_analysis/ -> ... Safety analysis on feature level [WP_SW_FEAT_SAFETY_ANALYSES] + safety_planning/ -> ... the feature specific safety workproducts planning + verification/ -> ... Feature verification report (reporting all feature verifications) [WP_SW_VERIFICATION_REPORT] + tests/ -> Feature tests, consisting of ... + integration-tests/ -> ... integration tests [WP_SW_INTEGRATION_TEST]. + toolchain/ -> Definition of toolchain incl. their requirements [WP_TOOL_REQ] + + modules/ -> Modules of the SW platform. + / -> Folder containing all artifacts corresponding to one module. + docs/ -> Documentation of the module consisting of ... + manual/ -> ... Module manual, e.g. integration manual, assumptions of use and safety manual [WP_SW_AOU], [WP_SW_SAFTEY_MANUAL]. + release/ -> ... Module release note [WP_SW_RELEASE_NOTE] plus safety assessment [WP_ASSESSMENT_REPORT] + safety_plan/ -> ... Module safety plan [WP_SAFETY_PLAN], module safety case [WP_SAFETY_CASE] and their conformance reviews [WP_CMR_REPORTS] + safety_analysis/ -> ... Safety analysis on module level [WP_SW_COMP_DFA] + verification/ -> ... Module verification report (reporting all module's components verifications) [WP_SW_VERIFICATION_REPORT] plus safety analysis conformance reviews [WP_CMR_REPORTS] + + components/ -> Components of the module. + / -> Folder containing all artifacts corresponding to one component. + docs/ -> Documentation of the component consisting of ... + architecture/ -> ... Component architecture (only if sub-components exist) [WP_SW_COMPONENTS_ARCHITECTURE]. + requirements/ -> ... Component requirements [WP_SW_COMP_REQ] and HSI (if relevant) [WP_HSI]. + safety_analysis/ -> ... Safety analysis on component level [WP_SW_COMP_SAFETY_ANALYSES] + verification/ -> ... Architecture review [WP_SW_ARCH_VERIFICATION], code inspection [WP_SW_CODE_INSPECT] + src/ -> Source files of the component (incl. detailed design) [WP_SW_IMPLEMENTATION]. + include/ -> Include files of the component + tests/ -> Component tests, consisting of ... + unit_tests/ -> ... unit tests [WP_SW_UNIT_TEST] (for lowest level of components). + integration_tests/ -> ... integration tests [WP_SW_INTEGRATION_TEST]. + verification-tests/ -> ... verification tests [WP_SW_COMPONENT_TEST]. + / -> Sub-Component of the Component. + copy the relevant folders below if applicable (example: no code inspection needed for sub-components from the Open Source) + + platform-integration-tests/ -> Integration tests on reference hardware. + + process/process_model/ -> process definition including workflows, workproducts, roles, guidance [WP_PROCESS_DEFINITION] + + registry/ -> infrastructure configuration + + README.md -> Entrypoint of the repository. + +.. toctree:: + :maxdepth: 1 + :glob: diff --git a/docs/process_description/guidelines/index.rst b/docs/process_description/guidelines/index.rst index 5cca3fe..77ff44c 100644 --- a/docs/process_description/guidelines/index.rst +++ b/docs/process_description/guidelines/index.rst @@ -24,3 +24,4 @@ Configuration/Tool Guidelines git/index.rst branch/index.rst + general/index.rst \ No newline at end of file From 80c967223110c755386f331a1096c9d0a9d2a999 Mon Sep 17 00:00:00 2001 From: Anton Krivoborodov Date: Sun, 8 Dec 2024 15:46:21 +0100 Subject: [PATCH 4/6] process: fixing review findings Issue-ref: resolves #21 --- .vscode/extensions.json | 4 - .vscode/restructuredtext.code-snippets | 77 ------------------- .vscode/settings.json | 28 ------- docs/conf.py | 1 - docs/platform_management_plan/index.rst | 6 +- .../project_management.rst | 58 +++++++++----- .../guidelines/general/index.rst | 10 +-- 7 files changed, 44 insertions(+), 140 deletions(-) delete mode 100644 .vscode/restructuredtext.code-snippets diff --git a/.vscode/extensions.json b/.vscode/extensions.json index fc07eaf..2c63c08 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,6 +1,2 @@ { - "recommendations": [ - "useblocks.sphinx-needs-vscode", - "swyddfa.esbonio" - ] } diff --git a/.vscode/restructuredtext.code-snippets b/.vscode/restructuredtext.code-snippets deleted file mode 100644 index 01812c0..0000000 --- a/.vscode/restructuredtext.code-snippets +++ /dev/null @@ -1,77 +0,0 @@ -{ - "stkh_req_directive": { - "prefix": "stkh_req_t", - "body": [ - ".. sthk_req:: $1", - " :id: STHK_REQ__$RANDOM_HEX${RANDOM_HEX/([a-zA-z0-9}]{2,2})(.*)/$1/} $2", - " :reqtype: ${3|Functional, Interface, Process, Legal, Non-Functional|}", - " :security: ${4|YES,NO|}", - " :safety: ${5|QM, ASIL_B, ASIL_D|}", - " :rationale: $6", - " :status: ${7|valid,invalid|}\n", - " $8" ], - "description": "Generate an stakeholder directive need with all needed option types", - }, - "feat_req_directive": - { "prefix": "feat_req_t", - "body": [ ".. feat_req:: $1", - " :id: FEAT_REQ__$RANDOM_HEX${RANDOM_HEX/([a-zA-z0-9}]{2,2})(.*)/$1/} $2", - " :reqtype: ${3|Functional, Interface, Process, Legal, Non-Functional|}", - " :security: ${4|YES,NO|}", - " :safety: ${5|QM, ASIL_B, ASIL_D|}", - " :satisfies: STHK_REQ__$6", - " :status: ${7|valid,invalid|}\n", - " $8" ], - "description": "Generate an feature directive need with all needed option types", - }, - "comp_req_directive": { "prefix": "comp_req_t", - "body": [ ".. comp_req:: $1", - " :id: COMP_REQ__$RANDOM_HEX${RANDOM_HEX/([a-zA-z0-9}]{2,2})(.*)/$1/} $2", - " :reqtype: ${3|Functional, Interface, Process, Legal, Non-Functional|}", - " :security: ${4|YES,NO|}", - " :safety: ${5|QM, ASIL_B, ASIL_D|}", - " :satisfies: FEAT_REQ__$6", - " :status: ${7|valid,invalid|}\n", - " $8" ], - "description": "Generate an component requirement directive need with all needed option types", - }, - "tool_req_directive": { "prefix": "tool_req_t", - "body": [ ".. tool_req:: $1", - " :id: TOOL_REQ__$RANDOM_HEX${RANDOM_HEX/([a-zA-z0-9}]{2,2})(.*)/$1/} $2", - " :reqtype: ${3|Functional, Interface, Process, Legal, Non-Functional|}", - " :security: ${4|YES,NO|}", - " :safety: ${5|QM, ASIL_B, ASIL_D|}", - " :satisfies: GD__$6", - " :status: ${7|valid,invalid|}\n", - " $8" ], - "description": "Generate an tool requirement directive need with all needed option types", - }, - "aou_directive": { "prefix": "aou_t", - "body": [ ".. aou:: $1", - " :id: AOU_REQ__$RANDOM_HEX${RANDOM_HEX/([a-zA-z0-9}]{2,2})(.*)/$1/} $2", - " :reqtype: ${3|Functional, Interface, Process, Legal, Non-Functional|}", - " :security: ${4|YES,NO|}", - " :safety: ${5|ASIL_B, ASIL_D|}", - " :satisfies: $6", - " :status: ${7|valid,invalid|}\n", - " $8" ], - "description": "Generate an AoU directive need with all needed option types", - }, - "feat_arc_directive": - { "prefix": "feat_arc_t", - "body": [ ".. feat_arc::", - " :id: $1", - " :satisfies: $2", - " :status: $3\n", - " $4" ], - "description": "Generate an feature directive need with all needed option types", - }, - "comp_arc_directive": { "prefix": "comp_arc_t", - "body": [ ".. comp_arc::", - " :id: $1", - " :satisfies: $2", - " :status: $3\n", - " $4" ], - "description": "Generate an component directive need with all needed option types", - }, -} diff --git a/.vscode/settings.json b/.vscode/settings.json index fa59ddd..92c92ec 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -15,32 +15,4 @@ "[restructuredtext]": { "editor.tabSize": 3, }, - - // Sphinx Needs Extension - "sphinx-needs.folders": [ - { - "needsJson": "${workspaceFolder}/bazel-bin/docs/docs/_build/html/needs.json", - "srcDir": "${workspaceFolder}/docs", - }, - { - "needsJson": "${workspaceFolder}/bazel-bin/docs/docs/_build/html/needs.json", - "srcDir": "${workspaceFolder}/process/process_model", - }, - ], - - // Esbonio 0.x (Current) - // see https://github.com/swyddfa/esbonio/blob/0.x/docs/lsp/getting-started.rst - // and https://github.com/swyddfa/esbonio/blob/0.x/docs/lsp/editors/vscode/_configuration.rst - "esbonio.server.pythonPath": "${workspaceFolder}/.venv_docs/bin/python", - "esbonio.sphinx.confDir": "${workspaceFolder}", - "esbonio.sphinx.buildDir": "${workspaceFolder}/_build", - "esbonio.server.logLevel": "info", - // Do not auto-install. We'll use the one in the venv. - "esbonio.server.installBehavior": "nothing", - - // Esbonio 1.x (Preview) - "esbonio.sphinx.pythonCommand": [".venv_docs/bin/python"], - "esbonio.sphinx.buildCommand": ["-b", "html", ".", "_build", "--jobs", "auto"], - // default is "error", which doesn't show anything. - "esbonio.logging.level": "warning" } diff --git a/docs/conf.py b/docs/conf.py index bf48b22..3afc79a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,7 +23,6 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = "Score" -copyright = "2024, Score" author = "Score" release = "0.1" diff --git a/docs/platform_management_plan/index.rst b/docs/platform_management_plan/index.rst index e1637ba..37788db 100644 --- a/docs/platform_management_plan/index.rst +++ b/docs/platform_management_plan/index.rst @@ -22,19 +22,17 @@ Platform Management Plan +---------------------------+-------------------------------+ | Document ID | PLATFORM-MANAGEMENT-PLAN | +---------------------------+-------------------------------+ -| Project Name | | +| Project Name | SCORE | +---------------------------+-------------------------------+ | ASIL | B | +---------------------------+-------------------------------+ -| Security Classification | CONFIDENTIAL | -+---------------------------+-------------------------------+ | AUTHOR | | +---------------------------+-------------------------------+ | Reviewer | | +---------------------------+-------------------------------+ | Approver | | +---------------------------+-------------------------------+ -| Status | [DRAFT, VERIFIED, RELEASED] | +| Status | DRAFT | +---------------------------+-------------------------------+ .. toctree:: diff --git a/docs/platform_management_plan/project_management.rst b/docs/platform_management_plan/project_management.rst index b50100d..8e2c3d5 100644 --- a/docs/platform_management_plan/project_management.rst +++ b/docs/platform_management_plan/project_management.rst @@ -15,6 +15,26 @@ Project management plan ####################### ++---------------------------+-------------------------------+ +| DOCUMENT IDENTIFICATION | | ++===========================+===============================+ +| Document Type | Plan | ++---------------------------+-------------------------------+ +| Document ID | PROJECT-MANAGEMENT-PLAN | ++---------------------------+-------------------------------+ +| Project Name | SCORE | ++---------------------------+-------------------------------+ +| ASIL | B | ++---------------------------+-------------------------------+ +| AUTHOR | | ++---------------------------+-------------------------------+ +| Reviewer | | ++---------------------------+-------------------------------+ +| Approver | | ++---------------------------+-------------------------------+ +| Status | DRAFT | ++---------------------------+-------------------------------+ + Project organization ==================== @@ -31,20 +51,21 @@ Steering of the project is done by two committees: *project lead circle* and *te * Definition, discussion of and decisions about strategical topics (e.g. which associations to approach, confirmation of roadmap, representation in public). * Decision on which new software modules should be added or removed from the project. The decision is done based on proposal from the *Technical lead circle*. In case of changes to the existing modules and no concordant decision in the *Technical Lead Circle*, the *Project Lead Circle* has to decide about the change. * Election of new Project Leads. + * Election of Technical Leads. * Last instance of escalation path. - *Project lead circle* proposes and elects a *Project lead circle Assistant* and his deputy with bare majority, who is responsible for scheduling and announcing meetings, preparing and announcing agenda, writing meeting minutes and protocols. The *Project lead circle Assistant* and his deputy can resign anytime on their own will. + *Project lead circle* proposes and elects a *Project lead circle Assistant* and his deputy with bare majority, who is responsible for scheduling and announcing meetings, preparing and announcing agenda, writing meeting minutes and protocols. *Project lead circle* can reelect *Project lead circle Assistant* at any time. The *Project lead circle Assistant* and his deputy can resign anytime on their own will. * **Technical lead circle** Each *Project Lead* is allowed to nominate one *Technical Lead*. The *Technical Leads* form the "Technical Lead Circle". In case of absence, a technical lead can nominate a deputy. *Technical Leads* have the following responsibilities: - * Review and approval of *Contribution Requests* - * Project management, e.g., creation of the roadmap + * Review and approval of *Contribution Requests*, which add or modify SCORE platform features. + * Project management of the platform development, e.g., creation of the roadmap. * High-level project control and coordination between multiple software modules. * Escalation instance for software module project leads and committers. - *Technical lead circle* proposes and elects a *Technical lead circle Assistant* and his deputy with bare majority, who is responsible for scheduling and announcing meetings, preparing and announcing agenda, writing meeting minutes and protocols. The *Technical lead circle Assistant* and his deputy can resign anytime on their own will. + *Technical lead circle* proposes and elects a *Technical lead circle Assistant* and his deputy with bare majority, who is responsible for scheduling and announcing meetings, preparing and announcing agenda, writing meeting minutes and protocols. *Technical lead circle* can reelect *Technical lead circle Assistant* at any time. The *Technical lead circle Assistant* and his deputy can resign anytime on their own will. Technical committees -------------------- @@ -52,13 +73,12 @@ Technical committees *Communities* allow committers and contributors to exchange their opinions, take architectural decisions and implement the topics of some special - technical domain, e.g. testing tooling. One of the *Communities*' important tasks - is to do define architecture, component requirements (if applicable) - and do a breakdown to the concrete tasks of the platform sagas (see `Planning`_) . + technical domain, e.g. testing tooling. One of the *Communities*' important activities + is to do a breakdown of platform sagas to the concrete tasks (see `Planning`_) . Currently following *Communities* are defined in the *SCORE* project: * *Tooling/Infrastructure*: *community* for all kind of infra topics: - compiler, IDE, build toolchain and e.t.c. + compiler, IDE, build toolchain and etc. * *Testing*: *community* to clarify questions and define testing strategy for the 'SCORE' project * *Software Architecture*: *community* for clarification of software architecture topics, @@ -67,7 +87,7 @@ Technical committees of safety, security and quality software development process. The planning of the activities is done by every *Community* independent of other - teams. Each *Community* has a *Community Lead*, who is nominated by the *Technical lead circle*.The prioritization of some topics can be requested by the *Technical lead circle* + teams. Each *Community* has a *Community Lead*, who is nominated by the *Technical lead circle*. The prioritization of some topics can be requested by the *Technical lead circle* in order to achieve milestones on time. All important architectural decisions should be reported to the project as *Contribution Request* to get the final approvement from the *Technical lead circle*. @@ -76,9 +96,9 @@ Technical committees *Cross functional teams* are responsible for some piece of work from the beginning (e.g. definition of the architecture) till the end - (e.g. integration tests) and are assigned to one particular software module. *Cross-functional teams* work independently from each other on *GitHub* issues in the assigned software module. *Cross-functional teams* consist of the contributors, who can specify requirements, define architecture, develop source code and implement tests afterwards. *Project Leads* and *Committers* are also *Contributors* and effectively work on processing of *GitHub* issues. + (e.g. integration tests) and are usually assigned to the *SCORE* main integration project or to one particular software module. *Cross-functional teams* work independently from each other on *GitHub* issues in the assigned software module. *Cross-functional teams* consist of the contributors, who can specify requirements, define architecture, develop source code and implement tests afterwards. *Project Leads* and *Committers* are also *Contributors* and effectively work on processing of *GitHub* issues. - Cross-functional team usually consists of the following roles: Project Lead, Safety Manager, Quality Manager, Security Manager, Committers and Contributors. Every *cross-functional* team has at least one committer who can approve the PRs. + Cross-functional team usually consists of the following roles: Project Lead, Safety Manager, Quality Manager, Security Manager, Committers and Contributors. Every *cross-functional* team has at least one committer who can approve and merge the Pull Requests of the Contributors. Meeting Structure ----------------- @@ -97,7 +117,7 @@ Meeting Structure Regular participants of the *Technical Lead Circle meeting* are the *Technical Leads* of the main *SCORE* project. The main purpose of the meeting is the exchange between technical leads for fulfilling their responsibilities. - The *Technical Lead Circle meetings* are announced via *score-dev@eclipse.org* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as GitHub Discussions in `Technical Lead Circle section `_ and can be read by everyone. Topics for the *Technical lead circle meetings* can be proposed only by regular participants and will be prioritized by the *Technical lead circle Assistant*. Proposals for agenda topics can be added as comment to the respective GitHub discussion or sent to the *Technical lead circle Assistant*. + The *Technical Lead Circle meetings* are announced via *score-dev@eclipse.org* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as *GitHub Discussions* in `Technical Lead Circle section `_ and can be read by everyone. Topics for the *Technical lead circle meetings* can be proposed only by regular participants and will be prioritized by the *Technical lead circle Assistant*. Proposals for agenda topics can be added as comment to the respective GitHub discussion or sent to the *Technical lead circle Assistant*. Open points from the meetings will be handled by GitHub Issues in the *SCORE* main repository and can be filtered via label *technical_lead_circle*. @@ -105,9 +125,9 @@ Meeting Structure * **Committer Circle Meeting** - Regular participants of the *Committer Circle meeting* are the *Committers* of the main *SCORE* project and of all software modules/child projects. The main purpose of the meeting are in-depth technical discussions and evaluation of the *Contribution Requests*. + Regular participants of the *Committer Circle meeting* are the *Committers* of the main *SCORE* project and of all software modules/child projects. The *Committer Circle Meeting* is lead by the *Technical Leads*. The main purpose of the meeting are in-depth technical discussions and evaluation of the *Contribution Requests*. - The *Committer Circle Meeting* is lead by the *Technical Leads*. The *Committer Circle meetings* are announced via *score-dev@eclipse.org* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as GitHub Discussions in `Committer Circle section `_ and can be read by everyone. Topics for the *Committer circle meetings* can be proposed only by regular participants and will be prioritized by the *Technical lead circle*. Proposals for agenda topics can be added as comment to the respective GitHub discussion or sent to the *Technical lead circle Assistant*. + The *Committer Circle meetings* are announced via *score-dev@eclipse.org* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as GitHub Discussions in `Committer Circle section `_ and can be read by everyone. Topics for the *Committer circle meetings* can be proposed only by regular participants and will be prioritized by the *Technical lead circle*. Proposals for agenda topics can be added as comment to the respective GitHub discussion or sent to the *Technical lead circle Assistant*. The *Committer Circle meeting* takes place on demand. The decision for the scheduling of the *Committer Circle Meeting* is taken by the *Technical Lead Circle*. @@ -119,8 +139,7 @@ is the integration repository, where everything comes together. It contains: * :ref:`stakeholder requirements ` * documentation of all :ref:`platform features ` and features flags, feature requirements and architecture -* documentation of the :ref:`software development process ` -* build system and toolchain definition +* build system including *SCORE* specific *macros* and *rules* * integration rules for software modules. The main repository references multiple other repositories, mostly repositories, where @@ -134,7 +153,7 @@ A software module and its repository can be part of the main SCORE *Eclipse Proj Platform organization ======================= -Also in case the software module repositories are not always placed +Also in case the software module repositories are not placed in standalone *Eclipse child projects*, we still consider all software modules to be standalone *Eclipse child projects*, having their own *Committers* and *Project Leads* as defined by the *Eclipse Foundation Project Handbook*. Software module committers @@ -146,10 +165,7 @@ of who is committer and project lead is done using `CODEOWNER files `_ located in the subfolders of the corresponding repository of the software module. -Main task of software module committers and project leads is planning and prioritization of activities, maintaining of the backlog and ensuring, that the software development is done according -to process described in the main *SCORE* project. The planning inside of the software -modules should be done as described in the `Planning`_ chapter. -A more detailed description of their activities is given in *Eclipse Foundation Project Handbook*. +Main task of project leads is planning and prioritizing of activities, and together with the committers maintaining of the backlog and ensuring, that the software development is done according to process described in the main SCORE project. The planning should be done as described in the `Planning`_ chapter. A more detailed description of PLs' and Committers' activities is given in *Eclipse Foundation Project Handbook*. The main project *SCORE* has certainly also project leaders and committers, but their roles are slightly different compared to the software module committers and diff --git a/docs/process_description/guidelines/general/index.rst b/docs/process_description/guidelines/general/index.rst index f729828..a9aca45 100644 --- a/docs/process_description/guidelines/general/index.rst +++ b/docs/process_description/guidelines/general/index.rst @@ -45,7 +45,7 @@ can be in a different order. platform_management_plan/ -> Overall Platform Management Plan [WP_PLATFORM_MGMT], consisting of ... project_management.rst -> ... Project Management. stakeholder_management.rst -> ... Stakeholder Management. - safety_management.rst -> ... Safety Management incl. platform safety plan [WP_SAFETY_PLAN] + safety_management.rst -> ... Safety Management incl. platform safety plan [WP_PLATFORM_SAFETY_PLAN] risk_management.rst -> ... Risk Management. quality_management.rst -> ... Quality Management [WP_QMS]. config_management.rst -> ... Configuration Management. @@ -57,8 +57,8 @@ can be in a different order. software_development.rst -> ... Development [WP_SW_DEV_PLAN]. software_verification.rst -> ... Verification [WP_VERIFICATION_PLAN]. documentation_management.rst -> ... Documentation Management. - release/ -> [WP_SW_RELEASE_NOTE] - safety/ -> safety documentation on platform level (SEooC): [WP_SW_FEAT_DFA], [WP_SW_SAFETY_MANUAL], [WP_SAFETY_CASE], [WP_CMR_REPORTS], [WP_ASSESSMENT_REPORT] + release/ -> [WP_PLATFORM SW_RELEASE_NOTE] + safety/ -> safety documentation on platform level (SEooC): [WP_SW_FEATURE_DFA], [WP_PLATFORM_SW_SAFETY_MANUAL], [WP_PLATFORM_SAFETY_CASE], [WP_CMR_REPORTS], [WP_ASSESSMENT_REPORT] stakeholder_requirements/ -> Stakeholder requirements of the platform [WP_STAKEHOLDER_REQ]. examples/ -> examples how a C++, Rust, Python module can be set up @@ -79,8 +79,8 @@ can be in a different order. / -> Folder containing all artifacts corresponding to one module. docs/ -> Documentation of the module consisting of ... manual/ -> ... Module manual, e.g. integration manual, assumptions of use and safety manual [WP_SW_AOU], [WP_SW_SAFTEY_MANUAL]. - release/ -> ... Module release note [WP_SW_RELEASE_NOTE] plus safety assessment [WP_ASSESSMENT_REPORT] - safety_plan/ -> ... Module safety plan [WP_SAFETY_PLAN], module safety case [WP_SAFETY_CASE] and their conformance reviews [WP_CMR_REPORTS] + release/ -> ... Module release note [WP_PLATFORM SW_RELEASE_NOTE] plus safety assessment [WP_ASSESSMENT_REPORT] + safety_plan/ -> ... Module safety plan [WP_PLATFORM_SAFETY_PLAN], module safety case [WP_PLATFORM_SAFETY_CASE] and their conformance reviews [WP_CMR_REPORTS] safety_analysis/ -> ... Safety analysis on module level [WP_SW_COMP_DFA] verification/ -> ... Module verification report (reporting all module's components verifications) [WP_SW_VERIFICATION_REPORT] plus safety analysis conformance reviews [WP_CMR_REPORTS] From 6d30dd16527ba7395c7e6942b8aef78b581470ec Mon Sep 17 00:00:00 2001 From: Philipp Ahmann Date: Thu, 5 Dec 2024 15:11:36 +0100 Subject: [PATCH 5/6] process: correct typos Issue-ref: resolves #21 Signed-off-by: Philipp Ahmann --- docs/index.rst | 2 +- docs/platform_management_plan/project_management.rst | 11 +++++++---- .../guidelines/branch/index.rst | 0 .../guidelines/general/index.rst | 2 +- .../guidelines/git/index.rst | 0 .../guidelines/index.rst | 0 docs/{process_description => process}/index.rst | 0 .../templates/index.rst | 0 8 files changed, 9 insertions(+), 6 deletions(-) rename docs/{process_description => process}/guidelines/branch/index.rst (100%) rename docs/{process_description => process}/guidelines/general/index.rst (99%) rename docs/{process_description => process}/guidelines/git/index.rst (100%) rename docs/{process_description => process}/guidelines/index.rst (100%) rename docs/{process_description => process}/index.rst (100%) rename docs/{process_description => process}/templates/index.rst (100%) diff --git a/docs/index.rst b/docs/index.rst index 1779519..e4a4aec 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,6 +21,6 @@ Documentation stakeholder_requirements/index.rst tool_requirements/index.rst - process_description/index.rst + process/index.rst features/index.rst platform_management_plan/index.rst diff --git a/docs/platform_management_plan/project_management.rst b/docs/platform_management_plan/project_management.rst index 8e2c3d5..fdfa792 100644 --- a/docs/platform_management_plan/project_management.rst +++ b/docs/platform_management_plan/project_management.rst @@ -98,7 +98,10 @@ Technical committees of work from the beginning (e.g. definition of the architecture) till the end (e.g. integration tests) and are usually assigned to the *SCORE* main integration project or to one particular software module. *Cross-functional teams* work independently from each other on *GitHub* issues in the assigned software module. *Cross-functional teams* consist of the contributors, who can specify requirements, define architecture, develop source code and implement tests afterwards. *Project Leads* and *Committers* are also *Contributors* and effectively work on processing of *GitHub* issues. - Cross-functional team usually consists of the following roles: Project Lead, Safety Manager, Quality Manager, Security Manager, Committers and Contributors. Every *cross-functional* team has at least one committer who can approve and merge the Pull Requests of the Contributors. + *Cross-functional team* usually consists of the following roles: Project Lead, Safety Manager, Quality Manager, Security Manager, Committers and Contributors. Every *cross-functional* team has at least one committer who can approve and merge the Pull Requests of the Contributors. + + In case *Cross-functional team* needs to request a new repository, this can be done be extending the `otterdog configuration file `_ and creating a new PR, that should be approved by the *Project Leads*. + Meeting Structure ----------------- @@ -160,17 +163,17 @@ as defined by the *Eclipse Foundation Project Handbook*. Software module committ and software module project leads are responsible for managing the software module as if it were a normal *Eclipse child project*. The election of the project leads and committers for software module projects should be done using the main integration *SCORE* project mailing list, *score-dev@eclipse.org*. This means, that the decision who will be the project lead and committer of the new software module will be taken by the project leads and committers of the main *SCORE* project respectively. The elected project leads or committers of the software modules are not automatically project leads and committers of the main integration *SCORE* project. Typically, before becoming a project lead or a committer of the main integration *SCORE* project, you need to build up a good reputation by contributing to the main integration *SCORE* project and being project lead or committer for one of the software modules. -That should be a normal procedure, that before introducing a new *Eclipse child project* for a software module, it should first reside as a repository in the main *SCORE* project. If the software module later would be moved to a real standalone *Eclipse child project*, e.g., as there is a wish to use this software module independent of the *SCORE* project, then the elected project leads and committers of the software module will be simply taken over as project leads and committers of the new *Eclipse child project* and their tasks will stay the same. Further in this document differentation between a software module and *Eclipse child project* will be done only if necessary. For the software module that resides in the separate repository of the main *SCORE* project, the configuration and the control +That should be a normal procedure, that before introducing a new *Eclipse child project* for a software module, it should first reside as a repository in the main *SCORE* project. If the software module later would be moved to a real standalone *Eclipse child project*, e.g., as there is a wish to use this software module independent of the *SCORE* project, then the elected project leads and committers of the software module will be simply taken over as project leads and committers of the new *Eclipse child project* and their tasks will stay the same. Further in this document differentiation between a software module and *Eclipse child project* will be done only if necessary. For the software module that resides in the separate repository of the main *SCORE* project, the configuration and the control of who is committer and project lead is done using `CODEOWNER files `_ -located in the subfolders of the corresponding repository of the software module. +located in the subfolder of the corresponding repository of the software module. Main task of project leads is planning and prioritizing of activities, and together with the committers maintaining of the backlog and ensuring, that the software development is done according to process described in the main SCORE project. The planning should be done as described in the `Planning`_ chapter. A more detailed description of PLs' and Committers' activities is given in *Eclipse Foundation Project Handbook*. The main project *SCORE* has certainly also project leaders and committers, but their roles are slightly different compared to the software module committers and project leads. The role of the *SCORE* project as the central project is, as already -described, to ensure proper integration of multiple softwarre modules, provide common +described, to ensure proper integration of multiple software modules, provide common integration guidelines and mechanisms, e.g. build toolchain. Additionally *SCORE* project takes care of all overarching topics, as e.g. roadmap and milestone planning or definition of cross-functional topics. Therefore there exist number of additional diff --git a/docs/process_description/guidelines/branch/index.rst b/docs/process/guidelines/branch/index.rst similarity index 100% rename from docs/process_description/guidelines/branch/index.rst rename to docs/process/guidelines/branch/index.rst diff --git a/docs/process_description/guidelines/general/index.rst b/docs/process/guidelines/general/index.rst similarity index 99% rename from docs/process_description/guidelines/general/index.rst rename to docs/process/guidelines/general/index.rst index a9aca45..41a5dd2 100644 --- a/docs/process_description/guidelines/general/index.rst +++ b/docs/process/guidelines/general/index.rst @@ -102,7 +102,7 @@ can be in a different order. platform-integration-tests/ -> Integration tests on reference hardware. - process/process_model/ -> process definition including workflows, workproducts, roles, guidance [WP_PROCESS_DEFINITION] + process/ -> process definition including workflows, workproducts, roles, guidance [WP_PROCESS_DEFINITION] registry/ -> infrastructure configuration diff --git a/docs/process_description/guidelines/git/index.rst b/docs/process/guidelines/git/index.rst similarity index 100% rename from docs/process_description/guidelines/git/index.rst rename to docs/process/guidelines/git/index.rst diff --git a/docs/process_description/guidelines/index.rst b/docs/process/guidelines/index.rst similarity index 100% rename from docs/process_description/guidelines/index.rst rename to docs/process/guidelines/index.rst diff --git a/docs/process_description/index.rst b/docs/process/index.rst similarity index 100% rename from docs/process_description/index.rst rename to docs/process/index.rst diff --git a/docs/process_description/templates/index.rst b/docs/process/templates/index.rst similarity index 100% rename from docs/process_description/templates/index.rst rename to docs/process/templates/index.rst From d4f8aeed2d6a71ba2ae7f7bca65f90d620538ead Mon Sep 17 00:00:00 2001 From: Anton Krivoborodov Date: Tue, 10 Dec 2024 09:44:06 +0100 Subject: [PATCH 6/6] process: fix further review findings Issue-ref: resolves #21 --- .../project_management.rst | 10 +++---- docs/process/guidelines/general/index.rst | 30 +++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/platform_management_plan/project_management.rst b/docs/platform_management_plan/project_management.rst index b453053..6109a0d 100644 --- a/docs/platform_management_plan/project_management.rst +++ b/docs/platform_management_plan/project_management.rst @@ -96,7 +96,7 @@ Technical committees *Cross functional teams* are responsible for some piece of work from the beginning (e.g. definition of the architecture) till the end - (e.g. integration tests) and are usually assigned to the *SCORE* main integration project or to one particular software module. *Cross-functional teams* work independently from each other on *GitHub* issues in the assigned software module. *Cross-functional teams* consist of the contributors, who can specify requirements, define architecture, develop source code and implement tests afterwards. *Project Leads* and *Committers* are also *Contributors* and effectively work on processing of *GitHub* issues. + (e.g. integration tests) and are usually assigned to the *SCORE* main integration project or to one particular software module. *Cross-functional teams* work independently from each other on *GitHub Issues* in the assigned software module. *Cross-functional teams* consist of the contributors, who can specify requirements, define architecture, develop source code and implement tests afterwards. *Project Leads* and *Committers* are also *Contributors* and effectively work on processing of *GitHub Issues*. *Cross-functional team* usually consists of the following roles: Project Lead, Safety Manager, Quality Manager, Security Manager, Committers and Contributors. Every *cross-functional* team has at least one committer who can approve and merge the Pull Requests of the Contributors. @@ -120,17 +120,17 @@ Meeting Structure Regular participants of the *Technical Lead Circle meeting* are the *Technical Leads* of the main *SCORE* project. The main purpose of the meeting is the exchange between technical leads for fulfilling their responsibilities. - The *Technical Lead Circle meetings* are announced via *score-dev@eclipse.org* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as *GitHub Discussions* in `Technical Lead Circle section `_ and can be read by everyone. Topics for the *Technical lead circle meetings* can be proposed only by regular participants and will be prioritized by the *Technical lead circle Assistant*. Proposals for agenda topics can be added as comment to the respective GitHub discussion or sent to the *Technical lead circle Assistant*. + The *Technical Lead Circle meetings* are announced via *score-dev@eclipse.org* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as *GitHub Discussions* in `Technical Lead Circle section `_ and can be read by everyone. Topics for the *Technical lead circle meetings* can be proposed only by regular participants and will be prioritized by the *Technical lead circle Assistant*. Proposals for agenda topics can be added as comment to the respective *GitHub Discussion* or sent to the *Technical lead circle Assistant*. - Open points from the meetings will be handled by GitHub Issues in the *SCORE* main repository and can be filtered via label *technical_lead_circle*. + Open points from the meetings will be handled by *GitHub Issues* in the *SCORE* main repository and can be filtered via label *technical_lead_circle*. The *Technical Lead Circle meeting* takes place usually once a week. * **Committer Circle Meeting** - Regular participants of the *Committer Circle meeting* are the *Committers* of the main *SCORE* project and of all software modules/child projects. The *Committer Circle Meeting* is lead by the *Technical Leads*. The main purpose of the meeting are in-depth technical discussions and evaluation of the *Contribution Requests*. + Regular participants of the *Committer Circle meeting* are the *Committers* of the main *SCORE* project and of all software modules/child projects. The *Committer Circle Meeting* is lead by the *Technical Leads*. The main purpose of the meeting are in-depth technical discussions and evaluation of the *Contribution Requests*, that could not be approved in the *Technical Lead Circle meeting* and demand more technical discussions. - The *Committer Circle meetings* are announced via *score-dev@eclipse.org* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as GitHub Discussions in `Committer Circle section `_ and can be read by everyone. Topics for the *Committer circle meetings* can be proposed only by regular participants and will be prioritized by the *Technical lead circle*. Proposals for agenda topics can be added as comment to the respective GitHub discussion or sent to the *Technical lead circle Assistant*. + The *Committer Circle meetings* are announced via *score-dev@eclipse.org* mailing list and are open for everyone who is registered to this mailing list. All meetings are documented as *GitHub Discussions* in `Committer Circle section `_ and can be read by everyone. Topics for the *Committer circle meetings* can be proposed only by regular participants and will be prioritized by the *Technical lead circle*. Proposals for agenda topics can be added as comment to the respective *GitHub Discussion* or sent to the *Technical lead circle Assistant*. The *Committer Circle meeting* takes place on demand. The decision for the scheduling of the *Committer Circle Meeting* is taken by the *Technical Lead Circle*. diff --git a/docs/process/guidelines/general/index.rst b/docs/process/guidelines/general/index.rst index 41a5dd2..6e9abbf 100644 --- a/docs/process/guidelines/general/index.rst +++ b/docs/process/guidelines/general/index.rst @@ -57,8 +57,8 @@ can be in a different order. software_development.rst -> ... Development [WP_SW_DEV_PLAN]. software_verification.rst -> ... Verification [WP_VERIFICATION_PLAN]. documentation_management.rst -> ... Documentation Management. - release/ -> [WP_PLATFORM SW_RELEASE_NOTE] - safety/ -> safety documentation on platform level (SEooC): [WP_SW_FEATURE_DFA], [WP_PLATFORM_SW_SAFETY_MANUAL], [WP_PLATFORM_SAFETY_CASE], [WP_CMR_REPORTS], [WP_ASSESSMENT_REPORT] + release/ -> [WP_PLATFORM_SW_RELEASE_NOTE] + safety/ -> safety documentation on platform level (SEooC): [WP_FEATURE_DFA], [WP_PLATFORM_SW_SAFETY_MANUAL], [WP_PLATFORM_SAFETY_CASE], [WP_CMR_REPORTS], [WP_ASSESSMENT_REPORT] stakeholder_requirements/ -> Stakeholder requirements of the platform [WP_STAKEHOLDER_REQ]. examples/ -> examples how a C++, Rust, Python module can be set up @@ -68,41 +68,41 @@ can be in a different order. docs/ -> Documentation of the feature consisting of ... architecture/ -> ... Feature architecture [WP_FEATURE_ARCHITECTURE]. requirements/ -> ... Feature requirements [WP_FEATURE_REQ]. - safety_analysis/ -> ... Safety analysis on feature level [WP_SW_FEAT_SAFETY_ANALYSES] + safety_analysis/ -> ... Safety analysis on feature level [WP_FEATURE_SAFETY_ANALYSES] safety_planning/ -> ... the feature specific safety workproducts planning - verification/ -> ... Feature verification report (reporting all feature verifications) [WP_SW_VERIFICATION_REPORT] + verification/ -> ... Feature verification report (reporting all feature verifications) [WP_PLATFORM_SW_VERIFICATION_REPORT] tests/ -> Feature tests, consisting of ... - integration-tests/ -> ... integration tests [WP_SW_INTEGRATION_TEST]. + integration-tests/ -> ... integration tests [WP_FEATURE_INTEGRATION_TEST]. toolchain/ -> Definition of toolchain incl. their requirements [WP_TOOL_REQ] modules/ -> Modules of the SW platform. / -> Folder containing all artifacts corresponding to one module. docs/ -> Documentation of the module consisting of ... - manual/ -> ... Module manual, e.g. integration manual, assumptions of use and safety manual [WP_SW_AOU], [WP_SW_SAFTEY_MANUAL]. - release/ -> ... Module release note [WP_PLATFORM SW_RELEASE_NOTE] plus safety assessment [WP_ASSESSMENT_REPORT] - safety_plan/ -> ... Module safety plan [WP_PLATFORM_SAFETY_PLAN], module safety case [WP_PLATFORM_SAFETY_CASE] and their conformance reviews [WP_CMR_REPORTS] - safety_analysis/ -> ... Safety analysis on module level [WP_SW_COMP_DFA] - verification/ -> ... Module verification report (reporting all module's components verifications) [WP_SW_VERIFICATION_REPORT] plus safety analysis conformance reviews [WP_CMR_REPORTS] + manual/ -> ... Module manual, e.g. integration manual, assumptions of use and safety manual [WP_SW_COMPONENT_AOU], [WP_MODULE_SW_SAFETY_MANUAL]. + release/ -> ... Module release note [WP_MODULE_SW_RELEASE_NOTE] plus safety assessment [WP_ASSESSMENT_REPORT] + safety_plan/ -> ... Module safety plan [WP_MODULE_SAFETY_PLAN], module safety case [WP_MODULE_SAFETY_CASE] and their conformance reviews [WP_CMR_REPORTS] + safety_analysis/ -> ... Safety analysis on module level [WP_SW_COMPONENT_DFA] + verification/ -> ... Module verification report (reporting all module's components verifications) [WP_MODULE_SW_VERIFICATION_REPORT] plus safety analysis conformance reviews [WP_CMR_REPORTS] components/ -> Components of the module. / -> Folder containing all artifacts corresponding to one component. docs/ -> Documentation of the component consisting of ... - architecture/ -> ... Component architecture (only if sub-components exist) [WP_SW_COMPONENTS_ARCHITECTURE]. - requirements/ -> ... Component requirements [WP_SW_COMP_REQ] and HSI (if relevant) [WP_HSI]. - safety_analysis/ -> ... Safety analysis on component level [WP_SW_COMP_SAFETY_ANALYSES] + architecture/ -> ... Component architecture (only if sub-components exist) [WP_SW_COMPONENT_ARCHITECTURE]. + requirements/ -> ... Component requirements [WP_SW_COMPONENT_REQ] and HSI (if relevant) [WP_HSI]. + safety_analysis/ -> ... Safety analysis on component level [WP_SW_COMPONENT_SAFETY_ANALYSES] verification/ -> ... Architecture review [WP_SW_ARCH_VERIFICATION], code inspection [WP_SW_CODE_INSPECT] src/ -> Source files of the component (incl. detailed design) [WP_SW_IMPLEMENTATION]. include/ -> Include files of the component tests/ -> Component tests, consisting of ... unit_tests/ -> ... unit tests [WP_SW_UNIT_TEST] (for lowest level of components). - integration_tests/ -> ... integration tests [WP_SW_INTEGRATION_TEST]. + integration_tests/ -> ... integration tests [WP_SW_COMPONENT_INTEGRATION_TEST]. verification-tests/ -> ... verification tests [WP_SW_COMPONENT_TEST]. / -> Sub-Component of the Component. copy the relevant folders below if applicable (example: no code inspection needed for sub-components from the Open Source) platform-integration-tests/ -> Integration tests on reference hardware. - process/ -> process definition including workflows, workproducts, roles, guidance [WP_PROCESS_DEFINITION] + process -> process definition including workflows, workproducts, roles, guidance [WP_PROCESS_DEFINITION] registry/ -> infrastructure configuration