Skip to content

Commit f2592a7

Browse files
masc2023masc2023
authored
Merge pull request #814 from eclipse-score/masc2023_add_pltmgt
process: add initial platform management
2 parents 58ea743 + fd004b9 commit f2592a7

32 files changed

+945
-252
lines changed

‎docs/platform_management_plan/change_management.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -274,8 +274,8 @@ Change Management SW Platform Work Products
274274
- established
275275

276276
* - :need:`wp__platform_mgmt`
277-
- :need:`wf__cr_mt_platform_mngmt_plan`
278-
- :ndf:`copy('status', need_id='wf__cr_mt_platform_mngmt_plan')`
277+
- :need:`wf__platform__cr_mt_platform_mgmt_plan`
278+
- :ndf:`copy('status', need_id='wf__platform__cr_mt_platform_mgmt_plan')`
279279
- <Link to issue>
280280
- :doc:`index`
281281
- :ndf:`copy('status', need_id='doc__platform_mgt_plan')`

‎docs/platform_management_plan/documentation_management.rst

+1-5
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
:status: draft
1818
:safety: ASIL_B
1919
:tags: platform_management
20+
:realizes: wp__document_mgt_plan
2021

2122
Documentation Management Plan
2223
-----------------------------
@@ -38,11 +39,6 @@ Goal of this plan is to describe
3839
Approach
3940
++++++++
4041

41-
.. gd_guidl:: Documentation
42-
:id: gd_guidl__documentation
43-
:status: valid
44-
:complies: std_req__iso26262__support_1041, std_req__iso26262__support_1042, std_req__iso26262__support_1043, std_req__iso26262__support_1044, std_req__iso26262__support_1045, std_req__iso26262__support_1046
45-
4642
Some of the work products of the S-CORE project are modelled specifically
4743
(e.g. the requirements and architecture have a specific set of attributes)
4844
Others are modelled as general documents (e.g. the plans which are part of the program management plan or the verification reports).

‎docs/platform_management_plan/project_management.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@
1515
.. document:: Project Management Plan
1616
:id: doc__project_mgt_plan
1717
:status: draft
18-
:safety: QM
18+
:safety: ASIL_B
19+
:realizes: wp__project_mgt
1920
:tags: platform_management
2021

2122
Project management plan

‎docs/platform_management_plan/safety_management.rst

+8-8
Original file line numberDiff line numberDiff line change
@@ -308,8 +308,8 @@ Functional Safety Management SW Platform Work Products
308308
- to be shown to assessor
309309

310310
* - :need:`wp__qms`
311-
- :need:`wf__cr_mt_platform_mngmt_plan`
312-
- :ndf:`copy('status', need_id='wf__cr_mt_platform_mngmt_plan')`
311+
- :need:`wf__platform__cr_mt_platform_mgmt_plan`
312+
- :ndf:`copy('status', need_id='wf__platform__cr_mt_platform_mgmt_plan')`
313313
- `#316 <https://github.com/eclipse-score/score/issues/316>`_
314314
- :doc:`quality_management`
315315
- not started
@@ -322,8 +322,8 @@ Functional Safety Management SW Platform Work Products
322322
- established
323323

324324
* - :need:`wp__platform_mgmt`
325-
- :need:`wf__cr_mt_platform_mngmt_plan`
326-
- :ndf:`copy('status', need_id='wf__cr_mt_platform_mngmt_plan')`
325+
- :need:`wf__platform__cr_mt_platform_mgmt_plan`
326+
- :ndf:`copy('status', need_id='wf__platform__cr_mt_platform_mgmt_plan')`
327327
- `#540 <https://github.com/eclipse-score/score/issues/540>`_
328328
- :doc:`index`
329329
- :ndf:`copy('status', need_id='doc__platform_mgt_plan')`
@@ -434,15 +434,15 @@ Functional Safety Management SW Platform Work Products
434434
- <automated>
435435

