contributing to the documentation

[carbonatezero]

Hello. I'm interested in contributing to the documentation of the OpenDA project and would like to help edit the files in the doc directory. In addition to the "contributing guidelines", what would be the best practice to do so?

[theavuik]

At this moment, we are shifting from documentation in the OpenDA repository to documentation on docs.openda.org
As long as we are not completely finished, the old documentation is still found in the repo (but it is no longer updated).
Adding to the new documentation could be done via pull requests in the GitHub repo.

Could you point us to the information that you would like to update?

[carbonatezero]

@theavuik Thank you for responding. There are several places.

One is the Course pdf with description and exercises in docs.openda.org. I find typos and formatting that can be improved. But I'm not sure if the authors prefer to keep it as it was since these are historical lecture notes.

[nilsvanvelzen]

Hi @carbonatezero. Nice to hear that you are willing to contribute! I See you have explicitly linked to the course material/documentation. To put is a bit in perspective. The course is a living document/set of model input. Every time a course is organised we select the relevant exercises, fix issues/update when needed. Hence the exercises that are included in openda_course.tex are used at the last course and should be the most up to date/work properly. For contributing I suppose you should be able to create pull requests which is easy for smal suggestions/updates or additions and we can always discuss things here at the discussion forum.

[carbonatezero]

@nilsvanvelzen Thank you for getting back to me. I must admit that I am not an experienced developer, so my contribution may be limited to spotting typos and suggesting formatting improvements in the documentation. I believe that inexperienced users like me would benefit from more comprehensive documentation. I will make some pull requests to see how things progress.

[carbonatezero]

The guideline says "Ask a core-developer of OpenDA to create a branch where you can push your contributions." I forked the master branch. Which branch should I push to?

[nilsvanvelzen]

Hi @carbonatezero. I think a slightly different approach is "The GitHub way" If you fork our repository on GitHub. (button at top of GitHub). You can make your improvements on a branch of your forked repository (thanks!). When done you can create a pull request from you forked repository to the master on our repository. (in our GitHub "Pull requests-> New Pull request and select compare across forks". That should work and if not, let me know. In case that does not work I can merge the changes from your forked repository.

[carbonatezero]

Hi @nilsvanvelzen, I have successfully submitted a pull request for OpenDA-Association/OpenDA at #285.

I would appreciate it if you could confirm if I have followed the appropriate procedures. If this is the correct way to do it, I plan to contribute in a similar way in the future.

Thank you for your time and guidance.

[nilsvanvelzen]

Thank you. Is it correct that this first pull request is only a tiny single file change? I have accepted it and this is indeed the preferred way. I only advise (for you ease) to keep "your" master completely in sync with ours and work on a branch on you repository. I suppose you can create a pull request from your branch to our master as well.

If possible, you can assign me as your reviewer. In that way (I hope) I get a notification mail for the pull request.

[carbonatezero]

Hello @nilsvanvelzen, yes I made a small change to the code in order to experiment with how to create a correct pull request. Your advice has been really helpful, and I appreciate it. In the future, I will make sure to work on a separate branch to keep my "master" branch untouched.

I would like to assign you as the reviewer for my pull request. However, when I navigated to the Reviewers section on this page (#286), I couldn't find any options. Could you please let me know if this is due to the settings of the OpenDA repository or if I am missing something? Thank you.

[nilsvanvelzen]

It might be the case that non-core developers cannot assign a reviewer. No problem. I should get notifications of you pull requests (now). Thanks again for your contributions.