Hi all, we have two packages in review for which similar discussions have arisen around “good, better, best” guidelines:
Should pyOpenSci aim to have all components be at least “good” and ask to reviewers to provide recommendations for better and best, but not let that limit approval?
More specifically, how should the review process distinguish between required and recommended changes, as identified by the reviewers?
As one example, the review template provides a requirement of
Examples for all user-facing functions, and one reviewer noted that not all docstrings for user facing functions had examples. However, there were many examples in the provided tutorials.
As of right now, the submitting author has addressed this comment by adding examples (and links to the tutorials) to all user-facing functions, except those that could be considered to be self-explanatory (because they have either no parameters or have only simple parameters that are sufficiently described in the corresponding parameters section).
So in this example, is adding examples to ALL docstrings for user facing functions considered a required or recommended change?
We plan to discuss this further at our upcoming meeting on 2/28 11am MDT (meeting notes here) and also welcome comments and thoughts on this post.
Thanks and looking forward to hearing everyone’s thoughts!