Describe contributing to OSI

contributing/branching_member.adoc

@@ -1,11 +1,30 @@
-= Branching for member contributors
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-Et malesuada fames ac turpis egestas.
-Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi.
-Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis.
-Sed augue lacus viverra vitae congue eu.
-Velit ut tortor pretium viverra suspendisse.
-Amet commodo nulla facilisi nullam vehicula ipsum a.
-Nibh nisl condimentum id venenatis a.
-Diam vel quam elementum pulvinar etiam non quam lacus suspendisse.
+= Branching workflow for member contributors
+
+Members of the OSI project can contribute to the ASAM OSI repositories directly.
+
+**Prerequisites**
+
+- You have a Github account.
+- You are a member of the ASAM OSI project.
+
+**Steps**
+
+. Create an issue describing the intended change.
+. Clone the corresponding repository on your local machine.
+. Create a branch with a meaningful name.
+  Follow the branch-name conventions.
+. Commit and push your changes to the branch.
+  Follow the commit messages guidelines.
+. When your changes are ready for review, create a pull request.
+  If possible, add references to corresponding issues and appropriate labels.
+. Ask reviewers to review your changes.
+. When discussion about the changes are done, add the _ReadyForCCBReview_ label.
+  Pull request with this label will be discussed in the next meeting of the _Change Control Board_.
+. When the Change Control Board approves of the changes, the pull request is labelled as _ReadyToMerge_.
+This label indicates that the changes in the pull request can be merged.
+. Merge the changes into the master branch of the repository.
+
+**Related topics**
+
+- <<_reporting_issues>>
+- <<_guidelines_for_contributions>>

contributing/commenting_fields_enums.adoc

@@ -0,0 +1,59 @@
+= Commenting on fields and enums
+
+The reference documentation of OSI is created using _Doxygen_.
+The content of the reference documentation is generated from comments in the `.proto` files.
+Follow these steps when creating comments on fields and enums to keep the documentation style consistent.
+
+**Prerequisites**
+
+* You have created a field or enum.
+
+**Steps**
+
+. Add a description to the field or enum followed by an empty comment line.
+. Add the unit of the field using the format `Unit: UNIT` followed by an empty comment line.
+. Optionally, add notes using the keyword `\note`.
+. Optionally, add literary references to the comments.
+The list of references starts with `\par References:` followed by the references.
+Every reference starts on a new line.
+Every reference begins with a reference number in the format `[n]`.
+Every reference ends with `\n`, except the last reference.
+. Optionally, add rules encapsulated between `\rules` and `\endrules`.
+
+**Example**
+
+----
+// \brief The conditions of the environment.
+//
+// \image html EnvironmentalConditions.svg
+//
+// Definition of light, weather conditions and other environmental conditions.
+//
+// \note These conditions apply locally around the host vehicle.
+//
+message EnvironmentalConditions
+{
+    // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa) [1, 2].
+    //
+    // Unit: Pa
+    //
+    // \note 100000 Pa = 1 bar
+    //
+    // \par References:
+    // [1] DIN Deutsches Institut fuer Normung e. V. (1982). <em>DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik</em>. (DIN 5031-3:1982-03). Berlin, Germany. \n
+    // [2] Rapp, C. (2017). Grundlagen der Physik. In <em>Hydraulik fuer Ingenieure und Naturwissenschaftler</em> (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105.
+    //
+    // \rules
+    // is_optional
+    // is_greater_than_or_equal_to: 90000
+    // is_less_than_or_equal_to: 200000
+    // \endrules
+    //
+    optional double atmospheric_pressure = 1;
+}
+----
+
+**Related topics**
+
+- <<_writing_custom_rules>>
+- <<_guidelines_for_creating_literary_references>>

contributing/commenting_messages.adoc

