FIX: Update and cleanup the peer review section of our guide

[lwasser]

This PR updates the review guides for authors, editors, editor in chief and reviewers. It also cleans up content creating include files for all templated items that may end up in a few places. Finally it ensures that no one page is too long and breaks out content such as finding reviewers into separate pages. this will just make the content easier to read and discover.

[lwasser]

This is a really big PR but it's not new content i'm just cleaning up content. it is ready for review. @NickleDave pinging you here and @arianesasso too

[NickleDave]

👍 edit: just saw you commented in Slack

will prioritize #146 and then review this before Dec 25th at the latest

[lwasser]

awesome and this is a lot of content between the two pr's so if you need more time please take it. thank you @NickleDave !!

I am going to ignore any comments left until I see a message that you have completed your review. :)
i will move on to the package guide for the time being and will forget about these pr's until it's time to work on them again!
THANK YOU

[lwasser]

@leouieda @ocefpaf @xmnlab @yuvipanda @lheagy @xmnlab one. more item to review. This is short. it's the submission template where we collect information about the package before review. if you have time to look at it and provide any feedback please do.

[NickleDave]

Guide is looking better and better! These are mostly little suggested edits, hope some are helpful

[Batalex]

Thank you for your work 🙏

[Batalex]

Did you mean

pyOpenSci [is not just?] open source [...]

?

[lwasser]

yes!

[Batalex]

I have a question, where do we stand about git submodules?

A submodule is not a proper dependency, buuuut it allows to upgrade its content

[lwasser]

this is a really good question. So this topic came up with a previous review - pyOpenSci/software-submission#60 we had to close the issue and reject because they had forked the repo that they were vendoring and then were writing code on top of that fork. The issue there was multi-faceted but frm our perspective it would be VERY hard to find a new maintainer for that kind of custom workflow. I think if it had been a git submodule it could have been ok.

Its funny this came up as it's really an edge case but i'm learning that i think python will be full of edge cases that R doesn't see as often!

technically I don't know how a submodule works for packaging. Can you tell me @Batalex when you implement a submodule and package to tool are you then shipping the tool with both the vendored submodule AND the package itself vs installing as a dependency? many thanks!

[Batalex]

I have only tried once, so I am no expert.
A git submodule allows you to add secondary git folders inside your project. The commit histories would remain separate, however.

Since API wrappers and bindings for other tools are in scope for pyOpenSci, we could end up in a situation where a python package would ship some native lib in a submodule. Any time you want to release a new version, you can git pull the submodule to get the latest commit.

This usage would be pretty marginal though, especially considering that one may use conda to install non-python dependencies.

[lwasser]

thank you so much, @Batalex !! your thoughts here are super helpful!

[arianesasso]

I guess there was a discussion about vignette(s) in slack started by @NickleDave (and now I get it haha 😅). I personally never heard this term before. Maybe we could give an option: Vignette(s)/Snippets (or something more general?).

[lwasser]

@arianesasso yes that word is specific to the R community. In fact if you package an R package there is a vignette function. i'm so used to using it from years of working with R but i wonder if we just want to use short tutorials for Python as most are familiar with it to avoid cognitive overload? i'm somewhat torn on it but most people i meet who don't use python don't know that word?

[arianesasso]

Heey, thanks for clarifying 😄 . I would personally prefer something more general, as you said: short tutorials because then the R community and others could also understand. You could mention (if necessary) something like: short tutorials (for R users, something like vignettes).

[arianesasso]

I am also unsure what differentiates Vignette(s) from Examples 🤔

[lwasser]

yea... @arianesasso your questions are just making me think we should use "short tutorials" what do you think about that?

[arianesasso]

I agree :).

[lwasser]

Suggested change

	JOSS reviews are also [more limited in scope](https://joss.readthedocs.io/en/latest/review_criteria.html)
	JOSS reviews are also [more limited in scope](https://joss.readthedocs.io/en/latest/submitting.html?highlight=scope#submission-requirements)

[lwasser]

Github is doing weird things today but i did fix this locally.

[lwasser]

@arianesasso education is also here because of me :) we could totally revisit this list maybe in a separate PR? discuss it first in an issue if you'd like to open an issue about it.

[arianesasso]

Yes, I will do that! I also saw that in a different thread, so I guess it is time 😄 .

[NickleDave]

plus one!

This also came up in pyOpenSci/python-package-guide#21 -- maybe tag that issue too if you open a new one?

I think the person opening it didn't realize it was on python-packaging-guide instead of peer-review-guide

They specifically talk about the way we list categories now possibly limiting what people might consider in scope
pyOpenSci/python-package-guide#21 (comment)

In addition to revisiting categories, maybe it's worth thinking about what language we use to introduce this section.
Maybe we want to say something like "below is a list of some categories that fall within scope of pyOpenSci and our overall mission of enabling open science with Python. This list is not meant to be exclusive!"

... but I'll save that discussion for a new issue, don't mean to add noise to this review

[lwasser]

ok y'all. this MASSIVE MASSIVE pr that has been worked on for a solid few months is now being merged. ALL - once this is merged, I welcome you to read the document online, submit issues and or pr's for small fixes to the text at ANY TIME. this is not the final final. It's a final draft in my eyes but this guide will be living which means we will continue to update. i think this just sets us up for a usable working guidebook. and ideally maybe we won't have MASSIVE restructuring after this - rather finessing of text and guidelines as we need to.

Many thanks for all of the help with this heavy heavy lift !!