-
Notifications
You must be signed in to change notification settings - Fork 123
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Convert Markdown to Asciidoc where possible
Merged-by: Martin Grzenia <[email protected]>
- Loading branch information
Showing
6 changed files
with
88 additions
and
103 deletions.
There are no files selected for viewing
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| // SPDX-FileCopyrightText: The openTCS Authors | ||
| // SPDX-License-Identifier: CC-BY-4.0 | ||
|
|
||
| = Changelog | ||
|
|
||
| The changelog is maintained in link:./opentcs-documentation/src/docs/release-notes/changelog.adoc[opentcs-documentation/src/docs/release-notes/changelog.adoc]. |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,45 +1,43 @@ | ||
| <!-- | ||
| SPDX-FileCopyrightText: The openTCS Authors | ||
| SPDX-License-Identifier: CC-BY-4.0 | ||
| --> | ||
| // SPDX-FileCopyrightText: The openTCS Authors | ||
| // SPDX-License-Identifier: CC-BY-4.0 | ||
|
|
||
| # Contributing to openTCS | ||
| = Contributing to openTCS | ||
|
|
||
| The following is a set of guidelines for contributing to openTCS. | ||
|
|
||
| This project is maintained by the openTCS development team of [Fraunhofer IML](https://www.iml.fraunhofer.de/en.html). | ||
| A public mirror of the development repository is available at [GitHub](https://github.com/opentcs/opentcs). | ||
| This project is maintained by the openTCS development team of https://www.iml.fraunhofer.de/en.html[Fraunhofer IML]. | ||
| A public mirror of the development repository is available at https://github.com/opentcs/opentcs[GitHub]. | ||
|
|
||
| You are very welcome to contribute to this project when you find a bug, want to suggest an improvement, or have an idea for a useful feature. | ||
| For this, please always create an issue and/or a pull request, and follow our style guides as described below. | ||
|
|
||
| ## Issues | ||
| == Issues | ||
|
|
||
| It is required to create an issue if you want to integrate a bugfix, improvement, or feature. | ||
| Briefly and clearly describe the purpose of your contribution in the corresponding issue, using the appropriate template for it. | ||
|
|
||
| ## Pull requests / merge requests | ||
| == Pull requests / merge requests | ||
|
|
||
| Pull requests fixing bugs, adding new features or improving the quality of the code and/or the documentation are very welcome! | ||
| To contribute changes, please follow these steps: | ||
|
|
||
| 1. Before putting any significant amount of work into changes you want to make, get in touch with the maintainers. | ||
| Informing and coordinating helps to avoid conflicts with other changes made elsewhere. | ||
| If there already is an issue or a forum discussion related to the intended changes, announce your will to work on it there; if there isn't, yet, create one. | ||
| (Specific bug reports and feature/improvement suggestions should be handled in issues; loose ideas should be discussed in the forum first.) | ||
| 2. Fork the repository and create a new branch for your changes. | ||
| 3. Make your changes in the new branch, adhering to the coding guidelines. | ||
| 4. If your changes add a new feature, consider adding documentation for it to the user's guide or the developer's guide. | ||
| If your changes change an existing feature's behaviour, check these documents and update them if necessary. | ||
| 5. If your changes affect users, document them in the [changelog](opentcs-documentation/src/docs/release-notes/changelog.adoc). | ||
| 6. Push your branch to your forked repository. | ||
| 7. Open a pull request against the main repository's main branch. | ||
| 1. Fill out the pull request template and provide a clear description of your changes and the problem they solve. | ||
| 2. Provide a commit message for the pull request, adhering to the commit message guidelines described below. | ||
| . Before putting any significant amount of work into changes you want to make, get in touch with the maintainers. | ||
| Informing and coordinating helps to avoid conflicts with other changes made elsewhere. | ||
| If there already is an issue or a forum discussion related to the intended changes, announce your will to work on it there; if there isn't, yet, create one. | ||
| (Specific bug reports and feature/improvement suggestions should be handled in issues; loose ideas should be discussed in the forum first.) | ||
| . Fork the repository and create a new branch for your changes. | ||
| . Make your changes in the new branch, adhering to the coding guidelines. | ||
| . If your changes add a new feature, consider adding documentation for it to the user's guide or the developer's guide. | ||
| If your changes change an existing feature's behaviour, check these documents and update them if necessary. | ||
| . If your changes affect users, document them in the link:opentcs-documentation/src/docs/release-notes/changelog.adoc[changelog]. | ||
| . Push your branch to your forked repository. | ||
| . Open a pull request against the main repository's main branch. | ||
| .. Fill out the pull request template and provide a clear description of your changes and the problem they solve. | ||
| .. Provide a commit message for the pull request, adhering to the commit message guidelines described below. | ||
|
|
||
| When contributing, keep unrelated changes in separate pull requests! | ||
|
|
||
| ### Commit message guidelines | ||
| === Commit message guidelines | ||
|
|
||
| When writing commit messages, please follow these guidelines: | ||
|
|
||
|
|
@@ -53,17 +51,17 @@ When writing commit messages, please follow these guidelines: | |
|
|
||
| Example: | ||
|
|
||
| ``` | ||
| ---- | ||
| Make vehicle energy level thresholds configurable | ||
| Allow a vehicle's set of energy level thresholds to be modified during | ||
| runtime via the Operations Desk application and the web API. | ||
| Co-authored-by: Martin Grzenia <[email protected]> | ||
| Co-authored-by: Stefan Walter <[email protected]> | ||
| ``` | ||
| ---- | ||
|
|
||
| ## Coding guidelines | ||
| == Coding guidelines | ||
|
|
||
| In general, please adhere to the following guidelines to maintain code consistency, readability, and quality: | ||
|
|
||
|
|
@@ -77,19 +75,19 @@ The following subsections contain a few more detailed guidelines we consider imp | |
| Note that parts of the existing code may not fully adhere to these rules, yet. | ||
| When updating such code, do improve it by applying the guidelines where it makes sense, but avoid modifying large unrelated sections. | ||
|
|
||
| ### Primary formatting rules | ||
| === Primary formatting rules | ||
|
|
||
| For consistent formatting of the project's code, [Spotless](https://github.com/diffplug/spotless) is used. | ||
| For consistent formatting of the project's code, https://github.com/diffplug/spotless[Spotless] is used. | ||
| After making changes, make sure you run `./gradlew spotlessApply` to re-format the code. | ||
|
|
||
| ### Automatic tests | ||
| === Automatic tests | ||
|
|
||
| * New or changed non-trivial code should be covered by tests. | ||
| * This project uses [JUnit](https://junit.org/) for unit testing. | ||
| * This project uses https://junit.org/[JUnit] for unit testing. | ||
| * JUnit test classes and methods should omit the `public` modifier unless there is a technical reason for adding it. | ||
| * For assertions, `assertThat()` should be preferred over `assertTrue()`, as the former provides more information when failing. | ||
|
|
||
| ### Check preconditions in subroutines | ||
| === Check preconditions in subroutines | ||
|
|
||
| Methods belonging to a class's interface, i.e. `public` or `protected` methods, should check their preconditions. | ||
| They should at least check their input parameters for validity: | ||
|
|
@@ -102,14 +100,14 @@ They should at least check their input parameters for validity: | |
| Checking the object's internal state may also make sense for a method. | ||
| For such checks, `org.opentcs.util.Assertions.checkState()` should be used. | ||
|
|
||
| ### Avoid single-use local variables | ||
| === Avoid single-use local variables | ||
|
|
||
| Declaring local variables in subroutines that are then used only once creates unnecessary noise for the reader of the code. | ||
| In many cases, eliminating the variable by inlining its value improves the readability of the code. | ||
|
|
||
| ## Development setup | ||
| == Development setup | ||
|
|
||
| ### IDE: NetBeans | ||
| === IDE: NetBeans | ||
|
|
||
| To build the project from NetBeans, register a Java platform named "JDK 21 - openTCS" (without the quotes) within NetBeans. | ||
| This JDK will be used by NetBeans for running the build process. | ||
Oops, something went wrong.