diff --git a/how-to/author-guide.md b/how-to/author-guide.md index 18f8cea1..27a16d50 100644 --- a/how-to/author-guide.md +++ b/how-to/author-guide.md @@ -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?** @@ -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. + +### 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. +- **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. +- **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 @@ -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 @@ -232,7 +254,7 @@ 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 @@ -240,7 +262,7 @@ 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.