Skip to content

Commit beb1f69

Browse files
pahmannantonkri
pahmann
authored and
antonkri
committed
process: correct typos
Issue-ref: resolves eclipse-score#21 Signed-off-by: Philipp Ahmann <philipp.ahmann@de.bosch.com>
0 parents  commit beb1f69

File tree

6 files changed

+454
-0
lines changed

6 files changed

+454
-0
lines changed

‎docs/process/guidelines/branch/index.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2024 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+
Branches
17+
##########
18+
19+
*******************
20+
Naming Convention
21+
*******************
22+
23+
In order to keep an overview which branch belongs to whom the branch
24+
name also should be descriptive. The following rules shall apply:
25+
26+
#. The branch name shall start with your github username. This will make
27+
it easier for everybody to identify the owner of the branch.
28+
#. Branch names must be lower case.
29+
#. Concatenation is done by underscores _.
30+
31+
An example could look like this:
32+
33+
Mustermann, GitHub Name: maximuster
34+
35+
.. code::
36+
37+
maximuster_my_awesome_branch_name

‎docs/process/guidelines/general/index.rst‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2024 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+
General
16+
=======
17+
18+
Naming Conventions of Files
19+
---------------------------
20+
21+
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).
22+
23+
.. _Platform_Folder_Structure:
24+
25+
Folder Structure of Platform Repository
26+
---------------------------------------
27+
28+
The following shows the folder structure of the platform repository (ordered alphabetically). The ordering of the documentation in the rendered documentation
29+
can be in a different order.
30+
31+
.. code-block:: text
32+
33+
docs/ -> Global documentation of the platform.
34+
concepts/ -> Description of overall concepts.
35+
glossary/ -> Glossary of abbreviations used in the platform context.
36+
guidelines/ -> Guidelines regarding ...
37+
architecture/ -> ... architecture, e.g., documentation and tracing.
38+
coding/ -> ... coding rules, style, formatting, best practices for the languages C++, Rust & Python.
39+
detailed_design/ -> ... detailed design of the software components.
40+
general/ -> ... general topics, e.g. naming conventions or the folder structure.
41+
integration/ -> ... platform integration manual
42+
tutorials/ -> ... general tutorials.
43+
44+
overview/ -> Introduction and high-level description of the platform features.
45+
platform_management_plan/ -> Overall Platform Management Plan [WP_PLATFORM_MGMT], consisting of ...
46+
project_management.rst -> ... Project Management.
47+
stakeholder_management.rst -> ... Stakeholder Management.
48+
safety_management.rst -> ... Safety Management incl. platform safety plan [WP_PLATFORM_SAFETY_PLAN]
49+
risk_management.rst -> ... Risk Management.
50+
quality_management.rst -> ... Quality Management [WP_QMS].
51+
config_management.rst -> ... Configuration Management.
52+
tool_management.rst -> ... Tool Management.
53+
release_management.rst -> ... Release Management.
54+
problem_resolution.rst -> ... Problem Management.
55+
change_management.rst -> ... Change Management.
56+
requirements_management.rst -> ... Requirements Management.
57+
software_development.rst -> ... Development [WP_SW_DEV_PLAN].
58+
software_verification.rst -> ... Verification [WP_VERIFICATION_PLAN].
59+
documentation_management.rst -> ... Documentation Management.
60+
release/ -> [WP_PLATFORM SW_RELEASE_NOTE]
61+
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]
62+
stakeholder_requirements/ -> Stakeholder requirements of the platform [WP_STAKEHOLDER_REQ].
63+
64+
examples/ -> examples how a C++, Rust, Python module can be set up
65+
66+
features/ -> All features of the platform.
67+
<feature-name>/ -> Folder containing all sub-folders corresponding to one feature and the contribution request [WP_CONT_REQUEST]
68+
docs/ -> Documentation of the feature consisting of ...
69+
architecture/ -> ... Feature architecture [WP_FEATURE_ARCHITECTURE].
70+
requirements/ -> ... Feature requirements [WP_FEATURE_REQ].
71+
safety_analysis/ -> ... Safety analysis on feature level [WP_SW_FEAT_SAFETY_ANALYSES]
72+
safety_planning/ -> ... the feature specific safety workproducts planning
73+
verification/ -> ... Feature verification report (reporting all feature verifications) [WP_SW_VERIFICATION_REPORT]
74+
tests/ -> Feature tests, consisting of ...
75+
integration-tests/ -> ... integration tests [WP_SW_INTEGRATION_TEST].
76+
toolchain/ -> Definition of toolchain incl. their requirements [WP_TOOL_REQ]
77+
78+
modules/ -> Modules of the SW platform.
79+
<module-name>/ -> Folder containing all artifacts corresponding to one module.
80+
docs/ -> Documentation of the module consisting of ...
81+
manual/ -> ... Module manual, e.g. integration manual, assumptions of use and safety manual [WP_SW_AOU], [WP_SW_SAFTEY_MANUAL].
82+
release/ -> ... Module release note [WP_PLATFORM SW_RELEASE_NOTE] plus safety assessment [WP_ASSESSMENT_REPORT]
83+
safety_plan/ -> ... Module safety plan [WP_PLATFORM_SAFETY_PLAN], module safety case [WP_PLATFORM_SAFETY_CASE] and their conformance reviews [WP_CMR_REPORTS]
84+
safety_analysis/ -> ... Safety analysis on module level [WP_SW_COMP_DFA]
85+
verification/ -> ... Module verification report (reporting all module's components verifications) [WP_SW_VERIFICATION_REPORT] plus safety analysis conformance reviews [WP_CMR_REPORTS]
86+
87+
components/ -> Components of the module.
88+
<component-name>/ -> Folder containing all artifacts corresponding to one component.
89+
docs/ -> Documentation of the component consisting of ...
90+
architecture/ -> ... Component architecture (only if sub-components exist) [WP_SW_COMPONENTS_ARCHITECTURE].
91+
requirements/ -> ... Component requirements [WP_SW_COMP_REQ] and HSI (if relevant) [WP_HSI].
92+
safety_analysis/ -> ... Safety analysis on component level [WP_SW_COMP_SAFETY_ANALYSES]
93+
verification/ -> ... Architecture review [WP_SW_ARCH_VERIFICATION], code inspection [WP_SW_CODE_INSPECT]
94+
src/ -> Source files of the component (incl. detailed design) [WP_SW_IMPLEMENTATION].
95+
include/ -> Include files of the component
96+
tests/ -> Component tests, consisting of ...
97+
unit_tests/ -> ... unit tests [WP_SW_UNIT_TEST] (for lowest level of components).
98+
integration_tests/ -> ... integration tests [WP_SW_INTEGRATION_TEST].
99+
verification-tests/ -> ... verification tests [WP_SW_COMPONENT_TEST].
100+
<sub-component-name>/ -> Sub-Component of the Component.
101+
copy the relevant folders below <component-name> if applicable (example: no code inspection needed for sub-components from the Open Source)
102+
103+
platform-integration-tests/ -> Integration tests on reference hardware.
104+
105+
process/ -> process definition including workflows, workproducts, roles, guidance [WP_PROCESS_DEFINITION]
106+
107+
registry/ -> infrastructure configuration
108+
109+
README.md -> Entrypoint of the repository.
110+
111+
.. toctree::
112+
:maxdepth: 1
113+
:glob:

‎docs/process/guidelines/git/index.rst‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2024 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+
Git Guidelines
17+
################
18+
19+
***********
20+
Motivation
21+
***********
22+
23+
The commit history and especially the commit messages are part of a
24+
project's documentation. Therefore, the same rules that are valid for
25+
documentation are also valid for commits and commit messages. A commit
26+
message is written once, but read many times (especially when hunting
27+
bugs). Git supports powerful tools to find out which commit introduced a
28+
bug (e.g., git bisect, git blame). Their level of usefulness depends on
29+
the quality of the commits and their respective commit messages.
30+
31+
******************
32+
Git Configuration
33+
******************
34+
35+
Since name and e-mail address are part of the commit (and thus be part
36+
of the commit history) they shall be specified via the .gitconfig file.
37+
So this file must at least include the following lines:
38+
39+
.. code-block::
40+
41+
[user]
42+
email = <your-email-address> (e.g. max.mustermann@something.com)
43+
name = Max Mustermann
44+
45+
***************
46+
Commit History
47+
***************
48+
49+
Before merging a PR all commits shall be squashed into few (desired only
50+
one) logical commits.
51+
52+
.. note::
53+
54+
Keep in mind that upon merge the commit history of your branch will
55+
be preserved in the main branch of the repo as well.
56+
57+
**********************
58+
Commit Message Format
59+
**********************
60+
61+
In Score it is checked if git commit messages are written according
62+
to guidelines. However, it cannot enforce the meaningfulness of the
63+
message (and its parts).
64+
65+
.. note::
66+
67+
Remember that this information is shown in git log and other tools.
68+
69+
Wording
70+
=======
71+
72+
Proper English language and full sentences are to be used in the commit
73+
message. For both the subject and the body a singular imperative form is
74+
required. E.g. **"Add unit test for class XY"** and not "I added unit
75+
tests", "Adding unit tests" or "Various minor changes".
76+
77+
Additionally, the following specification for the content shall apply for
78+
commit messages (according to [Eclipse Git Commit Records](https://www.eclipse.org/projects/handbook/#resources-commit)):
79+
80+
Summary
81+
=======
82+
83+
.. code-block::
84+
85+
<prefix_name>: Summary
86+
87+
The Subject shall describe what was changed in a single line max 72
88+
characters long. It shall include a prefix for the module, component or
89+
feature which was changed e.g. "doc:" or "bazel:" It shall start with a
90+
capital letter and should not be ended by a trailing period in the
91+
subject line.
92+
93+
Good and bad examples for a subject are:
94+
95+
- **mw: Show colorful output** not Add file
96+
- **bazel: Test Requirement SWS_CM_00001** not Add test
97+
- **osal: Split responsibilities of job handling and execution** not Refactor code
98+
99+
Description
100+
===========
101+
102+
The description must contain a brief summary of the content of the
103+
commit and why this is necessary. Furthermore it must be consistent and
104+
logically complete.
105+
106+
If feasible, the commit message body should be extended with quoted
107+
material such as compiler warnings, debugger stack traces or measurement
108+
data for performance optimizations.
109+
110+
Footer
111+
======
112+
113+
At the end of the commit message a footer shall be specified
114+
in the following format:
115+
116+
.. code-block::
117+
118+
Also-by: Some Bodyelse <somebodyelse@nowhere.com>
119+
Issue-ref: <Keyword> #<IssueNr>
120+
121+
<Keyword> is specified by:
122+
123+
- see
124+
- close / closes / closed
125+
- fix / fixes / fixed
126+
- resolve / resolves / resolved
127+
128+
The Reference can contain links to multiple tickets. A detailed
129+
description of linking issues to code is available on `GitHub
130+
<https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue>`__.
131+
Be aware that keywords like (close | fix | resolve) will also close the referenced issue if the pull request is merged.
132+
133+
An additional check is implemented to suppress false positives: if a
134+
commit message has revert/merge in the first line, the linting rules
135+
will not be applied to it. Thereby headaches when performing reverts or
136+
merges are reduced.
137+
138+
Layout Summary
139+
==============
140+
141+
In short the commit message shall consist of:
142+
143+
- Summary
144+
- Empty line
145+
- Description
146+
- Empty line
147+
- Footer
148+
149+
Example
150+
=======
151+
.. code-block::
152+
153+
component: Short one line summary of change
154+
155+
More detailed explanatory text, if necessary. Wrap it to about 72
156+
characters or less. The first line is treated as the subject and the
157+
rest of the text as the body. The blank line separating the summary from
158+
the body is critical (unless you omit the body entirely);
159+
160+
- Bullet points are okay, too
161+
- Typically a hyphen or asterisk is used for the bullet, followed by a
162+
space, using a hanging indent
163+
164+
Comment how the change was tested.
165+
166+
Notes about dependencies to other tools or commits in other
167+
repositories.
168+
169+
Also-by: Some Bodyelse <somebodyelse@nowhere.com> |br|
170+
Issue-Ref: <closes #xxx>, <fixes #xxy>, ...

‎docs/process/guidelines/index.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2024 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+
.. _Configuration_Tool_Guidelines:
16+
17+
#############################
18+
Configuration/Tool Guidelines
19+
#############################
20+
21+
.. toctree::
22+
:maxdepth: 1
23+
:glob:
24+
25+
git/index.rst
26+
branch/index.rst
27+
general/index.rst

‎docs/process/index.rst‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2024 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+
.. _Process_description:
16+
17+
Process description
18+
===================
19+
20+
Processes are the basis to describe the way of working within the SCORE project.
21+
22+
Requirements engineering
23+
------------------------
24+
A key process is the Requirements engineering, which is for defining, documenting, and maintaining requirements within our SCORE project.
25+
26+
Requirements templates
27+
~~~~~~~~~~~~~~~~~~~~~~
28+
29+
.. toctree::
30+
:maxdepth: 1
31+
:glob:
32+
33+
templates/index.rst
34+
35+
Configuration/Tool management
36+
-----------------------------
37+
38+
Important from the begin are version control topics, like commit rules and naming conventions for branches.
39+
40+
Configuration/Tool guidelines
41+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
42+
43+
.. toctree::
44+
:maxdepth: 1
45+
:glob:
46+
47+
guidelines/index.rst

0 commit comments

Comments
 (0)