diff --git a/contributing/asking_review.adoc b/contributing/asking_review.adoc deleted file mode 100644 index da196bfc..00000000 --- a/contributing/asking_review.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= Asking for review - -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. \ No newline at end of file diff --git a/contributing/branching_member.adoc b/contributing/branching_member.adoc index 8f20775c..942c2b8f 100644 --- a/contributing/branching_member.adoc +++ b/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. \ No newline at end of file += 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>> \ No newline at end of file diff --git a/contributing/commenting_fields_enums.adoc b/contributing/commenting_fields_enums.adoc new file mode 100644 index 00000000..b088c6bf --- /dev/null +++ b/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). DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik. (DIN 5031-3:1982-03). Berlin, Germany. \n + // [2] Rapp, C. (2017). Grundlagen der Physik. In Hydraulik fuer Ingenieure und Naturwissenschaftler (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>> \ No newline at end of file diff --git a/contributing/commenting_messages.adoc b/contributing/commenting_messages.adoc new file mode 100644 index 00000000..c4419db8 --- /dev/null +++ b/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 +{ +} +---- diff --git a/contributing/contribution_rules.adoc b/contributing/contribution_rules.adoc index c5a5026e..e5ceba27 100644 --- a/contributing/contribution_rules.adoc +++ b/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. \ No newline at end of file += 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>> \ No newline at end of file diff --git a/contributing/creating_comments.adoc b/contributing/creating_comments.adoc deleted file mode 100644 index e815f858..00000000 --- a/contributing/creating_comments.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= Creating code comments - -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. \ No newline at end of file diff --git a/contributing/creating_references.adoc b/contributing/creating_references.adoc new file mode 100644 index 00000000..399ba7d2 --- /dev/null +++ b/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 `title`. +* 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 , . +* Editor names shall be written as . +* 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] +---- +, , & . (). Contribution in a compilation title. . . . . . . . +---- +Book:: +[source] +---- +, & . (). . . . . . +---- +Chapter in a book:: +[source] +---- + & . (). . In & (Eds.), (). . . . +---- +Article in a journal:: +[source] +---- + & . (). . . . . . . +---- +Phd thesis:: +[source] +---- +. (). . Phd. thesis. . . . . +---- +Online article:: +[source] +---- +. (, ). . Retrieved , , from . +---- +Standard:: +[source] +---- +. (). </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; +} +---- diff --git a/contributing/dco.adoc b/contributing/dco.adoc index d84ac225..a43aeba1 100644 --- a/contributing/dco.adoc +++ b/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. \ No newline at end of file += 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. diff --git a/contributing/forking_no_member.adoc b/contributing/forking_no_member.adoc index 24cb785f..db6ade6b 100644 --- a/contributing/forking_no_member.adoc +++ b/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. \ No newline at end of file +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>> \ No newline at end of file diff --git a/contributing/licensing.adoc b/contributing/licensing.adoc index 062b35c2..04ee6f46 100644 --- a/contributing/licensing.adoc +++ b/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. \ No newline at end of file +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. diff --git a/contributing/naming_conventions.adoc b/contributing/naming_conventions.adoc index 78a5709a..1f84f915 100644 --- a/contributing/naming_conventions.adoc +++ b/contributing/naming_conventions.adoc @@ -1,11 +1,55 @@ -= Message naming conventions - -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. \ No newline at end of file += Interface conventions + +OSI messages, enums, field messages, and field enums shall comply with OSI interface conventions. +These conventions ensure that message definitions and the corresponding classes are consistently named and easy to read. + +Message names shall use _PascalCase_. + +---- +message EnvironmentalConditions +{ +} +---- + +Message field names shall use _snake_case_. + +---- +message EnvironmentalConditions +{ + optional double atmospheric_pressure = 1; +} +---- + +Enum names shall use _PascalCase_. + +---- +message EnvironmentalConditions +{ + optional double atmospheric_pressure = 1; + + enum AmbientIllumination + { + } +} +---- + +Enum field names shall use _UPPER_SNAKE_CASE_. +Enum fields shall always be prefixed with the name of the corresponding enum. +The first enum field shall always use the suffix _UNKNOWN_. +The second enum field shall always use the suffix _OTHER_. + +---- +message EnvironmentalConditions +{ + optional double atmospheric_pressure = 1; + + enum AmbientIllumination + { + AMBIENT_ILLUMINATION_UNKNOWN = 0; + + AMBIENT_ILLUMINATION_OTHER = 1; + + AMBIENT_ILLUMINATION_LEVEL1 = 2; + } +} +---- \ No newline at end of file diff --git a/contributing/osi_repos.adoc b/contributing/osi_repos.adoc index adc11a7d..6a449b77 100644 --- a/contributing/osi_repos.adoc +++ b/contributing/osi_repos.adoc @@ -1,12 +1,15 @@ = ASAM OSI repositories -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. \ No newline at end of file +The source code and documentation of OSI and OSI-related tools are spread over several repositories. + +open-simulation-interface:: Main repository containing the interface description based on Google's Protocol Buffers, including helper scripts and test scripts. + +osi-documentation:: Source of the OSI user guide. + +osi-sensor-model-packaging:: Packaging specification for OSI models used in FMI 2.0 simulation environments, including examples. + +osi-validation:: Source code and documentation of the OSI Validator, a CLI tool for validating OSI messages. + +osi-visualizer:: Source code and documentation of the OSI Visualizer, a GUI tool for visualizing OSI messages. + +proto2cpp:: Doxygen filter for creating the reference documentation from OSI .proto files. \ No newline at end of file diff --git a/contributing/reporting_issues.adoc b/contributing/reporting_issues.adoc index 4272303f..79ab3051 100644 --- a/contributing/reporting_issues.adoc +++ b/contributing/reporting_issues.adoc @@ -1,12 +1,25 @@ = Reporting issues -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. \ No newline at end of file +Reporting issues is a simple way of contributing to OSI. + +**Prerequisites** + +* You have a Github account. + +**Steps** + +. Determine the repository that your issue relates to and open the repository on Github. +. Create a new issue. +. Select the correct issue type: + Bug report:: Report an error. + Feature request:: Suggest an idea for the project. + Question:: Ask a question if you do not understand something or need clarification. + Blank issue:: Use this issue type if no other type fits your issue. +. Fill out the title and description field. + Follow the instructions in the template. +. Add suitable labels. +. When you are done editing the fields and labels, click **Submit new issue**. + +**Related topics** + +- <<_asam_osi_repositories>> \ No newline at end of file diff --git a/contributing/review_author.adoc b/contributing/review_author.adoc index ef10a99a..9b7a0f89 100644 --- a/contributing/review_author.adoc +++ b/contributing/review_author.adoc @@ -1,12 +1,19 @@ -= Review from the author's perspective - -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. \ No newline at end of file += Review guidelines for authors + +Code review enhances the quality of the code and reduces the likelihood of introducing new bugs in the code base. +Reviewing code is a technical discussion, it is not an exam, but it is a common effort to learn from each other. + +Before asking for review, make sure your changes meet the following requirements: + +* The code is readable and easy to understand. +* The code does not contain contain commented-out lines and deprecated comments. +* The code contains helpful comments to be used in the reference documentation. +* Variable and function names follow the naming convention. +* Commit messages are meaningful and follow the convention. +* All commits are signed off. + +**Related topics** + +- <<_interface_conventions>> +- <<_guidelines_for_writing_commit_messages>> +- <<_signing_off_commits>> diff --git a/contributing/review_reviewer.adoc b/contributing/review_reviewer.adoc index 877f731c..0511acd7 100644 --- a/contributing/review_reviewer.adoc +++ b/contributing/review_reviewer.adoc @@ -1,12 +1,44 @@ -= Review from the reviewer's perspective - -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. \ No newline at end of file += Review guidelines for reviewers + +Code review can be challenging at times. +Follow these suggestions when reviewing code to avoid common pitfalls: + +Ask questions:: +What is the purpose of this change? +If this requirement changes, what else would have to change? +How could we make this more maintainable? + +Discuss in person for more detailed points:: +Online comments are useful for focused technical questions. +In case of more detailed discussions, it will often be more productive to discuss in person. + +Explain yourself:: +Sometimes it is best to both ask if there is a better alternative and at the same time justify why a problem in the code is worth fixing. +Criticism without explanation can appear confrontational. + +Make it about the code:: +It is easy to take notes from code reviews personally, especially if we take pride in our work. +It is best to make discussions about the code than about the developer. + +Suggest importance of fixes:: +When offering many suggestions at once, clarify that not all of them need to be acted upon at once. +Indicate the importance of your suggestions. +This allows developers to improve their work incrementally. + +Take the developer’s opinion into consideration:: +Imposing a particular design choice out of personal preferences and without a real explanation will incentivize the developer to be passive instead of active and creative. + +Do not re-write, remove or re-do all the work:: +Sometimes, it appears easier to re-do the work yourself, thereby discarding the work of the developer. +This can give the impression that the work of the developer is worthless. +It also adds additional work for the reviewer who effectively takes responsibility for the code. + +Consider the person you are reviewing:: +Developers are human beings. +Consider their personality and experience when reviewing their code. + +Avoid confrontational and authoritative language:: +The way we communicate has an impact on the receiver. +Consider these two statements to communicate about a problem in the code: +The statement “This operation is wrong, please fix it.” is confrontational and authoritative. +Instead, explain the specific error and ask the developer to review the code again. \ No newline at end of file diff --git a/contributing/signing_off_commits.adoc b/contributing/signing_off_commits.adoc index cd5b597e..d17ff6cb 100644 --- a/contributing/signing_off_commits.adoc +++ b/contributing/signing_off_commits.adoc @@ -1,11 +1,21 @@ = Signing off commits -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. \ No newline at end of file +Contributing to OSI projects requires agreeing to the Developer Certificate of Origin (DCO). +Contributors agree to the DCO by adding a ``Signed-off-by`` statement to the commit message. + +---- +Signed-off-by: Firstname Lastname <email@address.com> +---- + +If a commit does not include the ``Signed-off-by`` statement, this commit cannot be merged into the master branch. + +To add a sign-off statement to a commit add ``-s`` or ``--signoff`` to the commit command: + +---- +git commit -m "Commit message" -s +---- + + +**Related topics** + +- <<_developer_certificate_of_origin_dco>> \ No newline at end of file diff --git a/contributing/start_contributing.adoc b/contributing/start_contributing.adoc index ccc1dcfe..c6603faf 100644 --- a/contributing/start_contributing.adoc +++ b/contributing/start_contributing.adoc @@ -1,11 +1,12 @@ = Getting started with contributing -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. \ No newline at end of file +ASAM Open Simulation Interface is an open-source standardization project. +OSI and its supporting tools are developed publicly on Github. + +Before you start, make yourself familiar with OSI and how to contribute by reading this documentation and OSI's reference documentation. + +You should also make familiarize yourself with the following topics: + +* Google's _Protocol Buffers_ +* _Git_ +* _Github_ diff --git a/contributing/writing_commit_messages.adoc b/contributing/writing_commit_messages.adoc new file mode 100644 index 00000000..8198f0a0 --- /dev/null +++ b/contributing/writing_commit_messages.adoc @@ -0,0 +1,74 @@ += Guidelines for writing commit messages + +Apart from a sign-off message, OSI requires commit messages to follow a specific format. +This format enables others to understand the motivation behind your commits more easily. +OSI enforces these requirements only for commits to protected branches. +However, you should follow these guidelines always to help others to understand your commits. + +Commit messages shall have the following structure: + +[source] +---- +<type>[optional scope]: <description> + +[optional body] + +[optional footer(s)] +---- + +Commits can have one of the following types: + +fix:: +Change fixes an error. +Such changes usually correspond to a PATCH release. + +feat:: +Change introduces a new feature. +If the change is backwards compatible, it corresponds to a MINOR release. +If the change is not backwards compatible, it corresponds to a MAJOR release. + +style:: +Change affects only the style but not the meaning of the code. +Examples include white-space changes or code formatting. + +build:: +Change affects the building components. +Examples include changes to the CI pipeline or the project version. + +The scope indicates which part of OSI is affected by the commit. +With OSI, commits can have one of the following scopes: + +code:: +Change affects the OSI code. + +inlinedocs:: +Change affects the inline documentation. + +docs:: +Change affects the accompanying documentation. + +The description gives a concise summary of the change. +The description shall adhere to the following rules: + +- Use imperative mode and present tense to indicate what happens, when the change is applied. +- Do not capitalize the first letter. +- Do not end the description with a full stop. + +The optional body contains information about the motivation behind the change. +This includes references to Github issues by ID. +Github uses these IDs to create links between the issues and the commit history. + +The optional footer contains a note, if the changes are breaking backwards compatibility. +Such a note starts with `BREAKING CHANGES:` followed by a concise description of what this change breaks. + +The following example shows a commit message meeting all requirements: + +[source] +---- +feat(model): Prevent empty StopTriggers + +refers to #23 + +BREAKING CHANGES: StopTrigger can no longer be empty +Signed-off-by: Max Mustermann <max.mustermann@email.address> +---- \ No newline at end of file diff --git a/index.adoc b/index.adoc index f7737bcc..64f73ecf 100644 --- a/index.adoc +++ b/index.adoc @@ -57,7 +57,6 @@ include::./contributing/start_contributing.adoc[leveloffset=+2] include::./contributing/osi_repos.adoc[leveloffset=+2] - include::./contributing/reporting_issues.adoc[leveloffset=+2] === Contributing changes @@ -68,6 +67,8 @@ include::./contributing/dco.adoc[leveloffset=+3] include::./contributing/signing_off_commits.adoc[leveloffset=+3] +include::./contributing/writing_commit_messages.adoc[leveloffset=+3] + include::./contributing/contribution_rules.adoc[leveloffset=+3] include::./contributing/naming_conventions.adoc[leveloffset=+3] @@ -76,15 +77,17 @@ include::./contributing/branching_member.adoc[leveloffset=+3] include::./contributing/forking_no_member.adoc[leveloffset=+3] -include::./contributing/contributing_docs.adoc[leveloffset=+3] +//include::./contributing/contributing_docs.adoc[leveloffset=+3] -include::./contributing/creating_comments.adoc[leveloffset=+3] +include::./contributing/commenting_messages.adoc[leveloffset=+3] -include::./contributing/creating_images.adoc[leveloffset=+3] +include::./contributing/commenting_fields_enums.adoc[leveloffset=+3] -=== Reviewing contributions +include::./contributing/creating_references.adoc[leveloffset=+3] -include::./contributing/asking_review.adoc[leveloffset=+3] +//include::./contributing/creating_images.adoc[leveloffset=+3] + +=== Reviewing contributions include::./contributing/review_author.adoc[leveloffset=+3]