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 - 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

---

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 :)

[lwasser]

Ok friends. i'm so so behind on this repo. I wonder if we can break this into sub issues that people could tackle? Jonny i'm going to take a stab at doing that. The one challenge potentially with reformatting the front matter (i agree it would be lovely to have a table!) is that we'd have to consider all of or older issues and the pipelines that parse the text in those issues. but it would make the issues much easier to scan. but for now i'm going to create sub issues and flag ones that people could easily take on and complete.