ie3-institute · t-ober · Feb 23, 2023 · Feb 2, 2023 · Feb 13, 2023 · Feb 21, 2023
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -7,9 +7,9 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.11"
 
 # Configure python
 python:
@@ -18,4 +18,5 @@ python:
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-  configuration: docs/readthedocs/conf.py
+  configuration: docs/readthedocs/conf.py
+  fail_on_warning: true
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added DBFS test with participant load and added testing for FinishGridSimulationTrigger [#281](https://github.com/ie3-institute/simona/issues/281)
 - Added Dependabot updates to sphinx/readthedocs dependencies [#448](https://github.com/ie3-institute/simona/issues/448)
 - Check for grid validity with PSDM `ValidationUtils` [#460](https://github.com/ie3-institute/simona/issues/460)
+- Enhancing dev's guide [#363](https://github.com/ie3-institute/simona/issues/363)
 
 ### Changed
 - Re-organizing test resources into their respective packages [#105](https://github.com/ie3-institute/simona/issues/105)
@@ -58,6 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Changed simulation duration format [#429](https://github.com/ie3-institute/simona/issues/429)
 - Updated sphinx dependencies and fixed sphinx warnings [#444](https://github.com/ie3-institute/simona/issues/444)
 - Updated authors in AUTHORS.md and README.md [#452](https://github.com/ie3-institute/simona/issues/452)
+- Updating `CONTRIBUTING.md` [#201](https://github.com/ie3-institute/simona/issues/201)
 
 ### Fixed
 - Location of `vn_simona` test grid (was partially in Berlin and Dortmund) [#72](https://github.com/ie3-institute/simona/issues/72)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,16 +7,12 @@ With this document we would like to give you some orientation on how you can con
 * [Testing and reporting bugs](#testing-and-reporting-bugs)
 * [Suggest extensions](#suggest-extensions)
 * [Contributing code](#contributing-code)
-* [Branching and handing in pull requests](#branching-and-handing-in-pull-requests)
-* [General (software) design guidelines](#general-software-design-guidelines)
-* [Testing](#testing)
-* [Finalising your pull request](#finalising-your-pull-request)
-* [For any doubts](#for-any-doubts)
+* [With any questions or doubts](#with-any-questions-or-doubts)
 
 ## Testing and reporting bugs
 We really appreciate your usage of this project.
 Whenever you find a bug, it would be nice to check, if this isn't a feature to us. :wink:
-If you still think it's a bug, please raise an [issue](https://simona.ie3.e-technik.tu-dortmund.de/jira/projects/SIM/issues/) for us.
+If you still think it's a bug, please [raise an issue](https://github.com/ie3-institute/simona/issues) for us.
 Considering the following aspects in your inquiry, assists us in helping you:
 
 * **Is there already an issue addressing your problem?**
@@ -31,45 +27,12 @@ We use issues as well to keep track of enhancement suggestions.
 Considering the following aspects, assists us in understanding your needs properly:
 
 * **Is there already an issue addressing your request?**
-* **What would do you desire for?**
 * If possible provide an **example or sketch**.
 * Show a **use case**, that should be as versatile as possible.
 * Mark the issue with the **label _enhancement_**.
 
 ## Contributing code
-If you intend to produce some lines of code, pick an issue and get some hands on! For any questions feel
-free to contact us.
+Please refer to our [developer's guide](https://simona.readthedocs.io/en/latest/developersguide.html) for more information on how to contribute code.
 
-### Branching and handing in pull requests
-We try to follow a branch naming strategy of the form `<initials>/#<issueId>-<description>`.
-If for example [Prof. Dr. rer. hort. Klaus-Dieter Brokkoli](https://www.instagram.com/prof_broccoli/) would like to add some work on node models reported in issue 4711, he would open a branch `kb/#4711-extendingNodeModels`.
-Please hand in a pull request with ``WIP:`` prefix as early as possible to allow other to keep track on your changes.
-Before opening it for review, please [finalise your pull request](#finalising-your-pull-request).
-
-### General (software) design guidelines
-In order to maintain a consistent project, we thought of some general design guidlines, we kindly ask you to take care of:
-
-* We :heart: **immutability**. Therefore, please don't provide setters and use proper instantiation instead.
-* `double a = b * pow(x, j)`? :hand: Please **be expressive** in what you code!
-* Document your code with **scaladoc**.
-
-### Testing
-Ensure the proper function of your code by [test driven development (TDD)](https://www.guru99.com/test-driven-development.html).
-We have good experiences using [ScalaTest](scalatest.org) and [Spock](http://spockframework.org/) as a testing framework for [Groovy](https://groovy-lang.org/).
-
-### Finalising your pull request
-Some automated checks assist us in delivering a pretty fair quality of software.
-Before marking the pull request as 'ready to review', take these precautionary actions:
-
-* Are all tests passing? Run `gradle allTests` or comment `!test` in your PR which automatically triggers
-our [CI](https://tvnws007-lin.ie3.e-technik.tu-dortmund.de/job/simona/)
-* Is your code properly formatted? Run `gradle spotlessApply`
-* Update the javadoc pages. Run `gradle genJavadoc`
-
-## For any doubts
-... please contact
-* Johannes ([johannes.hiry@tu-dortmund.de](mailto:johannes.hiry@tu-dortmund.de)),
-* Debopama ([debopama-sen.sarma@tu-dortmund.de](mailto:debopama-sen.sarma@tu-dortmund.de)) or
-* Chris ([chris.kittl@tu-dortmund.de](mailto:chris.kittl@tu-dortmund.de))
-
-We are happy to help! :smiley:
+## With any questions or doubts
+... please contact the developers listed in the [README.md](https://github.com/ie3-institute/simona/blob/dev/README.md).
diff --git a/docs/readthedocs/conf.py b/docs/readthedocs/conf.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 project = u'simona'
-copyright = u'2020. TU Dortmund University, Institute of Energy Systems, Energy Efficiency and Energy Economics, Research group Distribution grid planning and operation '
+copyright = u'2023. TU Dortmund University, Institute of Energy Systems, Energy Efficiency and Energy Economics, Research group Distribution grid planning and operation '
 version = '1.0'
 release = '1.0.0'
 

diff --git a/docs/readthedocs/developersguide.md b/docs/readthedocs/developersguide.md
@@ -2,13 +2,80 @@
 
 # Developer’s Guide
 
-## Repositories
+The SIMONA repository can be found [on Github](https://github.com/ie3-institute/simona).
 
-The SIMONA repository on github [is here](https://github.com/ie3-institute/simona).
+```{contents}
+---
+local:
+```
+
+## Contributing code
+
+If you intend to produce some lines of code, pick an issue and get some hands on! For any questions feel
+free to contact us (see [`README.md`](https://github.com/ie3-institute/simona/blob/dev/README.md) for contact information).
+
+### Branching and handing in pull requests
+
+We try to follow a branch naming strategy of the form `<initials>/#<issueId>-<description>`.
+If for example [Prof. Dr. rer. hort. Klaus-Dieter Brokkoli](https://www.instagram.com/prof_broccoli/) would like to add some work on node models reported in issue #4711, he would open a branch `kb/#4711-extendingNodeModels`.
+Before opening it for review, please make sure the automated checks have succeeded and the code quality is up to our standard.
+
+## Finalising your pull request
+
+Before a PR can be merged, some automated tests and a manual review have to be completed successfully.
+There can be one or more reviewers per PR, although at least one is required, and one or multiple review rounds.
+We also encourage you to create pull requests early in your development cycle which gives others an opportunity to observe and/or provide feedback in real time. 
+When you are ready for a review, invite one or more reviewers through the pull request.
+In short, mergeable PRs have to meet our standards in several areas:
+- Automated checks
+  - [Jenkins](https://simona.ie3.e-technik.tu-dortmund.de/ci/job/ie3-institute/job/simona/) run succeeds, i.e. 
+    - The code needs to be properly formatted (`gradle spotlessApply`)
+    - The code needs to compile
+    - All tests need to succeed
+  - [SonarQube](https://simona.ie3.e-technik.tu-dortmund.de/sonar/dashboard?id=edu.ie3%3Asimona) run succeeds, i.e. 
+    - No new code smells are found 
+    - Code coverage is sufficient
+  - If the project uses readthedocs documentation, the sphinx compilation needs to succeed
+  - Other code checks such as Codacy and sonatype (exceptions can be made for some types of warnings)
+- Manual audits
+  - Changes made to the code have to be reflected within all types of documentation, i.e.
+    - Readthedocs for long form documentation
+    - ScalaDoc/JavaDoc for interface documentation
+    - Code commentary on crucial parts of the code
+  - All vital parts of the new code need to be covered by tests (see {ref}`developersguide:tests`)
+  - Code quality should be sufficient (see {ref}`developersguide:coding conventions`)
+
+There can be exceptions to these rules, which have to be approved by the reviewer.
+
+### Tests
+
+We have good experiences using [ScalaTest](https://www.scalatest.org/) and [Spock](http://spockframework.org/) as testing frameworks.
+Please do not only try to achieve a high _line coverage_, but also aim at covering as many [_branches_](https://en.wikipedia.org/wiki/Code_coverage) as possible.
+In order to execute _all_ available tests, execute `gradle test` or comment `!test` on your PR, which automatically queues a run in our CI.
+
+When practical, we like to use [test driven development (TDD)](https://www.guru99.com/test-driven-development.html):
+It can pay off to write a failing test first for new functionality to be implemented, then implement and alter the actual functionality until the tests pass.
+
+### Coding conventions
+
+The existing code base is not perfect. Still, we strive to continually improve code quality and in turn lower the entry barrier to working with SIMONA.
+Generally, when making changes to the code, we try to follow the _scouts' rule_: We leave the campsite tidier than we found it.
+
+Before marking PRs as ready to review, please make sure to deliver code that follows these basic guidelines:
+- There should be no unreachable or commented out code.
+- Variables and methods should have meaningful names.
+- The code should follow a clear structure.
+- Instead of using very specialized or shortened syntax, rather stick with well-known or easy to grasp forms of code.
+- Imports should be optimized in all changed classes (most of all, there should be no unused imports).
+- Avoid usage of `null` in Scala and Java.
+- Separate classes that hold data from classes that perform functionality.
 
-The convention for merging into the developer branch is that it needs to pass all tests and at least two other active SIMONA developers need to review your changes before merging. Please do this by creating a pull request from any new feature branches into dev. We also encourage you to create pull requests early in your development cycle which gives others an opportunity to observe and/or provide feedback in real time. When you are ready for a review, invite one or more through the pull request.
+Furthermore, there are some functional programming paradigms that we like to follow:
+- If possible, use [immutable objects](https://en.wikipedia.org/wiki/Immutable_object).
+- Write pure methods, avoid [side effects](https://en.wikipedia.org/wiki/Side_effect_(computer_science)). Sending a message (which happens asynchronously) can be considered a side effect too and should be separated from code that is dealing with logic.
+- Use higher-order functions on data structures such as [`map`](https://en.wikipedia.org/wiki/Map_(higher-order_function)), `fold`, `flatten` etc. instead of loops.
 
-Please use the following naming convention for feature branches, “&lt;initials-or-username&lt;/#&lt;issue-number&lt;-&lt;descriptive-feature-branch-name&lt;”. E.g.: ab/#issue123-update-docs
+These guidelines do not intend to be exhaustive. Feel free to extend them with rules that are yet missing.
 
 ## Protocols