From ebce35944787f86f5130d448d608c6df7247cc8b Mon Sep 17 00:00:00 2001 From: Jochen Hoenle Date: Tue, 25 Feb 2025 15:08:38 +0100 Subject: [PATCH] docs: restructure general guidelines move all general guidance documents into one folder tutorial --- docs/{guidance => contribute/ci}/index.rst | 7 +- .../ci}/publishing-gh-pages.rst | 0 ...ore_contribution_request_simple.drawio.svg | 0 ...e_contribution_request_standard.drawio.svg | 0 ...core_discussion_request_options.drawio.svg | 0 .../contribution_request.rst} | 6 +- .../contribution_request}/index.rst | 14 +--- .../templates/feature_request_template.rst | 2 +- .../contribution_request/templates/index.rst | 6 +- docs/contribute/development/index.rst | 20 +++++ .../assets/docs-as-code/drawio-editing.png | Bin .../assets/docs-as-code/example.drawio.svg | 0 .../assets/docs-as-code/example.puml | 0 .../documentation}/docs-as-code.rst | 4 +- docs/contribute/documentation/index.rst | 21 +++++ .../general/feature_flags.rst} | 2 + .../general/folder.rst} | 47 +---------- .../index.rst => contribute/general/git.rst} | 0 docs/contribute/general/index.rst | 24 ++++++ docs/contribute/general/naming.rst | 75 ++++++++++++++++++ .../guidance/branch => contribute}/index.rst | 31 +++----- docs/index.rst | 6 +- docs/process/index.rst | 15 +--- 23 files changed, 173 insertions(+), 107 deletions(-) rename docs/{guidance => contribute/ci}/index.rst (92%) rename docs/{guidance => contribute/ci}/publishing-gh-pages.rst (100%) rename docs/{process/guidance => contribute}/contribution_request/_assets/score_contribution_request_simple.drawio.svg (100%) rename docs/{process/guidance => contribute}/contribution_request/_assets/score_contribution_request_standard.drawio.svg (100%) rename docs/{process/guidance => contribute}/contribution_request/_assets/score_discussion_request_options.drawio.svg (100%) rename docs/{process/guidance/contribution_request/index.rst => contribute/contribution_request/contribution_request.rst} (99%) rename docs/{process/guidance => contribute/contribution_request}/index.rst (77%) rename docs/{process/guidance => contribute}/contribution_request/templates/feature_request_template.rst (97%) rename docs/{process/guidance => contribute}/contribution_request/templates/index.rst (89%) create mode 100644 docs/contribute/development/index.rst rename docs/{guidance => contribute/documentation}/assets/docs-as-code/drawio-editing.png (100%) rename docs/{guidance => contribute/documentation}/assets/docs-as-code/example.drawio.svg (100%) rename docs/{guidance => contribute/documentation}/assets/docs-as-code/example.puml (100%) rename docs/{guidance => contribute/documentation}/docs-as-code.rst (98%) create mode 100644 docs/contribute/documentation/index.rst rename docs/{process/guidance/feature_flags/index.rst => contribute/general/feature_flags.rst} (99%) rename docs/{process/guidance/general/index.rst => contribute/general/folder.rst} (87%) rename docs/{process/guidance/git/index.rst => contribute/general/git.rst} (100%) create mode 100644 docs/contribute/general/index.rst create mode 100644 docs/contribute/general/naming.rst rename docs/{process/guidance/branch => contribute}/index.rst (52%) diff --git a/docs/guidance/index.rst b/docs/contribute/ci/index.rst similarity index 92% rename from docs/guidance/index.rst rename to docs/contribute/ci/index.rst index f96f513b3a..bd854b1789 100644 --- a/docs/guidance/index.rst +++ b/docs/contribute/ci/index.rst @@ -12,11 +12,10 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Guidance -======== +CI +## .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - docs-as-code publishing-gh-pages diff --git a/docs/guidance/publishing-gh-pages.rst b/docs/contribute/ci/publishing-gh-pages.rst similarity index 100% rename from docs/guidance/publishing-gh-pages.rst rename to docs/contribute/ci/publishing-gh-pages.rst diff --git a/docs/process/guidance/contribution_request/_assets/score_contribution_request_simple.drawio.svg b/docs/contribute/contribution_request/_assets/score_contribution_request_simple.drawio.svg similarity index 100% rename from docs/process/guidance/contribution_request/_assets/score_contribution_request_simple.drawio.svg rename to docs/contribute/contribution_request/_assets/score_contribution_request_simple.drawio.svg diff --git a/docs/process/guidance/contribution_request/_assets/score_contribution_request_standard.drawio.svg b/docs/contribute/contribution_request/_assets/score_contribution_request_standard.drawio.svg similarity index 100% rename from docs/process/guidance/contribution_request/_assets/score_contribution_request_standard.drawio.svg rename to docs/contribute/contribution_request/_assets/score_contribution_request_standard.drawio.svg diff --git a/docs/process/guidance/contribution_request/_assets/score_discussion_request_options.drawio.svg b/docs/contribute/contribution_request/_assets/score_discussion_request_options.drawio.svg similarity index 100% rename from docs/process/guidance/contribution_request/_assets/score_discussion_request_options.drawio.svg rename to docs/contribute/contribution_request/_assets/score_discussion_request_options.drawio.svg diff --git a/docs/process/guidance/contribution_request/index.rst b/docs/contribute/contribution_request/contribution_request.rst similarity index 99% rename from docs/process/guidance/contribution_request/index.rst rename to docs/contribute/contribution_request/contribution_request.rst index a356cfc751..55e090943f 100644 --- a/docs/process/guidance/contribution_request/index.rst +++ b/docs/contribute/contribution_request/contribution_request.rst @@ -12,9 +12,9 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -############################### - Contribution Request Guideline -############################### + +Contribution Request Guideline +############################## .. gd_guidl:: Contribution Request Guideline :id: gd_guidl__contr_request_guideline diff --git a/docs/process/guidance/index.rst b/docs/contribute/contribution_request/index.rst similarity index 77% rename from docs/process/guidance/index.rst rename to docs/contribute/contribution_request/index.rst index d7ec454806..77dc45a69e 100644 --- a/docs/process/guidance/index.rst +++ b/docs/contribute/contribution_request/index.rst @@ -12,18 +12,10 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. _process_guidance: - -######### - Guidance -######### +Contribution Request +#################### .. toctree:: :maxdepth: 1 - :glob: - git/index.rst - branch/index.rst - feature_flags/index.rst - general/index.rst - contribution_request/index.rst + contribution_request diff --git a/docs/process/guidance/contribution_request/templates/feature_request_template.rst b/docs/contribute/contribution_request/templates/feature_request_template.rst similarity index 97% rename from docs/process/guidance/contribution_request/templates/feature_request_template.rst rename to docs/contribute/contribution_request/templates/feature_request_template.rst index c72927aae0..2277dee4b1 100644 --- a/docs/process/guidance/contribution_request/templates/feature_request_template.rst +++ b/docs/contribute/contribution_request/templates/feature_request_template.rst @@ -55,7 +55,7 @@ To activate this feature, use the following feature flag: .. note:: The feature flag must reflect the feature name in snake_case. Further, it is prepended with ``experimental_``, as - long as the feature is not yet stable. See :doc:`/process/guidance/feature_flags/index` for more information. + long as the feature is not yet stable. See :ref:`feature_flags` for more information. Abstract diff --git a/docs/process/guidance/contribution_request/templates/index.rst b/docs/contribute/contribution_request/templates/index.rst similarity index 89% rename from docs/process/guidance/contribution_request/templates/index.rst rename to docs/contribute/contribution_request/templates/index.rst index b7878be66e..5f873f6a4e 100644 --- a/docs/process/guidance/contribution_request/templates/index.rst +++ b/docs/contribute/contribution_request/templates/index.rst @@ -14,12 +14,10 @@ .. _contribution_templates: -####################### - Contribution Templates -####################### +Contribution Templates +###################### .. toctree:: :maxdepth: 1 - :glob: feature_request_template.rst diff --git a/docs/contribute/development/index.rst b/docs/contribute/development/index.rst new file mode 100644 index 0000000000..8d4c9630ca --- /dev/null +++ b/docs/contribute/development/index.rst @@ -0,0 +1,20 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Development +########### + +.. toctree:: + :maxdepth: 1 + diff --git a/docs/guidance/assets/docs-as-code/drawio-editing.png b/docs/contribute/documentation/assets/docs-as-code/drawio-editing.png similarity index 100% rename from docs/guidance/assets/docs-as-code/drawio-editing.png rename to docs/contribute/documentation/assets/docs-as-code/drawio-editing.png diff --git a/docs/guidance/assets/docs-as-code/example.drawio.svg b/docs/contribute/documentation/assets/docs-as-code/example.drawio.svg similarity index 100% rename from docs/guidance/assets/docs-as-code/example.drawio.svg rename to docs/contribute/documentation/assets/docs-as-code/example.drawio.svg diff --git a/docs/guidance/assets/docs-as-code/example.puml b/docs/contribute/documentation/assets/docs-as-code/example.puml similarity index 100% rename from docs/guidance/assets/docs-as-code/example.puml rename to docs/contribute/documentation/assets/docs-as-code/example.puml diff --git a/docs/guidance/docs-as-code.rst b/docs/contribute/documentation/docs-as-code.rst similarity index 98% rename from docs/guidance/docs-as-code.rst rename to docs/contribute/documentation/docs-as-code.rst index 9f9b772d0e..cf76f8a693 100644 --- a/docs/guidance/docs-as-code.rst +++ b/docs/contribute/documentation/docs-as-code.rst @@ -12,8 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Guidance: Docs-As-Code -====================== +Docs-As-Code +============ Introduction ------------ diff --git a/docs/contribute/documentation/index.rst b/docs/contribute/documentation/index.rst new file mode 100644 index 0000000000..64fd22b4e5 --- /dev/null +++ b/docs/contribute/documentation/index.rst @@ -0,0 +1,21 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Documentation +############# + +.. toctree:: + :maxdepth: 1 + + docs-as-code diff --git a/docs/process/guidance/feature_flags/index.rst b/docs/contribute/general/feature_flags.rst similarity index 99% rename from docs/process/guidance/feature_flags/index.rst rename to docs/contribute/general/feature_flags.rst index b838b77a71..f43e7e9fa0 100644 --- a/docs/process/guidance/feature_flags/index.rst +++ b/docs/contribute/general/feature_flags.rst @@ -12,6 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _feature_flags: + Feature Flags ============= diff --git a/docs/process/guidance/general/index.rst b/docs/contribute/general/folder.rst similarity index 87% rename from docs/process/guidance/general/index.rst rename to docs/contribute/general/folder.rst index 25472879e1..4f45c82d0a 100644 --- a/docs/process/guidance/general/index.rst +++ b/docs/contribute/general/folder.rst @@ -12,51 +12,10 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -General -======= - -.. _naming_convention_files: - -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). - -.. _naming_convention_needs: - -Naming Convention for UIDs --------------------------- - -The naming convention for the UIDs of **all** elements shall be defined as follows: - -* It should not exceed 30 characters -* It shall show a meaningful name -* It shall only consist of lowercase, digits and underscores - -For the naming of the UIDs also following convention shall be applied: - -* It shall consist of 3 parts separated by double underscore - * | prefix - | (defined in the Metamodel) - * | structural element - | (e.g. abbreviation for the feature / subfeature) - * | keyword (s) - | (keyword(s) referring the the description, separated by underscore) - -As examples: - -* feat_req__ipc__e2e_protection -* comp_req__kvs__storage - -Only for **process UIDs** the structural element is optional: - -* gd_temp__review -* gd_req__req__structure - .. _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. @@ -138,7 +97,3 @@ can be in a different order. registry/ -> infrastructure configuration README.md -> Entrypoint of the repository. - -.. toctree:: - :maxdepth: 1 - :glob: diff --git a/docs/process/guidance/git/index.rst b/docs/contribute/general/git.rst similarity index 100% rename from docs/process/guidance/git/index.rst rename to docs/contribute/general/git.rst diff --git a/docs/contribute/general/index.rst b/docs/contribute/general/index.rst new file mode 100644 index 0000000000..aa61407d49 --- /dev/null +++ b/docs/contribute/general/index.rst @@ -0,0 +1,24 @@ +.. + # ******************************************************************************* + # 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 +####### + +.. toctree:: + :maxdepth: 1 + + naming + git + folder + feature_flags diff --git a/docs/contribute/general/naming.rst b/docs/contribute/general/naming.rst new file mode 100644 index 0000000000..55955fdf3c --- /dev/null +++ b/docs/contribute/general/naming.rst @@ -0,0 +1,75 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Naming Conventions +================== + +.. _naming_convention_files: + +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). + +.. _naming_convention_needs: + +Naming Convention for UIDs +-------------------------- + +The naming convention for the UIDs of **all** elements shall be defined as follows: + +* It should not exceed 30 characters +* It shall show a meaningful name +* It shall only consist of lowercase, digits and underscores + +For the naming of the UIDs also following convention shall be applied: + +* It shall consist of 3 parts separated by double underscore + * | prefix + | (defined in the Metamodel) + * | structural element + | (e.g. abbreviation for the feature / subfeature) + * | keyword (s) + | (keyword(s) referring the the description, separated by underscore) + +As examples: + +* feat_req__ipc__e2e_protection +* comp_req__kvs__storage + +Only for **process UIDs** the structural element is optional: + +* gd_temp__review +* gd_req__req__structure + +.. _branch_naming: + +Naming convention for git branches +---------------------------------- + +In order to keep an overview which branch belongs to whom the branch +name also should be descriptive. The following rules shall apply: + +#. The branch name shall start with your github username. This will make + it easier for everybody to identify the owner of the branch. +#. Branch names must be lower case. +#. Concatenation is done by underscores _. + +An example could look like this: + +Mustermann, GitHub Name: maximuster + +.. code:: + + maximuster_my_awesome_branch_name diff --git a/docs/process/guidance/branch/index.rst b/docs/contribute/index.rst similarity index 52% rename from docs/process/guidance/branch/index.rst rename to docs/contribute/index.rst index 590a15189f..1b060917e1 100644 --- a/docs/process/guidance/branch/index.rst +++ b/docs/contribute/index.rst @@ -12,28 +12,17 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -########## - Branches -########## - -.. _branch_naming: - -******************* - Naming Convention -******************* +.. _contribute: -In order to keep an overview which branch belongs to whom the branch -name also should be descriptive. The following rules shall apply: - -#. The branch name shall start with your github username. This will make - it easier for everybody to identify the owner of the branch. -#. Branch names must be lower case. -#. Concatenation is done by underscores _. - -An example could look like this: +Contribute +########## -Mustermann, GitHub Name: maximuster +.. toctree:: + :maxdepth: 2 -.. code:: + general/index + contribution_request/index + documentation/index + development/index + ci/index - maximuster_my_awesome_branch_name diff --git a/docs/index.rst b/docs/index.rst index 0dcf213f23..16a99daa52 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -118,7 +118,7 @@ Project structure and processes ^^^ Understand how we work, by reading our :ref:`Process description `. And receive tips & tricks for our used tool stack by reading the - :ref:`Guidance `. + :ref:`contribute`. .. grid-item-card:: @@ -131,11 +131,11 @@ Project structure and processes .. dropdown:: Click to see the complete sitemap .. toctree:: - :maxdepth: 3 + :maxdepth: 1 requirements/index features/index - guidance/index + contribute/index Releases process/index PMP diff --git a/docs/process/index.rst b/docs/process/index.rst index 0bcad4ae5d..bbf202119b 100644 --- a/docs/process/index.rst +++ b/docs/process/index.rst @@ -42,7 +42,6 @@ The process description for the SCORE project (e.g. requirements, architecture, .. toctree:: :maxdepth: 1 - :glob: process_areas/index.rst @@ -52,7 +51,6 @@ Process Role definition .. toctree:: :maxdepth: 1 - :glob: roles/index.rst @@ -61,7 +59,6 @@ Workproducts .. toctree:: :maxdepth: 1 - :glob: workproducts/index.rst @@ -70,20 +67,15 @@ Workflows .. toctree:: :maxdepth: 1 - :glob: workflows/index.rst -Process Guidances +How To Contribute ----------------- -The guidance for the SCORE project (e.g. templates, guidelines, checklists) can be found here: +How to contribute to the SCORE project (e.g. naming convention, folder structure, IDE setup) can be found here: -.. toctree:: - :maxdepth: 1 - :glob: - - guidance/index.rst +:ref:`contribute` Standards --------- @@ -92,6 +84,5 @@ The the standard references the SCORE project's processes are derived from can b .. toctree:: :maxdepth: 1 - :glob: standards/index.rst