@@ -0,0 +1,33 @@
+= Commenting on messages
+
+The reference documentation of OSI is created using _Doxygen_.
+The content of the reference documentation is generated from comments in the `.proto` files.
+Follow these steps when creating comments on messages to keep the documentation style consistent.
+
+**Prerequisites**
+
+* You have created a new message.
+
+**Steps**
+
+. Add a brief description using the `\brief` keyword followed by an empty comment line.
+. Optionally, add an image using the `\image html` keyword followed by an empty comment line.
+  The image must be stored at `./open-simulation-interface/docs/images`
+. Optionally, add a detailed description spanning multiple lines followed by an empty comment line.
+. Optionally, add notes using the keyword `\note`.
+
+**Example**
+
+----
+// \brief The conditions of the environment.
+//
+// \image html EnvironmentalConditions.svg
+//
+// Definition of light, weather conditions and other environmental conditions.
+//
+// \note These conditions apply locally around the host vehicle.
+//
+message EnvironmentalConditions
+{
+}
+----

contributing/contribution_rules.adoc

@@ -1,11 +1,22 @@
-= Rules for contributions
-
-- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-- Et malesuada fames ac turpis egestas.
-- Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi.
-- Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis.
-- Sed augue lacus viverra vitae congue eu.
-- Velit ut tortor pretium viverra suspendisse.
-- Amet commodo nulla facilisi nullam vehicula ipsum a.
-- Nibh nisl condimentum id venenatis a.
-- Diam vel quam elementum pulvinar etiam non quam lacus suspendisse.
+= Guidelines for contributions
+
+Commit guidelines ensure the transparency and intelligibility of the commit history.
+ASAM OSI enforces the following commit guidelines:
+
+- Prefer small atomic commits over large ones that do many things.
+- Do not mix refactoring and new features.
+- Do not mix style changes, for example indentation changes, with actual code changes.
+- If you add new messages to a *.proto file, add appropriate documentation as well.
+- Run the unit tests for comment compliance to check if you followed the correct syntax guidelines for *.proto files.
+- Follow the guidelines for commit messages.
+- Sign off commit messages.
+- Name branches meaningfully and consistently.
+- If a commit contains work-in-progress, add the _WIP_ label to the commit message.
+
+**Related topics**
+
+- <<_guidelines_for_writing_commit_messages>>
+- <<_interface_conventions>>
+- <<_commenting_on_messages>>
+- <<_commenting_on_fields_and_enums>>
+- <<_signing_off_commits>>

contributing/creating_references.adoc

@@ -0,0 +1,74 @@
+= Guidelines for creating literary references
+
+When citing literature in the reference documentation, adhere to the following guidelines:
+
+* All sources shall be primary sources. Sources like Wikipedia are not allowed.
+* OSI uses _APA style_ references from the American Psychological Association.
+* In the text, sources are cited using numbers in brackets.
+* In the references list, the number in brackets is resolved to a full citation.
+* Titles shall be written in italic, using `<em>title</em>`.
+* If the list contains more than one entry, add `\n` at the end of the line to create a line break within the list.
+* Author names shall be written as <surname>, <initial(s)>.
+* Editor names shall be written as <initial(s)> <surname>.
+* Page numbers are optional and may be used with long texts or for referencing specific sections.
+
+**Templates**
+
+Use the following templates for creating properly styled references:
+
+Compilation::
+[source]
+----
+<author1>, <author2>, <author3> & <author4>. (<year>). Contribution in a compilation title. <em><Compilation Title></em>. <edition>. <page(s)>. <publisher>. <location>. <doi>. <page(s)>.
+----
+Book::
+[source]
+----
+<author1>, <author2> & <author3>. (<year>). <em><book (monograph) title></em>. <edition>. <publisher>. <doi>. <page(s)>.
+----
+Chapter in a book::
+[source]
+----
+<author1> & <author2>. (<year>). <book chapter title>. In <editor1> & <editor2> (Eds.), <em><book title></em> (<page(s)>). <publisher>. <doi>. <page(s)>.
+----
+Article in a journal::
+[source]
+----
+<author1> & <author2>. (<year>). <journal article title>. <em><journal title></em>. <page(s)>. <location>. <doi>. <page(s)>.
+----
+Phd thesis::
+[source]
+----
+<author>. (<year>). <em><Phd thesis title></em>. Phd. thesis. <location>. <university>. <doi or url>. <page(s)>.
+----
+Online article::
+[source]
+----
+<author>. (<year>, <month> <day>). <em><internet article title></em>. Retrieved <month> <day>, <year>, from <url>.
+----
+Standard::
+[source]
+----
+<standarding organisation>. (<year>). <em><title of the standard></em>. (<standard identifier>). <location>.
+----
+Patent::
+[source]
+----
+<author>. (<year>). <em><patent title and id></em>. <location>. <organisation>.
+----
+
+More sample templates are available at https://apastyle.apa.org.
+
+
+**Example**
+
+[source]
+----
+    // [...]
+    // \par References:
+    // [1] DIN Deutsches Institut fuer Normung e. V. (1982). <em>DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik</em>. (DIN 5031-3:1982-03). Berlin, Germany. \n
+    // [2] Rapp, C. (2017). Grundlagen der Physik. In <em>Hydraulik fuer Ingenieure und Naturwissenschaftler</em> (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105.
+    //
+    optional double atmospheric_pressure = 1;
+}
+----

