From ad2e3bb1aa159f3e9a128dc459b9cfc71bd0921e Mon Sep 17 00:00:00 2001 From: Maximilian Rosin Date: Mon, 10 May 2021 08:13:36 +0200 Subject: [PATCH 1/7] feat(docs): Add docs on contributing (#25) Signed-off-by: Maximilian Rosin --- contributing/asking_review.adoc | 12 ---- contributing/branching_member.adoc | 40 ++++++++---- contributing/commenting_fields_enums.adoc | 54 +++++++++++++++++ contributing/commenting_messages.adoc | 37 ++++++++++++ contributing/contribution_rules.adoc | 23 ++++--- contributing/creating_comments.adoc | 11 ---- contributing/dco.adoc | 64 ++++++++++++++++---- contributing/forking_no_member.adoc | 37 +++++++++--- contributing/licensing.adoc | 13 ++-- contributing/naming_conventions.adoc | 66 ++++++++++++++++---- contributing/osi_repos.adoc | 23 ++++--- contributing/reporting_issues.adoc | 33 +++++++--- contributing/review_author.adoc | 31 ++++++---- contributing/review_reviewer.adoc | 55 +++++++++++++---- contributing/signing_off_commits.adoc | 28 ++++++--- contributing/start_contributing.adoc | 19 +++--- contributing/writing_commit_messages.adoc | 74 +++++++++++++++++++++++ index.adoc | 9 +-- 18 files changed, 479 insertions(+), 150 deletions(-) delete mode 100644 contributing/asking_review.adoc create mode 100644 contributing/commenting_fields_enums.adoc create mode 100644 contributing/commenting_messages.adoc delete mode 100644 contributing/creating_comments.adoc create mode 100644 contributing/writing_commit_messages.adoc 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..9687eb70 100644 --- a/contributing/branching_member.adoc +++ b/contributing/branching_member.adoc @@ -1,11 +1,29 @@ -= 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 respective 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 diff --git a/contributing/commenting_fields_enums.adoc b/contributing/commenting_fields_enums.adoc new file mode 100644 index 00000000..d5664fcd --- /dev/null +++ b/contributing/commenting_fields_enums.adoc @@ -0,0 +1,54 @@ += Commenting on fields and enums + +The reference documentation of Open Simulation Interface 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 `\unit` keyword followed by an empty comment line. +. Optionally, add literary references to the comments. +. 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 rules +- 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..140a33d5 --- /dev/null +++ b/contributing/commenting_messages.adoc @@ -0,0 +1,37 @@ += Commenting on messages + +The reference documentation of Open Simulation Interface 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 an image using the `\image html` keyword followed by an empty comment line. + +**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 +{ +} +---- + +**Related topics** + +- Creating images. \ No newline at end of file diff --git a/contributing/contribution_rules.adoc b/contributing/contribution_rules.adoc index c5a5026e..b453a9d9 100644 --- a/contributing/contribution_rules.adoc +++ b/contributing/contribution_rules.adoc @@ -1,11 +1,14 @@ -= Rules for contributions += Guidelines 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 +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 consistent. +- If a commit contains work-in-progress, add the _WIP_ label to the commit message. 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/dco.adoc b/contributing/dco.adoc index d84ac225..79c8045c 100644 --- a/contributing/dco.adoc +++ b/contributing/dco.adoc @@ -1,11 +1,53 @@ -= 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 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. + +**Related topics** + diff --git a/contributing/forking_no_member.adoc b/contributing/forking_no_member.adoc index 24cb785f..6b9618f0 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 respective 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 +- Commit message guidelines \ No newline at end of file diff --git a/contributing/licensing.adoc b/contributing/licensing.adoc index 062b35c2..f5f7f307 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 respective repository. diff --git a/contributing/naming_conventions.adoc b/contributing/naming_conventions.adoc index 78a5709a..dc066110 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 respective 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..eca016a4 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 is 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..4a205717 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 your issue relates to and open it 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** + +- <> \ No newline at end of file diff --git a/contributing/review_author.adoc b/contributing/review_author.adoc index ef10a99a..3c10b62d 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 is a tool among others to enhance the quality of the code and to reduce the likelihood of introducing new bugs in the code base. +It 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 +- Writing commit messages +- Signing off commits diff --git a/contributing/review_reviewer.adoc b/contributing/review_reviewer.adoc index 877f731c..61130078 100644 --- a/contributing/review_reviewer.adoc +++ b/contributing/review_reviewer.adoc @@ -1,12 +1,43 @@ -= 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. These are suggestions and common pitfalls a code reviewer should avoid. + +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 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 a 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 : +For example, the statement “This operation is wrong. Please fix it.” is confrontational and authorative. +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..a34d2f71 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 +---- + +If a commit is missing 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..93b73a53 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 yourself familiar 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..74779f6b --- /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 all the times to help others to understand your commits. + +Commit messages shall have the following structure: + +[source] +---- +[optional scope]: + +[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 correspond to a MINOR release. +If the change is not backwards compatible, it correspond 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 +---- \ No newline at end of file diff --git a/index.adoc b/index.adoc index f7737bcc..013b222f 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] @@ -78,14 +79,14 @@ include::./contributing/forking_no_member.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/commenting_fields_enums.adoc[leveloffset=+3] include::./contributing/creating_images.adoc[leveloffset=+3] === Reviewing contributions -include::./contributing/asking_review.adoc[leveloffset=+3] - include::./contributing/review_author.adoc[leveloffset=+3] include::./contributing/review_reviewer.adoc[leveloffset=+3] From b87dc5edfbcb6d52bd3893f932cdf2442ff91075 Mon Sep 17 00:00:00 2001 From: Maximilian Rosin Date: Mon, 10 May 2021 08:37:15 +0200 Subject: [PATCH 2/7] feat(docs): Add docs on citing properly (#25) Signed-off-by: Maximilian Rosin --- contributing/creating_references.adoc | 74 +++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 contributing/creating_references.adoc 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; +} +---- From 5b1664a341798edca9e3afb09b84239db1c1d72b Mon Sep 17 00:00:00 2001 From: Maximilian Rosin <maximilian.rosin@parson-europe.com> Date: Thu, 17 Jun 2021 10:45:01 +0200 Subject: [PATCH 3/7] fix(docs): Changes after internal review (#25) Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com> --- contributing/branching_member.adoc | 4 ++-- contributing/commenting_fields_enums.adoc | 2 +- contributing/commenting_messages.adoc | 2 +- contributing/contribution_rules.adoc | 6 +++--- contributing/dco.adoc | 2 +- contributing/forking_no_member.adoc | 4 ++-- contributing/licensing.adoc | 2 +- contributing/naming_conventions.adoc | 10 +++++----- contributing/osi_repos.adoc | 6 +++--- contributing/reporting_issues.adoc | 6 +++--- contributing/review_author.adoc | 6 +++--- contributing/review_reviewer.adoc | 13 +++++++------ contributing/signing_off_commits.adoc | 2 +- contributing/start_contributing.adoc | 2 +- contributing/writing_commit_messages.adoc | 10 +++++----- 15 files changed, 39 insertions(+), 38 deletions(-) diff --git a/contributing/branching_member.adoc b/contributing/branching_member.adoc index 9687eb70..facf74b6 100644 --- a/contributing/branching_member.adoc +++ b/contributing/branching_member.adoc @@ -10,7 +10,7 @@ Members of the OSI project can contribute to the ASAM OSI repositories directly. **Steps** . Create an issue describing the intended change. -. Clone the respective repository on your local machine. +. 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. @@ -20,7 +20,7 @@ Members of the OSI project can contribute to the ASAM OSI repositories directly. . 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_. +. 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. diff --git a/contributing/commenting_fields_enums.adoc b/contributing/commenting_fields_enums.adoc index d5664fcd..263cf55c 100644 --- a/contributing/commenting_fields_enums.adoc +++ b/contributing/commenting_fields_enums.adoc @@ -1,6 +1,6 @@ = Commenting on fields and enums -The reference documentation of Open Simulation Interface is created using doxygen. +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. diff --git a/contributing/commenting_messages.adoc b/contributing/commenting_messages.adoc index 140a33d5..2939bb0b 100644 --- a/contributing/commenting_messages.adoc +++ b/contributing/commenting_messages.adoc @@ -1,6 +1,6 @@ = Commenting on messages -The reference documentation of Open Simulation Interface is created using doxygen. +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. diff --git a/contributing/contribution_rules.adoc b/contributing/contribution_rules.adoc index b453a9d9..58ba3235 100644 --- a/contributing/contribution_rules.adoc +++ b/contributing/contribution_rules.adoc @@ -7,8 +7,8 @@ ASAM OSI enforces the following commit guidelines: - 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 +- 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 consistent. +- Sign off commit messages. +- Name branches meaningfully and consistently. - If a commit contains work-in-progress, add the _WIP_ label to the commit message. diff --git a/contributing/dco.adoc b/contributing/dco.adoc index 79c8045c..adc03e52 100644 --- a/contributing/dco.adoc +++ b/contributing/dco.adoc @@ -1,6 +1,6 @@ = Developer Certificate of Origin (DCO) -To make a good-faith effort to ensure licensing criteria are met, the Developer-Certificate-of-Origin process shall be followed. +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. diff --git a/contributing/forking_no_member.adoc b/contributing/forking_no_member.adoc index 6b9618f0..c957954a 100644 --- a/contributing/forking_no_member.adoc +++ b/contributing/forking_no_member.adoc @@ -9,7 +9,7 @@ External contributers must fork the OSI repositories and contribute their change **Steps** . Create an issue describing the intended change. -. Fork the respective OSI repository on Github. +. 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. @@ -20,7 +20,7 @@ External contributers must fork the OSI repositories and contribute their change . 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_. +. 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. diff --git a/contributing/licensing.adoc b/contributing/licensing.adoc index f5f7f307..04ee6f46 100644 --- a/contributing/licensing.adoc +++ b/contributing/licensing.adoc @@ -3,4 +3,4 @@ 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 respective repository. +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 dc066110..1f84f915 100644 --- a/contributing/naming_conventions.adoc +++ b/contributing/naming_conventions.adoc @@ -1,6 +1,6 @@ = Interface conventions -OSI messages, enums, field messages and field enums shall comply with OSI 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_. @@ -11,7 +11,7 @@ message EnvironmentalConditions } ---- -Message field names shall use _snake_case_ +Message field names shall use _snake_case_. ---- message EnvironmentalConditions @@ -34,9 +34,9 @@ message EnvironmentalConditions ---- Enum field names shall use _UPPER_SNAKE_CASE_. -Enum fields shall always be prefixed with the name of the respective enum. -The first enum field shall always use the suffix __UNKNOWN_. -The second enum field shall always use the suffix __OTHER_. +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 diff --git a/contributing/osi_repos.adoc b/contributing/osi_repos.adoc index eca016a4..6a449b77 100644 --- a/contributing/osi_repos.adoc +++ b/contributing/osi_repos.adoc @@ -1,15 +1,15 @@ = ASAM OSI repositories -The source code and documentation of OSI and OSI-related tools is spread over several repositories. +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-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 +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 4a205717..8e66bb76 100644 --- a/contributing/reporting_issues.adoc +++ b/contributing/reporting_issues.adoc @@ -8,11 +8,11 @@ Reporting issues is a simple way of contributing to OSI. **Steps** -. Determine the repository your issue relates to and open it on Github. +. Determine the repository that your issue relates to and open the repository on Github. . Create a new issue. -. Select the correct issue type. +. Select the correct issue type: Bug report:: Report an error. - Feature request:: Suggest an idea for the project + 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. diff --git a/contributing/review_author.adoc b/contributing/review_author.adoc index 3c10b62d..8c67b92e 100644 --- a/contributing/review_author.adoc +++ b/contributing/review_author.adoc @@ -1,7 +1,7 @@ = Review guidelines for authors -Code review is a tool among others to enhance the quality of the code and to reduce the likelihood of introducing new bugs in the code base. -It is a technical discussion, it is not an exam, but it is a common effort to learn from each other. +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: @@ -10,7 +10,7 @@ Before asking for review, make sure your changes meet the following requirements * 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. +* All commits are signed off. **Related topics** diff --git a/contributing/review_reviewer.adoc b/contributing/review_reviewer.adoc index 61130078..0511acd7 100644 --- a/contributing/review_reviewer.adoc +++ b/contributing/review_reviewer.adoc @@ -1,6 +1,7 @@ = Review guidelines for reviewers -Code review can be challenging at times. These are suggestions and common pitfalls a code reviewer should avoid. +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? @@ -9,7 +10,7 @@ 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 discussions, it will often be more productive to discuss in person. +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. @@ -25,10 +26,10 @@ 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 a active and creative. +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. +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. @@ -38,6 +39,6 @@ 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 : -For example, the statement “This operation is wrong. Please fix it.” is confrontational and authorative. +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 a34d2f71..c44991c0 100644 --- a/contributing/signing_off_commits.adoc +++ b/contributing/signing_off_commits.adoc @@ -7,7 +7,7 @@ Contributors agree to the DCO by adding a ``Signed-off-by`` statement to the com Signed-off-by: Firstname Lastname <email@address.com> ---- -If a commit is missing the ``Signed-off-by`` statement, this commit cannot be merged into the master branch. +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: diff --git a/contributing/start_contributing.adoc b/contributing/start_contributing.adoc index 93b73a53..81300897 100644 --- a/contributing/start_contributing.adoc +++ b/contributing/start_contributing.adoc @@ -5,7 +5,7 @@ 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 yourself familiar with the following topics: +You should also make familiarize yourself with the following topics: * Google's _Protocol Buffers_. * _Git_. diff --git a/contributing/writing_commit_messages.adoc b/contributing/writing_commit_messages.adoc index 74779f6b..8198f0a0 100644 --- a/contributing/writing_commit_messages.adoc +++ b/contributing/writing_commit_messages.adoc @@ -3,7 +3,7 @@ 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 all the times to help others to understand your commits. +However, you should follow these guidelines always to help others to understand your commits. Commit messages shall have the following structure: @@ -24,11 +24,11 @@ Such changes usually correspond to a PATCH release. feat:: Change introduces a new feature. -If the change is backwards compatible, it correspond to a MINOR release. -If the change is not backwards compatible, it correspond to a MAJOR release. +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. +Change affects only the style but not the meaning of the code. Examples include white-space changes or code formatting. build:: @@ -59,7 +59,7 @@ 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. +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: From c83b69f5990dde436ff262e325011628b2faab8d Mon Sep 17 00:00:00 2001 From: Maximilian Rosin <maximilian.rosin@parson-europe.com> Date: Thu, 17 Jun 2021 10:49:49 +0200 Subject: [PATCH 4/7] feat(docs): Commented out topics for lack of content (#25) Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com> --- index.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.adoc b/index.adoc index 013b222f..96b0a126 100644 --- a/index.adoc +++ b/index.adoc @@ -77,13 +77,13 @@ 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/commenting_messages.adoc[leveloffset=+3] include::./contributing/commenting_fields_enums.adoc[leveloffset=+3] -include::./contributing/creating_images.adoc[leveloffset=+3] +//include::./contributing/creating_images.adoc[leveloffset=+3] === Reviewing contributions From 11668e9af862b87604da6401825170ecc64c0d47 Mon Sep 17 00:00:00 2001 From: Maximilian Rosin <maximilian.rosin@parson-europe.com> Date: Fri, 25 Jun 2021 13:54:32 +0200 Subject: [PATCH 5/7] fix(docs): Add related links, fix typos, add missing include (#25) Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com> --- contributing/branching_member.adoc | 3 ++- contributing/commenting_fields_enums.adoc | 4 ++-- contributing/commenting_messages.adoc | 4 ---- contributing/contribution_rules.adoc | 8 ++++++++ contributing/dco.adoc | 3 --- contributing/forking_no_member.adoc | 4 ++-- contributing/start_contributing.adoc | 4 ++-- 7 files changed, 16 insertions(+), 14 deletions(-) diff --git a/contributing/branching_member.adoc b/contributing/branching_member.adoc index facf74b6..942c2b8f 100644 --- a/contributing/branching_member.adoc +++ b/contributing/branching_member.adoc @@ -26,4 +26,5 @@ This label indicates that the changes in the pull request can be merged. **Related topics** -- Reporting issues +- <<_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 index 263cf55c..418b9076 100644 --- a/contributing/commenting_fields_enums.adoc +++ b/contributing/commenting_fields_enums.adoc @@ -50,5 +50,5 @@ message EnvironmentalConditions **Related topics** -- Writing rules -- Creating literary references. \ No newline at end of file +- <<_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 index 2939bb0b..4dfd1c55 100644 --- a/contributing/commenting_messages.adoc +++ b/contributing/commenting_messages.adoc @@ -31,7 +31,3 @@ message EnvironmentalConditions { } ---- - -**Related topics** - -- Creating images. \ No newline at end of file diff --git a/contributing/contribution_rules.adoc b/contributing/contribution_rules.adoc index 58ba3235..e5ceba27 100644 --- a/contributing/contribution_rules.adoc +++ b/contributing/contribution_rules.adoc @@ -12,3 +12,11 @@ ASAM OSI enforces the following commit guidelines: - 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/dco.adoc b/contributing/dco.adoc index adc03e52..a43aeba1 100644 --- a/contributing/dco.adoc +++ b/contributing/dco.adoc @@ -48,6 +48,3 @@ By making a contribution to this project, I certify that: ---- Contributors agree to the DCO by adding a ``Signed-off-by`` statement to the commit message. - -**Related topics** - diff --git a/contributing/forking_no_member.adoc b/contributing/forking_no_member.adoc index c957954a..db6ade6b 100644 --- a/contributing/forking_no_member.adoc +++ b/contributing/forking_no_member.adoc @@ -26,5 +26,5 @@ This label indicates that the changes in the pull request can be merged. **Related topics** -- Reporting issues -- Commit message guidelines \ No newline at end of file +- <<_reporting_issues>> +- <<_guidelines_for_contributions>> \ No newline at end of file diff --git a/contributing/start_contributing.adoc b/contributing/start_contributing.adoc index 81300897..c6603faf 100644 --- a/contributing/start_contributing.adoc +++ b/contributing/start_contributing.adoc @@ -7,6 +7,6 @@ Before you start, make yourself familiar with OSI and how to contribute by readi You should also make familiarize yourself with the following topics: -* Google's _Protocol Buffers_. -* _Git_. +* Google's _Protocol Buffers_ +* _Git_ * _Github_ From 03aaed4431b1b31edf254dd886ec49a27068ec8b Mon Sep 17 00:00:00 2001 From: Maximilian Rosin <maximilian.rosin@parson-europe.com> Date: Fri, 25 Jun 2021 14:24:44 +0200 Subject: [PATCH 6/7] fix(docs): Implement changes after review Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com> --- contributing/commenting_fields_enums.adoc | 8 ++++++-- contributing/commenting_messages.adoc | 1 - contributing/reporting_issues.adoc | 2 +- contributing/review_author.adoc | 6 +++--- contributing/signing_off_commits.adoc | 2 +- index.adoc | 2 ++ 6 files changed, 13 insertions(+), 8 deletions(-) diff --git a/contributing/commenting_fields_enums.adoc b/contributing/commenting_fields_enums.adoc index 418b9076..b0e858f0 100644 --- a/contributing/commenting_fields_enums.adoc +++ b/contributing/commenting_fields_enums.adoc @@ -11,9 +11,13 @@ Follow these steps when creating comments on fields and enums to keep the docume **Steps** . Add a description to the field or enum followed by an empty comment line. -. Add the unit of the field using the `\unit` keyword 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 literary references to the comments. -. Optionally, add rules encapsulated between `\rules` and `endrules`. +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** diff --git a/contributing/commenting_messages.adoc b/contributing/commenting_messages.adoc index 4dfd1c55..56f0891d 100644 --- a/contributing/commenting_messages.adoc +++ b/contributing/commenting_messages.adoc @@ -14,7 +14,6 @@ Follow these steps when creating comments on messages to keep the documentation . 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 an image using the `\image html` keyword followed by an empty comment line. **Example** diff --git a/contributing/reporting_issues.adoc b/contributing/reporting_issues.adoc index 8e66bb76..79ab3051 100644 --- a/contributing/reporting_issues.adoc +++ b/contributing/reporting_issues.adoc @@ -22,4 +22,4 @@ Reporting issues is a simple way of contributing to OSI. **Related topics** -- <<osi_repos.adoc#, ASAM OSI repositories>> \ No newline at end of file +- <<_asam_osi_repositories>> \ No newline at end of file diff --git a/contributing/review_author.adoc b/contributing/review_author.adoc index 8c67b92e..9b7a0f89 100644 --- a/contributing/review_author.adoc +++ b/contributing/review_author.adoc @@ -14,6 +14,6 @@ Before asking for review, make sure your changes meet the following requirements **Related topics** -- Interface conventions -- Writing commit messages -- Signing off commits +- <<_interface_conventions>> +- <<_guidelines_for_writing_commit_messages>> +- <<_signing_off_commits>> diff --git a/contributing/signing_off_commits.adoc b/contributing/signing_off_commits.adoc index c44991c0..d17ff6cb 100644 --- a/contributing/signing_off_commits.adoc +++ b/contributing/signing_off_commits.adoc @@ -18,4 +18,4 @@ git commit -m "Commit message" -s **Related topics** -Developer Certificate of Origin (DCO) \ No newline at end of file +- <<_developer_certificate_of_origin_dco>> \ No newline at end of file diff --git a/index.adoc b/index.adoc index 96b0a126..64f73ecf 100644 --- a/index.adoc +++ b/index.adoc @@ -83,6 +83,8 @@ include::./contributing/commenting_messages.adoc[leveloffset=+3] include::./contributing/commenting_fields_enums.adoc[leveloffset=+3] +include::./contributing/creating_references.adoc[leveloffset=+3] + //include::./contributing/creating_images.adoc[leveloffset=+3] === Reviewing contributions From df912dc02f2d97f9c85df4cc7f11bd03abc01a41 Mon Sep 17 00:00:00 2001 From: Maximilian Rosin <maximilian.rosin@parson-europe.com> Date: Fri, 25 Jun 2021 14:35:55 +0200 Subject: [PATCH 7/7] fix(docs): Describe use of note tag (#25) Signed-off-by: Maximilian Rosin <maximilian.rosin@parson-europe.com> --- contributing/commenting_fields_enums.adoc | 1 + contributing/commenting_messages.adoc | 1 + 2 files changed, 2 insertions(+) diff --git a/contributing/commenting_fields_enums.adoc b/contributing/commenting_fields_enums.adoc index b0e858f0..b088c6bf 100644 --- a/contributing/commenting_fields_enums.adoc +++ b/contributing/commenting_fields_enums.adoc @@ -12,6 +12,7 @@ Follow these steps when creating comments on fields and enums to keep the docume . 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. diff --git a/contributing/commenting_messages.adoc b/contributing/commenting_messages.adoc index 56f0891d..c4419db8 100644 --- a/contributing/commenting_messages.adoc +++ b/contributing/commenting_messages.adoc @@ -14,6 +14,7 @@ Follow these steps when creating comments on messages to keep the documentation . 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**