From 0132a70b493877bc903f48cf591d8921bdcd282a Mon Sep 17 00:00:00 2001 From: Scott Chamberlain Date: Mon, 26 Aug 2024 15:42:24 -0700 Subject: [PATCH 1/2] #37 playing with child qmd files as rules --- maintenance.qmd | 9 +++++---- rules/codeowners.qmd | 6 ++++++ rules/main-branch-protections.qmd | 6 ++++++ rules/main-branch.qmd | 6 ++++++ rules/releases-tags.qmd | 6 ++++++ 5 files changed, 29 insertions(+), 4 deletions(-) create mode 100644 rules/codeowners.qmd create mode 100644 rules/main-branch-protections.qmd create mode 100644 rules/main-branch.qmd create mode 100644 rules/releases-tags.qmd diff --git a/maintenance.qmd b/maintenance.qmd index b925dea..13081cd 100644 --- a/maintenance.qmd +++ b/maintenance.qmd @@ -97,16 +97,17 @@ 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. +{{< 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. +{{< 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. +{{< include rules/releases-tags.qmd >}} ## Package releases {#sec-releases} diff --git a/rules/codeowners.qmd b/rules/codeowners.qmd new file mode 100644 index 0000000..2391889 --- /dev/null +++ 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 new file mode 100644 index 0000000..7ee8658 --- /dev/null +++ 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. +::: \ No newline at end of file diff --git a/rules/main-branch.qmd b/rules/main-branch.qmd new file mode 100644 index 0000000..50845fe --- /dev/null +++ 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/releases-tags.qmd b/rules/releases-tags.qmd new file mode 100644 index 0000000..ada97a4 --- /dev/null +++ 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. +::: From 7822b58c73539d577a2bddbf4ad43e05400bfd28 Mon Sep 17 00:00:00 2001 From: Scott Chamberlain Date: Thu, 12 Sep 2024 15:03:14 -0700 Subject: [PATCH 2/2] change setup for rules: - instead of callouts use _variables.yml file to define rules - and combination of bootstrap badge + text of rule - provides more flexiblity in where rules can be placed (e..g, in lists) - most rules were in lists so it would have been awkward to have callouts combined with lists --- DESCRIPTION | 3 ++- _variables.yml | 47 ++++++++++++++++++++++++++++++++++++ conventions.qmd | 8 ++++-- index.qmd | 10 ++++++++ maintenance.qmd | 18 +++++++++----- packagedocs.qmd | 14 +++++++---- rules/merge-main-release.qmd | 3 +++ testing.qmd | 2 +- 8 files changed, 90 insertions(+), 15 deletions(-) create mode 100644 _variables.yml create mode 100644 rules/merge-main-release.qmd diff --git a/DESCRIPTION b/DESCRIPTION index ffa1e7c..97e7bf1 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -5,7 +5,8 @@ Authors@R: c( person("Scott", "Chamberlain", , "sachamber@fredhutch.org", 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 new file mode 100644 index 0000000..c9d168b --- /dev/null +++ b/_variables.yml @@ -0,0 +1,47 @@ +version: 1.2 + +rule-badge: > + + + + +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 index 3ed0d9a..488323d 100644 --- 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 . There's a website for these badges and an easy click to copy interface at . diff --git a/index.qmd b/index.qmd index 615dbfe..1fa7b9c 100644 --- 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 index 13081cd..80caf46 100644 --- 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,17 +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. -{{< include rules/main-branch.qmd >}} +{{< var rule-badge >}} {{< var rules.main-branch >}} + + [**Prototype**](#statuses) status projects must have all of the above and the following: -{{< include rules/codeowners.qmd >}} +- {{< var rule-badge >}} {{< var rules.codeowners >}} +- {{< var rule-badge >}} {{< var rules.main-branch-protections >}} -{{< include rules/main-branch-protections.qmd >}} + [**Stable**](#statuses) status projects must have all of the above and the following: -{{< include rules/releases-tags.qmd >}} +- {{< var rule-badge >}} {{< var rules.release-tags >}} + + ## Package releases {#sec-releases} @@ -116,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 index df88064..62de09c 100644 --- 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/merge-main-release.qmd b/rules/merge-main-release.qmd new file mode 100644 index 0000000..235f555 --- /dev/null +++ b/rules/merge-main-release.qmd @@ -0,0 +1,3 @@ +```{=html} +

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

+``` diff --git a/testing.qmd b/testing.qmd index 9d9e233..293f341 100644 --- 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).