contributing/dco.adoc

@@ -1,11 +1,50 @@
-= Developer Certification of Origin (DCO)
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-Et malesuada fames ac turpis egestas.
-Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi.
-Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis.
-Sed augue lacus viverra vitae congue eu.
-Velit ut tortor pretium viverra suspendisse.
-Amet commodo nulla facilisi nullam vehicula ipsum a.
-Nibh nisl condimentum id venenatis a.
-Diam vel quam elementum pulvinar etiam non quam lacus suspendisse.
+= Developer Certificate of Origin (DCO)
+
+To make a good-faith effort to ensure licensing criteria are met, the Developer-Certificate-of-Origin (DCO) process shall be followed.
+
+When contributing a change, the contributor must agree to the DCO.
+The DCO is a commitment that the contributor has the right to submit the change.
+
+The text of the DCO is shown below or can be accessed at https://developercertificate.org/.
+
+----
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(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
+
+(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
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(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.
+----
+
+Contributors agree to the DCO by adding a ``Signed-off-by`` statement to the commit message.

contributing/forking_no_member.adoc

@@ -1,11 +1,30 @@
 = Forking for non-member contributors
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-Et malesuada fames ac turpis egestas.
-Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi.
-Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis.
-Sed augue lacus viverra vitae congue eu.
-Velit ut tortor pretium viverra suspendisse.
-Amet commodo nulla facilisi nullam vehicula ipsum a.
-Nibh nisl condimentum id venenatis a.
-Diam vel quam elementum pulvinar etiam non quam lacus suspendisse.
+External contributers must fork the OSI repositories and contribute their changes via pull request.
+
+**Prerequisites**
+
+- You have a Github account.
+
+**Steps**
+
+. Create an issue describing the intended change.
+. Fork the corresponding OSI repository on Github.
+. Clone the forked repository on your local machine.
+. Create a branch with a meaningful name.
+  Follow the branch-name conventions.
+. Commit and push your changes to the branch.
+  Follow the commit messages guidelines.
+. When your changes are ready for review, create a pull request.
+  If possible, add references to corresponding issues and appropriate labels.
+. Ask reviewers to review your changes.
+. When discussion about the changes are done, add the _ReadyForCCBReview_ label.
+  Pull request with this label will be discussed in the next meeting of the _Change Control Board_.
+. When the Change Control Board approves of the changes, the pull request is labelled as _ReadyToMerge_.
+This label indicates that the changes in the pull request can be merged.
+. Merge the changes into the master branch of the repository.
+
+**Related topics**
+
+- <<_reporting_issues>>
+- <<_guidelines_for_contributions>>

contributing/licensing.adoc

@@ -1,11 +1,6 @@
 = License
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-Et malesuada fames ac turpis egestas.
-Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi.
-Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis.
-Sed augue lacus viverra vitae congue eu.
-Velit ut tortor pretium viverra suspendisse.
-Amet commodo nulla facilisi nullam vehicula ipsum a.
-Nibh nisl condimentum id venenatis a.
-Diam vel quam elementum pulvinar etiam non quam lacus suspendisse.
+OSI uses the https://www.mozilla.org/en-US/MPL/2.0/[Mozilla Public License, v. 2.0].
+All contributions are released under this license.
+
+Before contributing to OSI repositories, read the `LICENSE` file in the corresponding repository.