COSIMA
Collate documentation
The amazing-super-fun hackathon made me want to review pull requests, and since I didn't go to the review tutorial because I had some even more basic git/github pitfalls, I missed out on learning that day. So I searched for documentation/step-by-step tutorials on how to do it because I wanted to run the notebooks to test them which is not as trivial as opening reviewNB and commenting. I have not found that documentation, but did receive help from people via chat. There are two possibilities:
- My searching skills are flawed (probably true) and said documentation exists somewhere.
- Documentation does not exist.
I think in either case, it would be cool to populate the repo Wiki so that others that struggle like me have 1 place and only 1 place where to go to follow steps that enable them to contribute to the recipes. Hopefully this boosts participation outside of the hackathons.
Thoughts?
I am happy to do this if people agree, and if someone wants to suffer with me please join :)
Did you find this documentation that @navidcy recently made? https://cosima-recipes.readthedocs.io/en/latest/contributing.html#reviewing-existing-pull-requests
I think it would be great to expand this step:
- Clone the repository or the fork that the pull request was made from;
to be easier by suggesting people do the 'Checkout with GitHub CLI' instead, and adding some instructions on how to do that.
Also, maybe we could make a link to the above contribution docs on this 'Beginners Guide to the COSIMA Cookbook' page? I find it confusing that we have these 2 sets of different documentation pages.
Also, I find it quite confusing that the 'Beginners Guide to the COSIMA Cookbook' is at cosima-cookbook/wiki, not the cosima-recipes/wiki, because the most useful thing there is instructions on how to get the recipes working. Maybe that will get fixed if we go through with renaming this repository?
Thanks @julia-neme for opening this! Already it paved the way for @adele-morrison to express her confusion. I'm happy to hear more points of confusion from everyone so we resolve them!
Sidenote: It's not related with this issue but I think renaming the repo will create huge issues... For example, consider all the posts in the forum linking to issues in this repo being broken.... I'll open another issue to discuss this and will put my reservations there.
I'm not sure I feel super strongly either way on the renaming the repo topic, but just to note (from here):
When you rename a repository, all existing information, with the exception of project site URLs, is automatically redirected to the new name, including:
- Issues
- Wikis
- Stars
- Followers
It’s unrelated to this issue
I'm not sure I feel super strongly either way on the renaming the repo topic, but just to note (from here):
When you rename a repository, all existing information, with the exception of project site URLs, is automatically redirected to the new name, including:
- Issues
- Wikis
- Stars
- Followers
Yes. But we are proposing to rename it to a name that already is a different repository!
Btw, the Beginners Guide to the COSIMA Cookbook will become deprecated with the ACCESS Intake. So let's not put too much effort in it....?
I stumbled upon this excellent blogpost on reviewing code. Should we add a url somewhere?
https://www.alexandra-hill.com/2018/06/25/the-art-of-giving-and-receiving-code-reviews/
Here’s a youtube video of the blog above!
https://youtu.be/XY6eA2_2hOg?si=CDyUJ-FOqwo0JzxL
Do you think making short videos will make things clearer? I am thinking maybe making 2-3 minute videos showing how to do the basics will make following instructions easier.
Also, is there a way to pin these resources in the ACCESS-NRI forum? I am thinking just a post with useful links, nothing too complicated, but that would hopefully point people in the right direction.
Also, I think it is a good idea to include the resources you shared @navidcy
I have done a first draft of a wiki, where you can find (or I hope you can) all the steps to start contributing and reviewing using gadi/git/github. I've linked to github tutorials in some places, and wrote the steps I have used in others.
This is probably riddled with mistakes/not-best-practices. I would really appreciate people that are github savvy and total newbies to try some/all steps and edit where you see fit.
I think we should choose between having a wiki or a readthedocs.io, not have both. Having just one is cleaner and avoids redundancy. I am partial to the wiki because I find it more intuitive to find, but the wiki is also really easy to copy into the readthedocs.io if that's what people want! I would add a page with tips for good recipes/best practices with the stuff that's in readthedocs.io and what @navidcy talked about in the hackathon.
Let's add a link to the repo's wiki in the README and in the readthedocs.io?
I vote for the wiki and delete/shift over the readthedocs.io page. That way everything is at the same github repo link.
No, I suggest moving the info from readthedocs.io to the github wiki page. Then delete the readthedocs. Though maybe there is some good reason to have it there that I don't know about?
Gotcha. I think everything (related instructions, cloning, contributions, PR reviewing etc) in the wiki would work!
Btw I opened https://github.com/COSIMA/cosima-cookbook/issues/343 which is related.
I don't have a view either way but one difference between a wiki and readthedocs is how they are authored.
A wiki can typically be edited, without review, by anyone with write access to the repository. For new and occasional contributors this may prevent them being able to make changes. (Although the access permissions can be changed, you can allow edits from anyone)
Readthedocs is within the repository, so changes are made by pull request and therefore require review also. Anyone can submit a pull request (and they don't need write access).
I do prefer the readdocs place for things to be (for the reasons @anton-seaice mentioned!).
But, more importantly, I think it's good to have everything in one place! And that we actually have the information written down!
People are generally very reluctant in opening PRs and contributing, so when someone said "I'll make a wiki.." I was so excited that I didn't wanna add extra layers of complications.
So I suggest we gather everything in the cosima-recipe's wiki now, since after @julia-neme's attempt it's mostly there. Afterwards it would be very easy to move everything in the readdocs if we wanted to.
It seems easy to transfer from one place to another! Why don't we keep editing in the wiki until more or less satisfied and then we decided? In my mind there seem to be two other things to include:
- Relevant info from the cosima-cookbook wiki
- Good practices on reviewing/documenting/etc by @navidcy
@julia-neme is there anything else from the COSIMA-Cookbook Wiki that needs to come over or should we go ahead and delete that one and replace it with a link to this repo's wiki?
I think the wiki is done except for a new FAQ page. I don't think there is anything missing from the cookbook wiki. Please look at the FAQs and edit away. Or just delete the page if its not useful.
What should we do now?
- Option 1: put the wiki into readthedocs.io
- Option 2: do a couple of new pages in the wiki with tips on contributing etc.
What do people think? Move wiki to readthedocs or move readthedocs to the wiki? @navidcy @adele-morrison @edoddridge @lidefi87 and others?
I prefer the wiki, because then everything is at the same weblink, and it's easy to navigate back to the code. But I can see the benefit of requiring review on readthedocs if others prefer that.
Wiki is at https://github.com/COSIMA/cosima-recipes/wiki, which has a 'Code' link in the top bar to take you back directly to the recipes.
Readthedocs is at https://cosima-recipes.readthedocs.io/en/latest/. I always find it tricky to navigate from there back to https://github.com/COSIMA/cosima-recipes.
we can always fix that! the trick is to voice that you'd like that (as you did now!) :)
Perhaps unhelpfully, I would prefer it be part of read the docs. That way, all the user facing information is on the same site. It's a fair point though @adele-morrison. Would including a link back to GH on the main page be sufficient?
