Improve organisation of main GitHub page (https://github.com/BaRatin-tools/BaRatinAGE)

[benRenard]

Currently the README.md provides a very general overview (OK but could be improved), but then the fact that there is also a README.txt is confusing: should we remove it and merge it into README.md? Or rename it e.g. VersionNotes.md? or use this file as a VersionNotes file?

In addition, renaming some compilation-related files (wind_dist.ps1 and DevMiscInfo.md) to make their purpose more explicit would be useful.

[IvanHeriver]

Very good point. I suggest the README.md file should contain the following 3 sections:

• General overview as it does today
• Usage Instruction: details on how to get, install and use BaRatinAGE (with links to help, website, etc.) (i.e. kind of what is currently in ReadMe.txt)
• Development instutruction: details on how to setup a development environment for BaRatinAGE and compile it (i.e. an updated version of what is in the file DevMiscInfo.md)

With these changes, ReadMe.txt and DevMiscInfo.md could be deleted.

The file win_dist.ps1 is obsolete and can be deleted right away. Everything is handled by Ant and its configuration file build.xml.

What do you think?

[IvanHeriver]

I finally chose to use two separate files: README.md and CONTRIBUTING.md files

README.md

It is now a rather important file since it is the one people see when arriving on the github page and I also added it at the root of the final distributable zip file (I added a copy step in the build.xml file).

I'm sure there are some typos so please have a look, @JeromeLeCoz and @benRenard! I also took the liberty to write new content, so please make sure you're ok with what I wrote.

CONTRIBUTING.md

this file contains developer related stuff (english only)

[JeromeLeCoz]

Je recorrige car Ben a été plus rapide que moi, j'ai pas pu committer mes corrections!

[benRenard]

Sorry Jerome... Indeed I just pushed minor fixes for the README - please check you're OK with them.

Same thing for the CONTRIBUTING file, a few minor fixes, but I also have a few suggestions for you to consider Ivan (I haven't made the changes, please decide!)

• "an IDE that you've set up correctly for Java": add what we use or suggest?
• In the Java version section, be more explicit on what we use and where/how to install it? for instance we could make explicit the 'apt install openjdk-17-jdk' (and not jre or headless or what else) issue that confused us yesterday
• "update the env variable by adding the path C:\Program Files\Java\apache-maven-3.8.6\bin": explain how to do it?

I think you can close the ticket after that.

[JeromeLeCoz]

No problem, I've updated your edited version.

[IvanHeriver]

See commit 7e2693a452d80643f121320fcf965f54d8178147

---

"an IDE that you've set up correctly for Java": add what we use or suggest?

I prefere not suggesting anything, at least for now. I've been using VS code with Java for too short a time period to confortably recommend it. And I'm not a fan of Eclipse...

I think we should assume that people contributing have enough knowledge/background/skills to set things up the way they like. CONTRIBUTING.md should contain only things closely related to the BaRatinAGE project.

In the Java version section, be more explicit on what we use and where/how to install it? for instance we could make explicit the 'apt install openjdk-17-jdk' (and not jre or headless or what else) issue that confused us yesterday

Agreed! I made some changes to mention that version 17 is recommended and added the command line to install the right version of the openJDK on linux.

"update the env variable by adding the path C:\Program Files\Java\apache-maven-3.8.6\bin": explain how to do it?

I think this is a knowledge which we should expect from anyone contributing and using windows... Nevertheless, I added a link to tutorial on how to change an environment variable but I'm not convinced it's a good idea.