Notes from an editor dogfooding a review

[sneakers-the-rat]

If it's cool, can I take notes as I work as an editor on a review of small things that come up that may or may not rise to the level of an issue, are worth tracking, but I don't want to open a million issues before completing the process and checking that these things are documented/etc. elsewhere? As I go i'll raise separate issues as necessary and then close this. If that's not cool I can close this and only raise the issues.

• Finding reviewers - apparently there is a reviewer signup! mentioned in the editor slack channel and needs to make it into the docs
• Finding reviewers - would be nice to do a default announcement on socials for calls for new reviewers (for reviews that dont' already have people signed up)
• Review Flow - It would be nice to put all metadata for the review as skimmable bullet points in the root post of the review issue. Things that need to make it up there:
  • Review start date/reviewers assigned date
  • Review deadline
  • Links to reviewer comments

---

• Review UX - It would be good to do a little formatting for the initial header post, either by putting it in a table or using bolding to offset field names and values.

Currently looks like this:

Submitting Author: Name (@\username)
All current maintainers: @\username ...
Package Name: Plenoptic
One-Line Description of Package: a python library for model-based synthesis of perceptual stimuli
Repository Link: https://github.com/labForComputationalVision/plenoptic/
Version submitted: v1.0.2
Editor: @\username
Reviewer 1: @\username
Reviewer 2: @\username
Reviewers assigned: 2023-12-13
Reviews due: 2024-01-05
Archive: TBD
JOSS DOI: TBD
Version accepted: TBD
Date accepted (month/day/year): TBD

As a table:

Plenoptic
Submitting Author	Name (@\username)
Current maintainers	@\username ...
One-Line Description of Package	a python library for model-based synthesis of perceptual stimuli
Repository Link	https://github.com/labForComputationalVision/plenoptic/
Version submitted	v1.0.2
Editor	@\username
Reviewer 1	@\username
Reviewer 2	@\username
Reviewers assigned	2023-12-13
Reviews due	2024-01-05
Archive	TBD
JOSS DOI	TBD
Version accepted	TBD
Date accepted	TBD

As a list with bolding:

• Submitting Author: Name (@\username)
• All current maintainers: @\username ...
• Package Name: Plenoptic
• One-Line Description of Package: a python library for model-based synthesis of perceptual stimuli
• Repository Link: https://github.com/labForComputationalVision/plenoptic/
• Version submitted: v1.0.2
• Editor: @\username
• Reviewer 1: @\username
• Reviewer 2: @\username
• Reviewers assigned: 2023-12-13
• Reviews due: 2024-01-05
• Archive: TBD
• JOSS DOI: TBD
• Version accepted: TBD
• Date accepted (month/day/year): TBD

---

• Docs - It would be nice to make the steps in the guide match the steps in the review. Currently the ToC here doesn't lend itself to being a quick reference to use during a review, mostly because a lot of the background information needs to be collapsed into second-tier ToC elements and the titles for the process checklist should probably be changed to match the review stages.

Currently it looks like this:

Guide	Tags
Editor Checklist: : Get Started With Leading a Package Review
1. First, tag the submission issue on GitHub	1/editor-checks
2. Respond to the submitter in the GitHub issue	2/seeking-reviewers
3. Identify scientific Python package reviewers
Finding package reviewers
4. Onboard reviewers	3/reviewers-assigned
Editor responsibilities during the review
5. What to do when reviews are in	4/review-in-awaiting-changes
	5/awaiting-reviewer-response
6. How to accept a package into the pyOpenSci ecosystem	6/pyOS-approved
OPTIONAL: Instructions for Submitting to JOSS	7/under-joss-review
	9/joss-approved
Last Steps Before Closing the Review Issue

Which is sort of hard to follow. I think with some simple restructuring we could make each phase in the review match across the docs and the tags - "if i am on step 3/reviewers-assigned, i go to the "3: Reviewers Assigned" section in the docs to see what to do"

---

• Docs - is there a step 8 between under joss review and joss approved?
• Docs - reviewer is not sure what a "vignette" is, recommend adding a link to Vignettes (see Plenoptic software-submission#150 (comment) )

[lwasser]

@sneakers-the-rat thank you for this. it's more than cool - it's appreciated!! let me know when i should look more closely at this in terms of following up with content fixes!!

[sneakers-the-rat]

Two more things as im completing the review:

• its not clear to me what I need to do to finalize it, there is a bit of a gap in the guide between finishing the review and closing the issue - how do I put the package on the website? Or is that not for the editor to do?
• the final checklist invites them to write a blog post - how should they do that? Can we give them more specific instructions on submitting one?

[Batalex]

There is an action to publish the package on the website, but it sometimes needs a manual trigger. I asked Leah last time I wrapped up a review.
As for the blog post, I think we can write a quick section on how to proceed because it should not be too complicated: a shared Gdoc, an (optional) outline and the agreement that we can offer suggestions on the content.

[sneakers-the-rat]

There is an action to publish the package on the website, but it sometimes needs a manual trigger. I asked Leah last time I wrapped up a review.

fabulous, then lets add that to the editor guide :)

As for the blog post, I think we can write a quick section on how to proceed because it should not be too complicated: a shared Gdoc, an (optional) outline and the agreement that we can offer suggestions on the content.

Since i am assuming the blog post would eventually be a jekyll markdown document pulled here: https://github.com/pyOpenSci/pyopensci.github.io/tree/main/_posts
could we just say that they should open a PR to that effect? seems weird to edit a markdown document on a google doc and make a new workflow (eg. to whom would they send the google doc link? who would review it? how would it eventually be added to the site?) when a PR is right there :)