Skip to content

enh(author-guide): Add discussion about when a package is good enough for review #361

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
eliotwrobson wants to merge 2 commits into
base: main
Choose a base branch
from
Open

enh(author-guide): Add discussion about when a package is good enough for review #361

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5a3a38c
Update author-guide.md
eliotwrobson Dec 16, 2025
49c6bc8
Update how-to/author-guide.md
eliotwrobson Dec 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 28 additions & 6 deletions how-to/author-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,6 @@ for Python packaging, including discussions of:
Given the increased use of Generative AI tools (LLMs), we have developed a disclosure policy for all packages submitted to pyOpenSci (generative-ai-policy). Please review this before submitting to us.
:::


```{hint}
**Do you have questions about Python packaging or our peer review process?**

Expand Down Expand Up @@ -203,13 +202,36 @@ Our current categories for determining package scope are below:
Click here to view our technical and domain scope requirements.
```

## 4. Submit your package for peer review
## 4. Prepare your package for peer review

Please consider the best time in your package's development to submit for review. Your package should be sufficiently mature so that reviewers can review all essential aspects. Keep in mind that review may result in major changes.
Copy link
Contributor

@eigenbrot eigenbrot Dec 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first two sentences here read a bit awkward to me. Maybe something like "Packages submitted for review should be mature enough that reviewers can review all of its essential aspects." could read better?? I'm not sure the current first sentence is doing much lifting.

Also, it might look good to bold "may result in major changes."


### When to submit

Your package is ready for review when:

- **Functions and classes (the API) are stable or close to reaching stability** after the review is complete. "Stable" means that the scope of the package is settled and well defined, and that backwards-incompatible changes to the API will be managed carefully.
- **Major changes and refactoring can still be carried out after review** but should not be a frequent occurrence.
Copy link
Contributor

@eigenbrot eigenbrot Dec 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The wording of this bullet is kind of opposite of the other bullets; they all describe a desired state of affairs while this bullet bolds a thing that should be minimized. Perhaps something like "The scope and factoring of the code are relatively stable. Major changes and refactor can still be carried out but should not be frequent." could work?

- **Most functionality should be clearly documented and tested**. At the submission stage, all major functions should be stable enough to be fully documented and tested. The README should make a strong case for the package.
Copy link
Contributor

@eigenbrot eigenbrot Dec 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We reference the README specifically in the next bullet so I'm not sure it needs to be included here.

- **The README provides enough information** about your package (goals, usage, similar packages) for the editors to assess its scope without having to install the package.

### Review before publication

We strongly suggest submitting your package for review **before submitting a software paper** describing the package to a journal. Review feedback may result in major improvements and updates to your package, including renaming and breaking changes to functions.

```{note}
Many Python packages are published to PyPI in alpha/beta stages to attract early users and contributors. Publishing to PyPI before review is acceptable and often beneficial for package development.
```

Your package will continue to evolve after review. For guidance on this topic, see our [post-review process documentation](post-review-process).

## 5. Submit your package for peer review

To submit your package for peer review, you can
open an issue in our [pyopensci/software-review repo](https://github.com/pyOpenSci/software-review/issues/new/choose/)
repository and fill out the [Submit Software for Review](https://github.com/pyOpenSci/software-submission/issues/new?template=submit-software-for-review.md) issue template.

## 5. Editor-in-Chief reviews package for scope and minimal infrastructure criteria
## 6. Editor-in-Chief reviews package for scope and minimal infrastructure criteria

Once the issue is opened, our editor-in-chief and an editor from our editorial board will review your submission within
**2 weeks** and respond with next steps. The editor may request that you make updates
Expand All @@ -222,7 +244,7 @@ package if it does not fall within our scope.
Click here to view the editor checks that will be used to evaluate your package.
```

## 6. The review begins
## 7. The review begins

If your package meets the minimal criteria for being
reviewed, it may then be given to an editor with appropriate domain experience
Expand All @@ -232,15 +254,15 @@ issue within **3 weeks**. Reviewers can also open issues in your package reposit
We prefer issues that link back to the review as they document changes made to your
package that were triggered by our review process.

## 7. Response to reviews
## 8. Response to reviews

You should respond to reviewers’ comments within **2 weeks** of the
last-submitted review. You can make updates to your package at any time. We
encourage ongoing conversations between authors and reviewers. See the
[guide for package reviewers](reviewer-guide.md) for more details about reviewers' engagement with package
maintainers during a review.

## 8. Acceptance into pyOpenSci
## 9. Acceptance into pyOpenSci

Once the reviewers are happy with the changes that you've made to the package, the
editor will review everything and accept your package into the pyOpenSci ecosystem.
Expand Down
Loading