[ENH] Improve submission/reviewing guidelines

[acocac]

Hi @acocac Yes, happy to help develop the submission guidelines, mainly by asking questions to help my understanding of the review process! (and then I can suggest text later).

For example, the Reviewing guidelines state that

the interaction of the authors [and reviewers?] is facilitated through ReviewNB

This would benefit (me at least!) from providing a little more guidance. ReviewNB looks great but I'm not entirely clear on how to use it within the process of deciding on changes (and editing the notebook). For example, I see that I can write responses to comments from reviewers in the text box - should I make a reply about a suggested edit in ReviewNB before making a notebook edit? Or just go ahead and make the notebook edit (see below) as I see fit and then reply? Who clicks the Resolve Conversation button? I assume that's for the reviewer to do once they are happy the comment has been appropriately addressed? How does that link to the editor's responsibility of approving PRs?

Then, the second major issue for me currently: how should I actually make edits to the notebook in response to the reviewer comments? I saw you have made some commits (editing file paths), so I pulled the repo - that has brought in the change that you made to the notebook file (now named general-exploration-landcover_io.ipyn) but not your suggested edits in the notebook itself. I then realised that's because I pulled from the main branch, but your edits within the notebook are on the review_round1 branch with an outstanding PR than needs to be merged to main.

As you noted above, you are editor so have responsibility for approving PRs. Do I just checkout the review_round1 branch, make edits, and submit PRs that you (as editor) then deal with merging into main? (What it a reviewer doesn't like my edit - which links back to my first set of questions).

Thanks!

_Originally posted by @jamesdamillington in eds-book-gallery/notebooks-ideas#7

[jamesdamillington]

Suggestions for guidelines (I will add to this list as points occur to me as we work through the review of my notebook):

• many of my comments below are about the review process (not how reviewers should act). So, I wonder if the Review Guidelines page then should either be renamed to Review Process, or a Review Process page should be added with content aimed at understanding the review process overall with the Review Guidelines page reserved for content aimed at what reviewers should be looking for when reviewing, etc.
• regardless of whether a new page is made, a flowchart showing how the review process is expected to proceed might be useful
• make clear that a 'review branch' will be created and that this is where commits should be made through the review process
• explain that commits on the 'review branch' will then appear in the ReviewNB render
• clarify what the order of responding to review comments should be (if any) - comment and commit at the same time? comment then wait for confirmation to commit?
• clarify any other preferred best practice for commits and comments - one commit per comment? how to link commits to comments