Merge pull request #38 from getwilds/children

playing with child qmd files as rules
getwilds · Sep 16, 2024 · 53a5d6c · 53a5d6c
2 parents 37087fc + 7822b58
commit 53a5d6c
Show file tree

Hide file tree

Showing 12 changed files with 115 additions and 15 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -5,7 +5,8 @@ Authors@R: c(
   person("Scott", "Chamberlain", , "[email protected]", c("aut", "cre"))
   )
 Imports:
-    rmarkdown
+    rmarkdown,
+    htmltools
 Remotes: r-lib/testthat
 URL: https://github.com/getwilds/guide
 BugReports: https://github.com/getwilds/guide/issues

diff --git a/_variables.yml b/_variables.yml
@@ -0,0 +1,47 @@
+version: 1.2
+
+rule-badge: >
+  <span class="badge text-bg-primary">
+    <iconify-icon inline icon="carbon:rule-draft">
+  </span>
+
+rule-eg: Example rule!
+
+rules:
+  merge-main-release: >
+    Every merge from `dev` into `main` should constitute a release, which
+    should generate a tagged version of the software and an increment to the
+    version number
+  release-tags: Code releases that correspond to specific git tags.
+  codeowners: >
+    At least two but no more than three designated project leads (specified in
+    the [CODEOWNERS file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)).
+  main-branch: >
+    Every project should have a `main` branch which contains the most stable
+    version of the software, or the version of the software that corresponds
+    to the most recent release of the software.
+  main-branch-protections: >
+    `main` branch protections such that `main` can only be updated by a pull
+    request from `dev` or a branch that begins with `hotfix-`, and a review
+    from at least one project lead.
+  mention-our-employer: >
+    In all repositories in WILDS we will include mention of our employer.
+  status-badge: All repositories must have a project status badge.
+  automated-tests: >
+    All [**Stable**](#statuses) projects need automated software testing set
+    up via GitHub Actions with a status badge in the README.md
+  readme: All repositories must have a README.md file.
+  docs-website: >
+    a standalone website that contains more detailed information about the
+    software.
+  readme-detailed: >
+    mature, fully-featured READMEs with badges for automated testing outcomes
+    and software repository availability; detailed information about who the
+    software is intended for, how it’s intended to be used, with fully-worked
+    examples of how to install and use the software.
+  readme-egs: a README that contains examples of how to use the software.
+  readme-basic: >
+    a README that describes what the software does and how to install it. At
+    the Experimental level and above, all functions should have accompanying
+    docstrings (in the case of Python), roxygen2 comments (in the case of R),
+    or equivalent function-level documentation.
diff --git a/conventions.qmd b/conventions.qmd
@@ -2,7 +2,9 @@
 
 ## Mention our employer
 
-In all repositories in WILDS we will include mention of our employer. The following are examples for R and Python:
+{{< var rule-badge >}} {{< var rules.mention-our-employer >}}
+
+The following are examples for R and Python:
 
 - R:
   - With the `usethis` package you can add an entry of type `person` to the DESCRIPTION file of your package
@@ -40,7 +42,9 @@ gh label clone getwilds/source-repo-name \
 
 ### Badges
 
-WILDS projects will use badges to indicate their status. Badges are a widely used standard in source code repositories, and help quickly indicate to a potential user something typically important about the repository.
+{{< var rule-badge >}} {{< var rules.status-badge >}}
+
+Badges are a widely used standard in source code repositories, and help quickly indicate to a potential user something typically important about the repository.
 
 WILDS badges are maintained in a GitHub repository at <https://github.com/getwilds/badges>. There's a website for these badges and an easy click to copy interface at <https://getwilds.org/badges/>.
 

diff --git a/index.qmd b/index.qmd
@@ -21,6 +21,16 @@ Inspiration for this guide is taken in part from:
 
 This book is licensed to you under [Creative Commons CC0 1.0 Universal (CC0 1.0)][cc0], i.e. public domain.
 
+## Rules
+
+Throughout this book we highlight rules that we strive to enforce for projects where deemed necessary. These rules are made more clear and easy to find by using a badge with an icon like:
+
+{{< var rule-badge >}} {{< var rule-eg >}}
+
+Why do certain things constitute a rule while others do not? We offer the following guard rails in lieu of a clear answer:
+
+- rules are likely to be concrete enough to easily allow human or ideally machine checks
+- rules are likley to be the issues we feel are most important
 
 [DaSL]: https://hutchdatascience.org/
 [R]: https://www.r-project.org/

diff --git a/maintenance.qmd b/maintenance.qmd
@@ -35,7 +35,7 @@ Similarly, there is currently no universal standard for incorporating licenses w
 
 ### Docker {#sec-license-docker}
 
-License type can be specified within the corresponding Dockerfile of each container using the "license" label: 
+License type can be specified within the corresponding Dockerfile of each container using the "license" label:
 ```
 LABEL org.opencontainers.image.licenses=MIT
 ```
@@ -97,16 +97,23 @@ We try to follow the principles set out in [Git Flow](https://nvie.com/posts/a-s
   - We use the `main` branch instead of the `master` branch, and we use the `dev` branch instead of the `develop` branch.
   - We don’t use release branches, we create release tags from the `main` branch. Therefore we shouldn’t use the `release-` prefix at all.
 
-Every project should have a `main` branch which contains the most stable version of the software, or the version of the software that corresponds to the most recent release of the software.
+{{< var rule-badge >}} {{< var rules.main-branch >}}
+
+<!-- {{< include rules/main-branch.qmd >}} -->
 
 [**Prototype**](#statuses) status projects must have all of the above and the following:
 
-  - At least two but no more than three designated project leads (specified in the [CODEOWNERS file][codeowners]).
-  - `main` branch protections such that `main` can only be updated by a pull request from `dev` or a branch that begins with `hotfix-`, and a review from at least one project lead.
+- {{< var rule-badge >}} {{< var rules.codeowners >}}
+- {{< var rule-badge >}} {{< var rules.main-branch-protections >}}
+
+<!-- {{< include rules/codeowners.qmd >}}
+{{< include rules/main-branch-protections.qmd >}} -->
 
 [**Stable**](#statuses) status projects must have all of the above and the following:
 
-  - Code releases that correspond to specific git tags.
+- {{< var rule-badge >}} {{< var rules.release-tags >}}
+
+<!-- {{< include rules/releases-tags.qmd >}} -->
 
 ## Package releases {#sec-releases}
 
@@ -115,7 +122,7 @@ In general follow the [Releasing to CRAN chapter](https://r-pkgs.org/release.htm
 There are a few aspects of releases we are opinionated about and would like all WILDS R and Python packages to follow:
 
 - Follow our versioning guidelines above (@sec-versioning).
-- Every merge from `dev` into `main` should constitute a release, which should generate a tagged version of the software and an increment to the version number.
+- {{< var rule-badge >}} {{< var rules.merge-main-release >}}
 - Every time the version number is incremented, the `NEWS.md` file should be updated describing what changes to the software have been made in the new version.
 - If a software package is distributed on an archive like CRAN or PyPI, wait to update the main branch until that software has been accepted by the archive.
 - How we create tagged releases on GitHub:

diff --git a/packagedocs.qmd b/packagedocs.qmd
@@ -36,17 +36,21 @@ For any of the options above, they can be hosted in many places, including [GitH
 ## Guidelines
 
 - README:
-  - All repositories must have a README.md file.
-  - All repositories must have a project status badge (see below for badge specific guidelines).
+  - {{< var rule-badge >}} {{< var rules.readme >}}
+  - {{< var rule-badge >}} {{< var rules.status-badge >}} (see below for badge specific guidelines).
   - This is most likely the first place potential users will interact with your package. Make sure the README clearly states what the package does, and how to get started.
 - Examples: All user facing functions should have examples. Make sure to be careful about how examples are run if there's any sensitive data or connections to remote services.
 - Vignettes: From the [R Packages book](https://r-pkgs.org/vignettes.html): "A vignette is a long-form guide to your package. Function documentation is great if you know the name of the function you need, but it’s useless otherwise. In contrast, a vignette can be framed around a target problem that your package is designed to solve. The vignette format is perfect for showing a workflow that solves that particular problem, start to finish. Vignettes afford you different opportunities than help topics: you have much more control over the integration of code and prose and it’s a better setting for showing how multiple functions work together."
 
 Badge specific guidelines
 
-- [**Experimental**](#statuses) status projects should have a README that describes what the software does and how to install it. At the Experimental level and above, all functions should have accompanying docstrings (in the case of Python), roxygen2 comments (in the case of R), or equivalent function-level documentation. See Google’s style guide on [Python docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) and the R Packages chapter on [function documentation](https://r-pkgs.org/man.html).
-- [**Prototype**](#statuses) status projects should have all of the above and a README that contains examples of how to use the software.
-- [**Stable**](#statuses) status projects should have all the above and mature, fully-featured READMEs with badges for automated testing outcomes and software repository availability. They should also feature detailed information about who the software is intended for, how it’s intended to be used, with fully-worked examples of how to install and use the software. Stable status projects should also have a standalone website that contains more detailed information about the software.
+- [**Experimental**](#statuses) status projects should have:
+  - {{< var rule-badge >}} {{< var rules.readme-basic >}} See Google’s style guide on [Python docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) and the R Packages chapter on [function documentation](https://r-pkgs.org/man.html).
+- [**Prototype**](#statuses) status projects should have all of the above and:
+  - {{< var rule-badge >}} {{< var rules.readme-egs >}}
+- [**Stable**](#statuses) status projects should have all the above and:
+  - {{< var rule-badge >}} {{< var rules.readme-detailed >}}
+  - {{< var rule-badge >}} {{< var rules.docs-website >}}
 
 
 [pkgdown]: https://pkgdown.r-lib.org/

diff --git a/rules/codeowners.qmd b/rules/codeowners.qmd
@@ -0,0 +1,6 @@
+::: {.callout-note icon=false}
+
+## {{< iconify carbon rule-draft >}} Rule
+
+At least two but no more than three designated project leads (specified in the [CODEOWNERS file][codeowners]).
+:::
diff --git a/rules/main-branch-protections.qmd b/rules/main-branch-protections.qmd
@@ -0,0 +1,6 @@
+::: {.callout-note icon=false}
+
+## {{< iconify carbon rule-draft >}} Rule
+
+`main` branch protections such that `main` can only be updated by a pull request from `dev` or a branch that begins with `hotfix-`, and a review from at least one project lead.
+:::
diff --git a/rules/main-branch.qmd b/rules/main-branch.qmd
@@ -0,0 +1,6 @@
+::: {.callout-note icon=false}
+
+## {{< iconify carbon rule-draft >}} Rule
+
+Every project should have a `main` branch which contains the most stable version of the software, or the version of the software that corresponds to the most recent release of the software.
+:::
diff --git a/rules/merge-main-release.qmd b/rules/merge-main-release.qmd
@@ -0,0 +1,3 @@
+```{=html}
+<p><span class="badge text-bg-primary"><iconify-icon inline icon="carbon:rule-draft"></span> Every merge from `dev` into `main` should constitute a release, which should generate a tagged version of the software and an increment to the version number</p>
+```
diff --git a/rules/releases-tags.qmd b/rules/releases-tags.qmd
@@ -0,0 +1,6 @@
+::: {.callout-note icon=false}
+
+## {{< iconify carbon rule-draft >}} Rule
+
+Code releases that correspond to specific git tags.
+:::
diff --git a/testing.qmd b/testing.qmd
@@ -1,6 +1,6 @@
 # Testing {{< iconify fa6-solid bug >}} {#sec-testing}
 
-- All [**Stable**](#statuses) projects need automated software testing set up via GitHub Actions with a status badge in the README.md
+- {{< var rule-badge >}} {{< var rules.automated-tests >}}
 - Software that interacts with the internet should use the [vcr][] or [webmockr][] package for testing whenever possible and appropriate.
 - When writing a test suite, you should aspire to as much [code coverage](https://en.wikipedia.org/wiki/Code_coverage) as is appropriate, although usually higher code coverage is better. When thinking about code coverage, consider this blog post from Google Engineering [
 Code Coverage Best Practices](https://testing.googleblog.com/2020/08/code-coverage-best-practices.html) and the [advice of the ancient master Testivus](https://www.artima.com/forums/flat.jsp?forum=106&thread=204677).