1  # Gitlab source control repository
  2  
  3  This project is hosted on gitlab.com and the gitlab provided features are used in the development process. People who already have a github account can also use that account to log in to gitlab. The git repository is public and can be cloned with `git` so all regular git development can be used for PDKMaster development.
  4  
  5  [Gitlab Issues](https://docs.gitlab.com/ee/user/project/issues/) are used in this project for bug tracking and feature requests. If you have problems using PDKMaster or think about possible improvements or extensions to the project anyone is free to create a new issue. No project specific policies are in place (yet) on how bugs or feature requests need to be reported.
  6  
  7  Code contributions need to de done through the [gitlab merge request feature](https://docs.gitlab.com/ee/user/project/merge_requests/). Anyone can create a merge request. Creation of the merge request will also run the [CI pipeline](https://docs.gitlab.com/ee/ci/pipelines/) on the request. Requests can only be accepted when this [CI pipeline](https://docs.gitlab.com/ee/ci/pipelines/) is passing.
  8  New requests will also be reviewed by a project maintainer. They will optionally propose some improvements to the code. After the proposed improvements are implemented a project maintainer can then merge the request into the main branch.
  9  If a merge request is considered out of scope or not in line with existing code base, a merge request may be closed without merging. For bigger code changes it does then make sense to first discuss the proposed changes in a feature request issue before actually starting the development work.  
 10  Currently merge requests can only be handled by the project maintainers on a best effort basis.
 11  
 12  # Code style
 13  
 14  For code style [PEP 8](https://pep8.org/) is mainly followed but not strictly. Line lengths above 80 are accepted; it is more around 100.
 15  
 16  There is a strong preference for multi-line brace statements to put the opening brace as last character on a line followed by the lines indented one level and then the closing brace on a separate line unindented.
 17  
 18  So:
 19  
 20  ```python
 21  val = [
 22      "one", "two", "four",
 23      "sixteen",
 24  ]
 25  ```
 26  
 27  not:
 28  
 29  ```python
 30  val = ["one", "two", "four",
 31         "sixteen"]
 32  ```
 33  
 34  or:
 35  
 36  ```python
 37  val = [
 38      "one", "two", "four",
 39      "sixteen",
 40      ]
 41  ```
 42  
 43  For method definitions `self` and optionally `*` may be left after the opening `(`; e.g.:
 44  
 45  ```python
 46  class C:
 47      ...
 48  
 49      def method(self, *,
 50          param1: int, param2: int,
 51          param3: str,
 52      )
 53  ```
 54  
 55  Typically formatting only merge requests are not accepted and the formatting of the code as first committed will be retained. Project maintainers may add a code reformatting commit before merging a merge request.
 56  
 57  For method and functions definitions normally argument passing by name is enforced by using the '*' construct. One accepted exception is when the function/method name is a verb and the parameter is the direct object of the verb; e.g.:
 58  
 59  ```python
 60  class _Layout:
 61      ...
 62  
 63      def place(self, object: "_Layout"):
 64          ...
 65  ```
 66  
 67  [Type annotations](https://docs.python.org/3/library/typing.html) are used to define the types of function & method parameters and object attributes. No run-time code is added to check types of annotated parameters and attributes; people need to rely on type checkers for conformance. Additional run-time type checks may be added if they can't be easily added using type annotations.
 68  
 69  As is discussed in [PEP 8]() non-public attributes start with a `_`. So in general no classes, functions, methods, attributes starting with a `_` should be used in user code.
 70  Some corner cases are not fully worked out yet and are further discussed in [#73](https://gitlab.com/Chips4Makers/PDKMaster/-/issues/73)
 71  
 72  # Minimal supported python version
 73  
 74  Currently, minimal supported python version is v3.8. This means that the CI pipeline runs with that version and that all commits requested to be merged have to be compatible with it.
 75  
 76  # License
 77  
 78  Contributors are allowing their code to be multi-licensed as specified in
 79  [LICENSE.md](LICENSE.md). This also means they have to fullfil the patent clauses included
 80  in any of the listed licenses. The rationale behind the multi-licensing is given in
 81  [README.md](README.md)
 82  
 83  All source files in this repository need to contain a proper `SPDX-License-Identifier` annotation; no other SPDX headers are added to the files.  
 84  For example for python files this is:
 85  
 86  ```python
 87  # SPDX-License-Identifier: AGPL-3.0-or-later OR GPL-2.0-or-later OR CERN-OHL-S-2.0+ OR Apache-2.0
 88  ```
 89  
 90  # Sign your work - the Developer’s Certificate of Origin
 91  
 92  In order for patches to be accepted in the repository of this project committers will need to certify the code by signing off their code. The commonly used 
 93  [Developer's Certificate of Origin](https://developercertificate.org/) is used for this purpose.
 94  
 95  The sign-off is a simple line at the end of the commit message for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below:
 96  
 97  __Developer’s Certificate of Origin 1.1__
 98  
 99  > By making a contribution to this project, I certify that:
100  >
101  > (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
102  >
103  > (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
104  >
105  > (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
106  >
107  > (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
108  
109  then you just add a line saying:
110  
111      Signed-off-by: Random J Developer <random@developer.example.org>
112  
113  using your name with which you are readily known in the community; anonymous signing of the code will not be accepted.