enh(author-guide): Add discussion about when a package is good enough for review #361
Conversation
Co-authored-by: Jonny Saunders <sneakers-the-rat@protonmail.com>
|
|
||
| - **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. |
There was a problem hiding this comment.
We reference the README specifically in the next bullet so I'm not sure it needs to be included here.
| 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. |
There was a problem hiding this comment.
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?
| ## 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. |
There was a problem hiding this comment.
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."
Closes #101
Used AI agent for summarizing discussions and updates to guide.