process: Python Coding Guidelines

docs/process/process_areas/implementation/guidance/cpp/code_analysis.rst → docs/contribute/development/cpp/code_analysis.rst

@@ -15,18 +15,17 @@
 Code Analysis C++
 #################
 
-.. gd_guidl:: Static Code Analysis
-   :id: gd_guidl__cpp__code_analysis
+.. document:: Static Code Analysis C++
+   :id: doc__cpp__code_analysis
    :status: valid
-   :complies: std_req__iso26262__software_541, std_req__iso26262__software_542, std_req__iso26262__software_543, std_req__iso26262__software_942
 
    Guideline for Static Code Analysis
 
 Static Code Analysis
 ====================
-In order to fulfil the S-CORE related standard requirements a concept for *Static Code Analysis* needs to be established. Input for the analysis is based upon *MISRA* and *ISO26262* standards in accordance to the :need:`gd_guidl__cpp_coding_guidelines`.
+In order to fulfil the S-CORE related standard requirements a concept for *Static Code Analysis* needs to be established. Input for the analysis is based upon *MISRA* and *ISO26262* standards in accordance to the :need:`doc__cpp_coding_guidelines`.
 
-Checking those rules can partially be automated and implemented by a combination of different tools. Thus a mapping needs to be established which provides a linkage of all *MISRA* requirements to the respective tool requirements/rules. For *MISRA C++:2023* this mapping is established: :need:`here <gd_guidl__cpp__misra2023_rule_mapping>`
+Checking those rules can partially be automated and implemented by a combination of different tools. Thus a mapping needs to be established which provides a linkage of all *MISRA* requirements to the respective tool requirements/rules. For *MISRA C++:2023* this mapping is established: :need:`here <doc__cpp__misra2023_rule_mapping>`
 
 .. needuml::
 

docs/process/process_areas/implementation/guidance/cpp/coding_guidelines.rst → docs/contribute/development/cpp/coding_guidelines.rst

@@ -15,10 +15,9 @@
 Writing C++ Code
 ################
 
-.. gd_guidl:: Coding Guidelines CPP
-   :id: gd_guidl__cpp_coding_guidelines
+.. document:: Coding Guidelines C++
+   :id: doc__cpp_coding_guidelines
    :status: valid
-   :complies: std_req__iso26262__software_541, std_req__iso26262__software_542, std_req__iso26262__software_543
 
 Coding Guidelines
 =================

docs/process/process_areas/implementation/guidance/cpp/misra_2023_rule_mapping.rst → docs/contribute/development/cpp/misra_2023_rule_mapping.rst

@@ -15,10 +15,9 @@
 MISRA C++:2023 Rule Mapping
 ###########################
 
-.. gd_guidl:: MISRA C++:2023 Rule Mapping
-   :id: gd_guidl__cpp__misra2023_rule_mapping
+.. document:: MISRA C++:2023 Rule Mapping
+   :id: doc__cpp__misra2023_rule_mapping
    :status: draft
-   :complies: std_req__iso26262__software_541, std_req__iso26262__software_542, std_req__iso26262__software_543, std_req__iso26262__software_942
 
 ..
     .. csv-table:: MISRA C++:2023 Rule Mapping

docs/contribute/development/index.rst

@@ -19,4 +19,6 @@ Development
    :maxdepth: 1
 
    development_environment
-
+   cpp/index
+   rust/index
+   python/index

docs/contribute/development/python/coding_guidelines.rst

