Revision of Guide for Authors for #366 (#371)

Co-authored-by: Maëlle Salmon <[email protected]>

DESCRIPTION

@@ -2,7 +2,7 @@ Package: placeholder
 Type: Website
 Title: rOpenSci Packages: Development, Maintenance, and Peer Review
 Description: rOpenSci Packages: Development, Maintenance, and Peer Review
-Version: 0.0.1
+Version: 0.0.1.001
 Imports:
     airtabler,
     htmltools,

appendix.Rmd

@@ -4,6 +4,8 @@
 
 ## dev
 
+- 2022-01-10, divide author's guide into sub-sections, and add extra info including `pkgcheck`.
+
 * 2021-11-30, adds links to examples of reviews, especially tough but constructive ones (with help from `@noamross`, `@mpadge`, #363).
 
 * 2021-11-19, add recommended spatial packages to scaffolding section (software-review-meta#47)

softwarereview_author.Rmd

@@ -4,23 +4,40 @@
 This concise guide presents the software peer review process for you as a package author.
 ```
 
--   Consult our [policies](#policies) see if your package meets our criteria for fitting into our suite and is not overlapping with other packages.
+## Planning a Submission (or a Pre-Submission Enquiry)
+
+-   Consult our [policies](#policies) see if your package meets our criteria for fitting into our suite and does not overlap with other packages.
     -    If you are unsure whether a package meets our criteria, feel free to open an issue as a pre-submission inquiry to ask if the package is appropriate.
--   Use [pkgcheck](https://docs.ropensci.org/pkgcheck/), read and follow [our packaging style guide](#building), [reviewer's guide](#preparereview) to ensure your package meets our style and quality criteria.
-    -   If you feel your package is in scope for the
-        [Journal of Open-Source Software](https://joss.theoj.org/) (JOSS), do not submit it to JOSS consideration until after the rOpenSci review process is over: if your package is deemed in scope by JOSS editors, only the accompanying short paper would be reviewed, (not the software that will have been extended reviewed by rOpenSci by that time). Not all rOpenSci packages will meet the criteria for JOSS.
 - Please consider the best time in your package's development to submit.  Your package should be sufficiently mature so that reviewers are able to review all essential aspects, but keep in mind that review may result in major changes.
-    - For any submission or pre-submission inquiry the README of your package should provide enough information about your package (goals, usage, similar packages) for the editors to assess its scope without having to install the package. Even better, set up a pkgdown website for allowing more detailed assessment of functionality online.
-    - If you use [repostatus.org badges](https://www.repostatus.org/) (which we recommend), submit when you're ready to get an _Active_ instead of _WIP_ badge. Similarly, if you use [lifecycle badges](https://www.tidyverse.org/lifecycle/), submission should happen if the package is at least _Maturing_.
-    - 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 editors will read it to e.g. evaluate this as in scope or not.).
     - We strongly suggest submitting your package for review _before_ publishing on CRAN or 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.
-    - Your package will continue to evolve after review, this book [provides guidance about the topic](#evolution).
-- In your initial (pre-)submission and README, strive to explain your package's functionality and aim assuming little to no domain knowledge from the reader. E.g. if you wrote something to interact with knitr engines, what's a knitr engine?
--   Do not submit your package for review while it or an associated manuscript is also under review at another venue, as this may result on conflicting requests for changes.
--   Next, [open a new issue](https://github.com/ropensci/software-review/issues/new/choose) in
-the software review repository and fill out the template.
+    -   Do not submit your package for review while it or an associated manuscript is also under review at another venue, as this may result in conflicting requests for changes.
+- If you use [repostatus.org badges](https://www.repostatus.org/) (which we recommend), submit when you're ready to get an _Active_ instead of _WIP_ badge. Similarly, if you use [lifecycle badges](https://www.tidyverse.org/lifecycle/), submission should happen when the package is at least _Maturing_.
+- For any submission or pre-submission inquiry the README of your package should provide enough information about your package (goals, usage, similar packages) for the editors to assess its scope without having to install the package. Even better, set up a pkgdown website for allowing more detailed assessment of functionality online.
+    - 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.
+    - Your README file should strive to explain your package's functionality and aims, assuming readers have little to no domain knowledge. All technical tems, including references to other software, should be clarified.
+- Your package will continue to evolve after review, the chapter on *Package evolution* [provides guidance about the topic](#evolution).
+
+## Preparing for Submission
+
+-   Read and follow [our packaging style guide](#building), [reviewer's guide](#preparereview) to ensure your package meets our style and quality criteria.
+-   Feel free to ask any questions about the process, or your specific package, in our [Discussion Forum](https://discuss.ropensci.org).
+-   All submissions are automatically checked by our [pkgcheck](https://docs.ropensci.org/pkgcheck/) system to ensure packages follow our guidelines. All authors are expected to have run [the main `pkgcheck()` function](https://docs.ropensci.org/pkgcheck/reference/pkgcheck.html) locally to confirm that the package may be submitted.
+-   If there are any aspects of `pkgcheck` which your package is unable to pass, please explain reasons in your submission template.
+-   If you feel your package is in scope for the
+    [Journal of Open-Source Software](https://joss.theoj.org/) (JOSS), do not submit it to JOSS consideration until after the rOpenSci review process is over: if your package is deemed in scope by JOSS editors, only the accompanying short paper would be reviewed, (not the software that will have been extended reviewed by rOpenSci by that time). Not all rOpenSci packages will meet the criteria for JOSS.
+
+## The Submission Process
+
+-   Software is submitted for review by [opening a new issue](https://github.com/ropensci/software-review/issues/new/choose) in the software review repository and filling out the template.
+- The template begins with a section which includes several HTML-styled variables (`<!---variable--->`). These are used by our `ropensci-review-bot`, and must be left in place, with values filled between the indicated start and end points, like this:
+```{bash, eval = F}
+<!---variable--->insert value here<!---end-variable>
+```
 -   Communication between authors, reviewers and editors will first and foremost take place on GitHub so that the review thread can serve as a full record of the review. You may choose to contact the editor by email or Slack if private consultation is needed (e.g., asking how to respond to a reviewer question). Do not contact reviewers off-thread without asking them in the GitHub thread whether they agree to it.
 - *When submitting a package please make sure your GitHub notification settings make it unlikely you will miss a comment.*
+
+## The Review Process
+
 -   An [editor](#editors) will review your submission within 5 business days and respond with next steps. The editor may assign the package to reviewers, request that the package be updated to meet minimal criteria before review, or reject the package due to lack of fit or overlap.
 -   If your package meets minimal criteria, the editor will assign  1-3 reviewers. They will be asked to provide reviews as comments on your issue within 3 weeks.
 -   We ask that you respond to reviewers' comments within 2 weeks of the last-submitted review, but you may make updates to your package or respond at any time. Your response should include a link to the updated [NEWS.md](#news) of your package. Here is [an author response example](https://github.com/ropensci/software-review/issues/160#issuecomment-355043656).  We encourage ongoing conversations between authors and reviewers. See the [reviewing guide](#reviewerguide) for more details.