436436
* - :need:`wp__sw_development_plan`
437-
- :need:`wf__cr_mt_platform_mngmt_plan`
438-
- :ndf:`copy('status', need_id='wf__cr_mt_platform_mngmt_plan')`
437+
- :need:`wf__platform__cr_mt_platform_mgmt_plan`
438+
- :ndf:`copy('status', need_id='wf__platform__cr_mt_platform_mgmt_plan')`
439439
- <Link to issue>
440440
- :doc:`software_development`
441441
- not started
442442

443443
* - :need:`wp__verification__plan`
444-
- :need:`wf__cr_mt_platform_mngmt_plan`
445-
- :ndf:`copy('status', need_id='wf__cr_mt_platform_mngmt_plan')`
444+
- :need:`wf__platform__cr_mt_platform_mgmt_plan`
445+
- :ndf:`copy('status', need_id='wf__platform__cr_mt_platform_mgmt_plan')`
446446
- <Link to issue>
447447
- :doc:`software_verification`
448448
- not started

‎docs/platform_management_plan/software_verification.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ The following types of integrations are applicable:
9999
#. **New software elements** get integrated according to the :need:`gd_guidl__contr_request_guideline`
100100
#. **Fixes of defects** get integrated based on their prioritization described by the
101101
:doc:`problem_resolution`.
102-
#. **Changes** get integrated based on the :need:`wf__cr_dc_changerequest` and will follow
102+
#. **Changes** get integrated based on the :need:`wf__change__cr_an_change_request` and will follow
103103
the :need:`gd_guidl__pull_request_guideline` as any other artifact.
104104

105105
Levels of integration and verification

‎docs/process/process_areas/documentation_management/documentation_concept.rst

+85
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
Concept
16+
-------
17+
18+
.. doc_concept:: Documentation Management Concept
19+
:id: doc_concept__documentation__process
20+
:status: valid
21+
22+
In this section a concept for the documentation management will be discussed.
23+
Inputs for this concepts are mainly the requirements of ISO26262 "Part 2: Management of functional safety"
24+
and "Part 8: Supporting processes".
25+
26+
Key concept
27+
^^^^^^^^^^^
28+
The Documentation Management Plan should define the strategy to manage the identifed documentations
29+
in an effective and repeatable way for the project life cycle.
30+
31+
32+
Inputs
33+
^^^^^^
34+
35+
#. Stakeholders for the documentation work products?
36+
#. What tooling do we need?
37+
#. Which guidance for the work products do we have?
38+
39+
Stakeholders
40+
^^^^^^^^^^^^
41+
42+
#. :need:`Contributor <rl__contributor>`
43+
#. :need:`Committer <rl__committer>`
44+
45+
* contributing and approving documents
46+
47+
#. :need:`Technical Lead <rl__technical_lead>`
48+
49+
* planning and status reporting of work products and their documentation for the platform
50+
51+
#. :need:`Module Lead <rl__module_lead>`
52+
53+
* planning and status reporting of work products and their documentation for modules
54+
55+
#. :need:`Safety Manager <rl__safety_manager>`
56+
57+
* wants to know when the safety related documents are ready for a release
58+
* wants to know who was the author and approver of a document in case of safety issues
59+
60+
#. :need:`Security Manager <rl__security_manager>`
61+
62+
* wants to know when the security related documents are ready for a release
63+
* wants to know who was the author and approver of a document in case of security issues
64+
65+
#. :need:`Quality Manager <rl__quality_manager>`
66+
67+
* wants to know when the quality related documents are ready for a release
68+
* wants to know who was the author and approver of a document in case of quality issues
69+
70+
Document Management Tooling
71+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
72+
73+
For the document attributes to be manually set, `sphinx-needs <https://www.sphinx-needs.com/>`_ will be used.
74+
75+
For the versioning and version history `github <https://github.com/>`_ is used.
76+
77+
For the automated attributes additional tooling is created (see :doc:`guidance/documentation_process_reqs`)
78+
79+
80+
Guidance
81+
--------
82+
83+
The document management guideline can be found here :need:`gd_guidl__documentation`.
84+
85+
Some process requirements to be automated are available here :ref:`documentation_process_requirements`.