@@ -0,0 +1,86 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2025 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
+   # *******************************************************************************
+
+Writing Python Code
+###################
+
+.. document:: Coding Guidelines Python
+   :id: doc__python_coding_guidelines
+   :status: valid
+
+Coding Guidelines
+=================
+.. warning:: Python is not meant to be used directly in safety critical systems. The following guidelines are only meant for tooling.
+   Every tool written will need to be evaluated for safety criticallity (TCL).
+
+
+**Consistency within score matters more than personal preference**.
+
+The art lies in balancing completeness of this document vs keeping it short, since frankly, no one
+will read a long document. Let's focus on issues that actively come up in real life and are worth
+discussing and agreeing upon, not on things that *might* be important.
+
+We don't want to write a book here. And we don't have to, since Python is not used for safety
+critical systems. However, to provide sufficient argumentation for code quality when it comes to
+tool qualification it is necessary to have and actively use guidelines.
+
+This guide is a **living document**—keep it concise, relevant, and practical.
+
+We assume basic programming and software-engineering know-how and will not repeat basics here! Go
+ask Google or ChatGPT. Or one of these established Python best practice websites:
+
+- [PEP 8](https://pep8.org/)
+- [The Hitchhiker's Guide to Python](https://docs.python-guide.org/)
+- [Real Python](https://realpython.com/)
+
+Comments
+--------
+- The first rule of comments is to write them **only when something is worth explaining**.
+- Comments should explain *why* the code does something, not *what* it does.
+- Avoid redundant comments: if the code is clear enough, a comment is not needed.
+- Take the user's perspective when writing docstrings
+
+Testing
+-------
+- **Readability:** For some reason, people tend to forget all they have ever learned about
+  readability when writing tests. **Tests do not have tests.** They must be even more readable than
+  production code!
+- **Mocking is an anti-pattern.** Well... it's complex. We don't want to write a book on mocking
+  here. Just really, really consider whether mocking is the best approach. - Favor dependency
+  injection and lightweight fixtures over excessive mocking. Mocks should not replace proper
+  design.
+- **Do not test every single function or class!** Instead: - Focus on testing *behavior*, not
+  implementation details. Overly fine-grained tests lead to brittle code and high maintenance.
+- **Boundary conditions:** - Edge cases often break things. Think about invalid input, large data
+  sets, empty cases, and concurrency issues.
+
+Documentation
+--------------------
+- If your documentation doesn't fit into a comment, create a `README.md` in the directory of the
+  tool.
+- `README.md` should explain the overall architecture and key design decisions.
+- If the design impacts multiple components, consider an architecture diagram.
+- User-facing documentation is stored under `docs/guidance`.
+
+
+Tools & Versions
+================
+
+We're using Python, Ruff (linting & formatting), Pyright (linting) and pytest for our tooling. The
+versions are managed by the infrastructure community and will be updated as frequently as possible.
+The configuration is managed by infrastructure and process communities.
+
+*Compliance to all tools is mandatory, and will be enforced by pull request checks.*
+
+Currently we do NOT aim at supporting older Python versions.

docs/contribute/development/python/index.rst

@@ -0,0 +1,21 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2025 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
+   # *******************************************************************************
+
+Python
+######
+
+.. toctree::
+   :maxdepth: 1
+
+   coding_guidelines

docs/contribute/development/rust/coding_guidelines.rst

@@ -0,0 +1,22 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2025 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
+   # *******************************************************************************
+
+Writing Rust Code
+#################
+
+.. document:: Coding Guidelines Rust
+   :id: doc__rust_coding_guidelines
+   :status: invalid
+
+.. note:: The Rust coding guidelines are not yet defined. This is a placeholder for future content.

docs/contribute/development/rust/index.rst

@@ -0,0 +1,21 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2025 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
+   # *******************************************************************************
+
+Rust
+####
+
+.. toctree::
+   :maxdepth: 1
+
+   coding_guidelines

docs/platform_management_plan/software_development.rst

@@ -69,7 +69,7 @@ The design guideline is defined in :need:`doc_concept__imp__concept` and :need:`
 Coding guideline
 ^^^^^^^^^^^^^^^^
 
-**C++** - see :need:`gd_guidl__cpp_coding_guidelines`
+**C++** - see :need:`doc__cpp_coding_guidelines`
 
 **Rust** - state of the art open source Rust guidelines are currently developed by `Safety Critical Rust Consortium <https://github.com/rustfoundation/safety-critical-rust-consortium/>`_
 (which will be adopted by the S-CORE project)

docs/process/process_areas/implementation/guidance/implementation_guideline.rst

@@ -33,7 +33,7 @@ Detailed description which steps are need for implementation.
    In this step, the components are broken down into smaller, independent units that can be tested
    separately during the unit testing phase. The detailed design shall be so exact, that test and
    implementation can be run simultaneously.
-#. Implement the source code, by using the coding guidelines :need:`gd_guidl__cpp_coding_guidelines` for C++,
+#. Implement the source code, by using the coding guidelines :need:`doc__cpp_coding_guidelines` for C++,
    or <TBD> for Rust.
 #. Create a pull request for your change.
 #. Detail Design and Code Inspection is done to review the code of the software and detect errors in it.

docs/process/process_areas/implementation/guidance/index.rst

@@ -19,7 +19,6 @@ Guidance
    :maxdepth: 1
 
    implementation_guideline
-   cpp/index
    implementation_checklist
    detailed_design_template
    implementation_process_reqs