Generalize the lifecycle statement standard from stat software review?

[maelle]

Cc @mpadge, @jooolia

Should all submissions include a lifecycle statement.

[mpadge]

My opinion: A lifecycle statement provides extremely useful information that is not otherwise conveyed at all, and I would love for it to be considered essential. But ... this really is a very different kind of information that has no direct place in a code repository. We stat-software folk went through very protracted wrangling of lots of different approaches, and ultimately settled on the path-of-least-resistance of requiring such a statement and encouraging but not requiring it to be in the CONTRIBUTING.md file.

Given that, my suggestion would actually be first to improve advice and help for authors on the general form of CONTRIBUTING.md files. Current package guide chapter makes no mention of requiring such a file, yet the contributing guide chapter states:

Having a contributing file as .github/CONTRIBUTING.md or docs/CONTRIBUTING.md is compulsory.

Presence of these files is also checked by pkgcheck, and use of pkgcheck is now recommended at the outset of the "Guide for Authors" chapter.

I think we first need some clarity about what is actually required in general, perhaps in the form of a simple list of all the things which pkgcheck will object to if they're not present. I think a slight re-structure of Chapter 6 (Guide for Authors) might be called for here? Within that, we could then include a brief statement on the requirement of a CONTRIBUTING.md file, for which I also think we should have a more useful reference or two than current link to this gist template, which I suspect might often be counter-productive through being too long and convoluted.

... Finally, once all that has been addressed, then I think, yes, we could also extend that by indicating that we require some kind of lifecycle statement along the lines of the General Stats Standard G1.2.

[mpadge]

TODO

• Revise Dev Guide Chapter 6: Guide for Authors by structuring in sub-sections to improve clarity and flow
• PR to software-review issue templates adding sections on explaining reasons for any failing pkgcheck items on submission.
• Move the entire section on CONTRIBUTING.md files from current location in Chapter 10: Collaboration Guide to Author's Guide in Chapter 6.
• Draft a template CONTRIBUTING.md guide for general use, or maybe even better and simpler, recommend usethis::use_tidy_contributing() and clarify that people are free to modify however they like (under CoC guidelines).
• Extend description of CONTRIBUTING requirements (or at least suggestions) to include a lifecycle statement.

[maelle]

Also related: #334

[mpadge]

Good link - thanks! Now that so much of the previously semi-random bag of requirements is auto-done via pgkcheck, the actual Guide for Authors chapter can actually be streamlined quite a bit, and lots of things shucked off to some kind of "what, how, and why of pkgcheck" appendix or sub-section or something. That links has lots of good thoughts for that.

[noamross]

Commenting now after talk with Mark. After completion of >=2 stats packages, let's put together a proposal of new general standards we're considering migrating to all packages, for consideration by editors.

[maelle]

@mpadge this is related to #391 isn't it? 😸

[mpadge]

Yes, indeed, and can likely be closed because that effectively covers the main concerns here, except the bits about explicit descriptions in a CONTRIBUTING file. @maelle Do you think that's still necessary, or do you think the new working via #391 suffice?

[maelle]

except the bits about explicit descriptions in a CONTRIBUTING file

Yes that could still be useful?

[jooolia]

Sorry just having a look at this now, do we have good examples of lifecycle statements? I have some ideas in my head, but I am wondering if we do see these statements in the wild? :)