‎docs/process/process_areas/documentation_management/documentation_getstrt.rst

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
Getting Started
16+
###############
17+
18+
.. doc_getstrt:: Documentation Management Get Started
19+
:id: doc_getstrt__documentation__process
20+
:status: valid
21+
22+
In case you are appointed as a :need:`Technical Lead <rl__technical_lead>` by the :need:`rl__project_lead` in the S-CORE project:
23+
24+
* On platform level, process community already provided a draft documentation management plan,
25+
see :need:`doc__documentation_mgt_plan`, just set it to "valid"
26+
* On module level, create a documentation management plan using the platform one as a template
27+
* On both levels: make sure only the documents in your scope appear in the documents list within the plan

‎docs/process/process_areas/documentation_management/documentation_roles.rst

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
Roles
16+
#####
17+
18+
For documentation management no additional roles need to be defined.
19+
20+
Contributing Roles:
21+
22+
* :need:`Contributor <rl__contributor>`
23+
* :need:`Committer <rl__committer>`
24+
* :need:`Technical Lead <rl__technical_lead>`
25+
* :need:`Module Project Lead <rl__module_lead>`
26+
* :need:`Safety Manager <rl__safety_manager>`
27+
* :need:`Security Manager <rl__security_manager>`
28+
* :need:`Quality Manager <rl__quality_manager>`
29+
30+
A detailed overview of the responsibility for the steps of the documentation management is listed here:
31+
32+
:need:`wf__platform__cr_mt_platform_mgmt_plan`

‎docs/process/process_areas/documentation_management/documentation_workflow.rst

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
16+
Workflow Documentation Management
17+
#################################
18+
19+
The main work product is the documentation management plan, which is a part of the platform
20+
management plan. Thus the work flow :need:`wf__platform__cr_mt_platform_mgmt_plan` applies.
21+
22+
The documentation management plan should contain the strategy to manage the identified
23+
documentations in an effective and repeatable way for the project life cycle.

‎docs/process/process_areas/documentation_management/documentation_workproducts.rst

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
Work Products Documentation Management
16+
######################################
17+
18+
.. workproduct:: Documentation Management Plan
19+
:id: wp__document_mgt_plan
20+
:status: valid
21+
:complies: std_wp__iso26262__support_1051, std_wp__iso26262__support_1052
22+
23+
Document Management Plan (Part of the Platform Management Plan)
24+
25+
Defines the documentation strategy which covers the following aspects:
26+
27+
* What is documented where and when?
28+
* How to review, update, (re-)approve documentations?
29+
* What is the status of a document and how are changes identified?
30+
* How to ensure the avaibility of the documents over time?
31+
* How to ensure the controlled distribution of documents?
32+
* How to avoid distribution of obsolete documents?
33+
* Which formal elements are used?

‎docs/process/process_areas/documentation_management/guidance/documentation_checklist.rst

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
Checklists
16+
##########
17+
18+
.. gd_chklst:: Documentation Review Checklist
19+
:id: gd_chklst__documentation__review
20+
:status: valid
21+
:complies:
22+
23+
| **1. Purpose**
24+
| The purpose of this checklist is to collect the formal topics to be checked during a
25+
Documentation Review from any contributor. It will not be filled out but considered during
26+
the review.
27+
|
28+
| **2. Checklist**
29+
|
30+
31+
.. list-table:: Documentation Review Checklist
32+
:header-rows: 1
33+
:widths: 10,30,6
34+
35+
* - Id
36+
- Topic
37+
- Status [FAIL|PASS]
38+
* - 1
39+
- Does the Document has an unique id as specified?
40+
-
41+
42+
* - 2
43+
- Does the Document has a date?
44+
-
45+
46+
* - 3
47+
- Does the Document has a author information?
48+
-
49+
50+
* - 4
51+
- Does the Document has a lifecycle, status as specified?
52+
-
53+
54+
* - 5
55+
- Does the Document has a reviewer?
56+
-
57+
58+
* - 6
59+
- Does the Document has a approver?
60+
-
61+
62+
* - 7
63+
- Does the Document has a versioning, baseline as specified?
64+
-
65+
66+
* - 8
67+
- Does the Document has a versioning, baseline as specified?
68+
-
69+
70+
* - 9
71+
- Does the Document has the correct storage location?
72+
-

0 commit comments

Comments
 (0)