Expanding guidelines for contributions - [merged] #1540

Closed SGeeversAtVortech closed 3 weeks ago

In GitLab by @jarsarasty on Oct 24, 2023, 12:01

_Merges guidelinescontributions -> master

This commit extends the guidelines for community contributions to RTC tools. It defines guidelines for creating issues and merge requests, and explains the procedure for submitting changes. This commit also includes an additional description of RTC-Tools in the Readme.md file.

In GitLab by @SGeeversAtVortech on Nov 17, 2023, 09:42

Commented on CONTRIBUTING.md line 34

Maybe rename this point to "Crete merge request"? And also provide the link to where the user can create this request. And I'd suggest to move this point to the end, just before "Code review".

In GitLab by @SGeeversAtVortech on Nov 17, 2023, 10:01

A general remark on paragraphs in markdown: you can write separate sentences on separate lines. As long as there is no blank line in between, the markdown viewer will still convert it to a single paragraph. This way you can avoid these very long lines.

In GitLab by @SGeeversAtVortech on Nov 17, 2023, 10:24

Commented on README.md line 9

This lists some features of rtc-tools, but not necessarily the basic functionalities. I would list something like this:

The core functionalities of RTC-Tools are:

Build Models: Build complex models using the Modelica language [link to https://modelica.org/]. RTC-Tools also provides the following Modelica libraries for specific applications:

[rtc-tools-channel-flow]: water system models
[rtc-tools-heat-network]: heat networks
... I would provide a link to these libraries, but not too much details here. For details, people can read the readme of the given library.

Build and solve optimization problems: Build and solve an optimization problem for a given model.

Run simulations: Run a simulation for a given model.

I would list other features such as goal programming and optimizing for scenario tress in a separate list.

Features of RTC-Tools include:

Goal programming: ...

Scenario trees: ...

Multiple input/output formats: list formats like csv and xml for reading/writing timeseries. Perhaps mention we also support xml formats used by Delft-FEWS.

In GitLab by @SGeeversAtVortech on Nov 17, 2023, 10:30

Looks good, big improvement from the previous version! I still have a few remarks, especially concerning the list of features in README.md.

In GitLab by @jarsarasty on Nov 21, 2023, 13:42

Commented on CONTRIBUTING.md line 16

changed this line in version 6 of the diff

In GitLab by @jarsarasty on Nov 21, 2023, 13:42

Commented on CONTRIBUTING.md line 33

changed this line in version 6 of the diff

In GitLab by @jarsarasty on Nov 21, 2023, 13:42

Commented on CONTRIBUTING.md line 35

changed this line in version 6 of the diff

In GitLab by @jarsarasty on Nov 21, 2023, 13:42

Commented on CONTRIBUTING.md line 34

changed this line in version 6 of the diff

In GitLab by @jarsarasty on Nov 21, 2023, 13:42

added 1 commit

6acd6e79 - doc: content and format adjustments

Compare with previous version

In GitLab by @jarsarasty on Nov 21, 2023, 13:52

added 1 commit

08fb7771 - doc: formatting

Compare with previous version

In GitLab by @jarsarasty on Nov 21, 2023, 13:57

Thanks, @SGeeversAtVortech ! I made the changes, as suggested.

In GitLab by @jarsarasty on Nov 21, 2023, 14:54

resolved all threads

In GitLab by @jarsarasty on Nov 22, 2023, 10:27

added 1 commit

6856f72f - doc: small changes in readme

Compare with previous version

In GitLab by @jarsarasty on Nov 22, 2023, 10:31

Hi @baayen, As per our previous conversation, we are expanding the RTC description in the readme file. We are trying to make this description general enough while keeping it concise. Could you please take a look and let us know if you think we should add or change anything?

In GitLab by @baayen on Nov 28, 2023, 14:18

Commented on CONTRIBUTING.md line 176

This section has no informational value and as such I would suggest to drop it.

In GitLab by @baayen on Nov 28, 2023, 14:19

Commented on README.md line 7

I would rephrase this as follows:

RTC-Tools is an open-source Python package for simulation and optimization of cyber-physical systems. It can be used for model-predictive control and operational decision making of water and energy systems. It is developed by Deltares in collaboration with partners.

In GitLab by @baayen on Nov 28, 2023, 14:20

Commented on README.md line 16

Add a statement that this list is non-exhaustive, and that new libraries may be created for new types of applications.

In GitLab by @baayen on Nov 28, 2023, 14:20

Commented on README.md line 18

Runing -> Running

"Simulate a given model"

In GitLab by @baayen on Nov 28, 2023, 14:21

Commented on README.md line 20

RT-Tools -> RTC-Tools

Mention Ipopt as one of the open-source solvers.

In GitLab by @baayen on Nov 28, 2023, 14:21

Commented on README.md line 26

hierarchical -> sequential

In GitLab by @baayen on Nov 28, 2023, 14:22

Commented on README.md line 30

CSV and XML (capitals). Mention that support for other formats can be implemented using mixins.

In GitLab by @baayen on Nov 28, 2023, 14:23

Commented on README.md line 32

framwork -> Framework

"RTC-Tools uses the CasADi framework for algorithmic differentiation, as well as for interfacing with numerical optimization solvers."

In GitLab by @baayen on Nov 28, 2023, 14:24

Commented on CONTRIBUTING.md line 4

I would suggest dropping the above two sentences, and simply focusing on the "business"/"mechanics" of contributing, as below.

In GitLab by @jarsarasty on Nov 28, 2023, 16:24

resolved all threads

In GitLab by @jarsarasty on Nov 28, 2023, 16:25

Thanks for the feedback, @baayen !