From fe1bbf18fecf8a4a3e2c6dbe99b820fd65208034 Mon Sep 17 00:00:00 2001 From: Trevor Keller Date: Tue, 28 Mar 2023 17:13:49 -0400 Subject: [PATCH 1/3] MarkdownLint & spelling; consistent semantic and length-based line wrapping. --- .github/workflows/README.md | 269 +++++++++++++++++++------------- CODE_OF_CONDUCT.md | 1 - CONTRIBUTING.md | 156 ++++++++++-------- LICENSE.md | 20 +-- README.md | 7 +- episodes/introduction.md | 26 +-- index.md | 5 +- instructors/instructor-notes.md | 2 +- learners/reference.md | 3 +- links.md | 1 - profiles/learner-profiles.md | 2 +- site/README.md | 4 +- 12 files changed, 284 insertions(+), 212 deletions(-) diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 101967e4..71ab945f 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -2,7 +2,7 @@ This directory contains workflows to be used for Lessons using the {sandpaper} lesson infrastructure. Two of these workflows require R (`sandpaper-main.yaml` -and `pr-recieve.yaml`) and the rest are bots to handle pull request management. +and `pr-receive.yaml`) and the rest are bots to handle pull request management. These workflows will likely change as {sandpaper} evolves, so it is important to keep them up-to-date. To do this in your lesson you can do the following in your @@ -10,7 +10,7 @@ R console: ```r # Install/Update sandpaper -options(repos = c(carpentries = "https://carpentries.r-universe.dev/", +options(repos = c(carpentries = "https://carpentries.r-universe.dev/", CRAN = "https://cloud.r-project.org")) install.packages("sandpaper") @@ -29,170 +29,217 @@ What follows are the descriptions of the workflow files: ### 01 Build and Deploy (sandpaper-main.yaml) -This is the main driver that will only act on the main branch of the repository. +This is the main driver that will only act on the main branch of +the repository. This workflow does the following: - 1. checks out the lesson - 2. provisions the following resources +1. checks out the lesson +2. provisions the following resources - R - pandoc - lesson infrastructure (stored in a cache) - lesson dependencies if needed (stored in a cache) - 3. builds the lesson via `sandpaper:::ci_deploy()` +3. builds the lesson via `sandpaper:::ci_deploy()` #### Caching -This workflow has two caches; one cache is for the lesson infrastructure and -the other is for the the lesson dependencies if the lesson contains rendered -content. These caches are invalidated by new versions of the infrastructure and -the `renv.lock` file, respectively. If there is a problem with the cache, -manual invaliation is necessary. You will need maintain access to the repository -and you can either go to the actions tab and [click on the caches button to find -and invalidate the failing cache](https://github.blog/changelog/2022-10-20-manage-caches-in-your-actions-workflows-from-web-interface/) -or by setting the `CACHE_VERSION` secret to the current date (which will -invalidate all of the caches). +This workflow has two caches; one cache is for the lesson +infrastructure and the other is for the the lesson dependencies +if the lesson contains rendered content. +These caches are invalidated by new versions of the +infrastructure and the `renv.lock` file, respectively. +If there is a problem with the cache, manual invalidation is +necessary. +You will need maintain access to the repository and you can +either go to the actions tab and [click on the caches button to +find and invalidate the failing +cache](https://github.blog/changelog/2022-10-20-manage-caches-in-your-actions-workflows-from-web-interface/) +or by setting the `CACHE_VERSION` secret to the current date +(which will invalidate all of the caches). ## Updates ### Setup Information -These workflows run on a schedule and at the maintainer's request. Because they -create pull requests that update workflows/require the downstream actions to run, -they need a special repository/organization secret token called -`SANDPAPER_WORKFLOW` and it must have the `public_repo` and `workflow` scope. - -This can be an individual user token, OR it can be a trusted bot account. If you -have a repository in one of the official Carpentries accounts, then you do not -need to worry about this token being present because the Carpentries Core Team -will take care of supplying this token. - -If you want to use your personal account: you can go to +These workflows run on a schedule and at the maintainer's +request. +Because they create pull requests that update workflows/require +the downstream actions to run, they need a special +repository/organization secret token called `SANDPAPER_WORKFLOW` +and it must have the `public_repo` and `workflow` scope. + +This can be an individual user token, OR it can be a trusted bot +account. +If you have a repository in one of the official Carpentries +accounts, +then you do not need to worry about this token being present +because the Carpentries Core Team will take care of supplying +this token. + +If you want to use your personal account: +you can go to -to create a token. Once you have created your token, you should copy it to your -clipboard and then go to your repository's settings > secrets > actions and -create or edit the `SANDPAPER_WORKFLOW` secret, pasting in the generated token. +to create a token. +Once you have created your token, you should copy it to your +clipboard and then go to your repository's +settings > secrets > actions +and create or edit the `SANDPAPER_WORKFLOW` secret, +pasting in the generated token. -If you do not specify your token correctly, the runs will not fail and they will -give you instructions to provide the token for your repository. +If you do not specify your token correctly, +the runs will not fail and they will give you instructions to +provide the token for your repository. ### 02 Maintain: Update Workflow Files (update-workflow.yaml) -The {sandpaper} repository was designed to do as much as possible to separate -the tools from the content. For local builds, this is absolutely true, but -there is a minor issue when it comes to workflow files: they must live inside -the repository. +The {sandpaper} repository was designed to do as much as possible +to separate the tools from the content. +For local builds, this is absolutely true, +but there is a minor issue when it comes to workflow files: +they must live inside the repository. -This workflow ensures that the workflow files are up-to-date. The way it work is -to download the update-workflows.sh script from GitHub and run it. The script -will do the following: +This workflow ensures that the workflow files are up-to-date. +The way it work is to download the update-workflows.sh script +from GitHub and run it. +The script will do the following: -1. check the recorded version of sandpaper against the current version on github +1. check the recorded version of sandpaper against the current + version on GitHub 2. update the files if there is a difference in versions -After the files are updated, if there are any changes, they are pushed to a -branch called `update/workflows` and a pull request is created. Maintainers are -encouraged to review the changes and accept the pull request if the outputs -are okay. +After the files are updated, +if there are any changes, +they are pushed to a branch called `update/workflows` and a pull +request is created. +Maintainers are encouraged to review the changes and accept the +pull request if the outputs are okay. This update is run ~~weekly or~~ on demand. -### 03 Maintain: Update Pacakge Cache (update-cache.yaml) +### 03 Maintain: Update Package Cache (update-cache.yaml) -For lessons that have generated content, we use {renv} to ensure that the output -is stable. This is controlled by a single lockfile which documents the packages -needed for the lesson and the version numbers. This workflow is skipped in -lessons that do not have generated content. +For lessons that have generated content, +we use {renv} to ensure that the output is stable. +This is controlled by a single lockfile which documents the +packages needed for the lesson and the version numbers. +This workflow is skipped in lessons that do not have generated +content. -Because the lessons need to remain current with the package ecosystem, it's a -good idea to make sure these packages can be updated periodically. The -update cache workflow will do this by checking for updates, applying them in a -branch called `updates/packages` and creating a pull request with _only the -lockfile changed_. +Because the lessons need to remain current with the package +ecosystem, +it's a good idea to make sure these packages can be updated +periodically. +The update cache workflow will do this by checking for updates, +applying them in a branch called `updates/packages` and creating +a pull request with _only the lockfile changed_. -From here, the markdown documents will be rebuilt and you can inspect what has -changed based on how the packages have updated. +From here, +the markdown documents will be rebuilt and you can inspect what +has changed based on how the packages have updated. ## Pull Request and Review Management -Because our lessons execute code, pull requests are a secruity risk for any -lesson and thus have security measures associted with them. **Do not merge any -pull requests that do not pass checks and do not have bots commented on them.** +Because our lessons execute code, +pull requests are a security risk for any lesson and thus have +security measures associated with them. +**Do not merge any pull requests that do not pass checks and do +not have bots commented on them.** -This series of workflows all go together and are described in the following -diagram and the below sections: +This series of workflows all go together and are described in the +following diagram and the below sections: ![Graph representation of a pull request](https://carpentries.github.io/sandpaper/articles/img/pr-flow.dot.svg) ### Pre Flight Pull Request Validation (pr-preflight.yaml) -This workflow runs every time a pull request is created and its purpose is to -validate that the pull request is okay to run. This means the following things: +This workflow runs every time a pull request is created and its +purpose is to validate that the pull request is okay to run. +This means the following things: 1. The pull request does not contain modified workflow files -2. If the pull request contains modified workflow files, it does not contain - modified content files (such as a situation where @carpentries-bot will - make an automated pull request) -3. The pull request does not contain an invalid commit hash (e.g. from a fork - that was made before a lesson was transitioned from styles to use the - workbench). - -Once the checks are finished, a comment is issued to the pull request, which -will allow maintainers to determine if it is safe to run the -"Receive Pull Request" workflow from new contributors. - -### Recieve Pull Request (pr-recieve.yaml) - -**Note of caution:** This workflow runs arbitrary code by anyone who creates a -pull request. GitHub has safeguarded the token used in this workflow to have no -priviledges in the repository, but we have taken precautions to protect against -spoofing. - -This workflow is triggered with every push to a pull request. If this workflow -is already running and a new push is sent to the pull request, the workflow -running from the previous push will be cancelled and a new workflow run will be -started. - -The first step of this workflow is to check if it is valid (e.g. that no -workflow files have been modified). If there are workflow files that have been -modified, a comment is made that indicates that the workflow is not run. If -both a workflow file and lesson content is modified, an error will occurr. - -The second step (if valid) is to build the generated content from the pull -request. This builds the content and uploads three artifacts: +2. If the pull request contains modified workflow files, + it does not contain modified content files + (such as a situation where @carpentries-bot will make an + automated pull request) +3. The pull request does not contain an invalid commit hash + (e.g. from a fork that was made before a lesson was + transitioned from styles to use the workbench). + +Once the checks are finished, +a comment is issued to the pull request, +which will allow maintainers to determine if it is safe to run +the "Receive Pull Request" workflow from new contributors. + +### Receive Pull Request (pr-receive.yaml) + +**Note of caution:** +This workflow runs arbitrary code by anyone who creates a pull +request. +GitHub has safeguarded the token used in this workflow to have no +privileges in the repository, +but we have taken precautions to protect against spoofing. + +This workflow is triggered with every push to a pull request. +If this workflow is already running and a new push is sent to the +pull request, +the workflow running from the previous push will be canceled and +a new workflow run will be started. + +The first step of this workflow is to check if it is valid +(e.g. that no workflow files have been modified). +If there are workflow files that have been modified, +a comment is made that indicates that the workflow is not run. +If both a workflow file and lesson content is modified, +an error +will occur. + +The second step (if valid) is to build the generated content from +the pull request. +This builds the content and uploads three artifacts: 1. The pull request number (pr) 2. A summary of changes after the rendering process (diff) 3. The rendered files (build) -Because this workflow builds generated content, it follows the same general -process as the `sandpaper-main` workflow with the same caching mechanisms. +Because this workflow builds generated content, +it follows the same general process as the `sandpaper-main` +workflow with the same caching mechanisms. The artifacts produced are used by the next workflow. ### Comment on Pull Request (pr-comment.yaml) -This workflow is triggered if the `pr-recieve.yaml` workflow is successful. +This workflow is triggered if the `pr-receive.yaml` workflow is +successful. The steps in this workflow are: -1. Test if the workflow is valid and comment the validity of the workflow to the - pull request. -2. If it is valid: create an orphan branch with two commits: the current state - of the repository and the proposed changes. -3. If it is valid: update the pull request comment with the summary of changes - -Importantly: if the pull request is invalid, the branch is not created so any -malicious code is not published. - -From here, the maintainer can request changes from the author and eventually -either merge or reject the PR. When this happens, if the PR was valid, the -preview branch needs to be deleted. +1. Test if the workflow is valid and comment the validity of the + workflow to the pull request. +2. If it is valid, + create an orphan branch with two commits: + the current state of the repository and the proposed changes. +3. If it is valid, + update the pull request comment with the summary of changes. + +Importantly, +if the pull request is invalid, +the branch is not created so any malicious code is not published. + +From here, +the maintainer can request changes from the author and eventually +either merge or reject the PR. +When this happens, +if the PR was valid, +the preview branch needs to be deleted. ### Send Close PR Signal (pr-close-signal.yaml) -Triggered any time a pull request is closed. This emits an artifact that is the -pull request number for the next action +Triggered any time a pull request is closed. +This emits an artifact that is the pull request number for the +next action ### Remove Pull Request Branch (pr-post-remove-branch.yaml) -Tiggered by `pr-close-signal.yaml`. This removes the temporary branch associated with -the pull request (if it was created). +Triggered by `pr-close-signal.yaml`. +This removes the temporary branch associated with the pull +request (if it was created). diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index f19b8049..95ae91f5 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -8,6 +8,5 @@ we pledge to follow the [The Carpentries Code of Conduct][coc]. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by following our [reporting guidelines][coc-reporting]. - [coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html [coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e29bff5..3bd74f92 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,7 @@ # Contributing -[Software Carpentry][swc-site] and [Data Carpentry][dc-site] are open source projects, +[Software Carpentry][swc-site] and +[Data Carpentry][dc-site] are open source projects, and we welcome contributions of all kinds: new lessons, fixes to existing material, @@ -10,12 +11,15 @@ and reviews of proposed changes are all welcome. ## Contributor Agreement By contributing, -you agree that we may redistribute your work under [our license](LICENSE.md). +you agree that we may redistribute your work under +[our license](LICENSE.md). In exchange, -we will address your issues and/or assess your change proposal as promptly as we can, +we will address your issues and/or assess your change +proposal as promptly as we can, and help you become a member of our community. -Everyone involved in [Software Carpentry][swc-site] and [Data Carpentry][dc-site] -agrees to abide by our [code of conduct](CONDUCT.md). +Everyone involved in [Software Carpentry][swc-site] +and [Data Carpentry][dc-site] agrees to abide by our +[code of conduct](CONDUCT.md). ## How to Contribute @@ -23,68 +27,83 @@ The easiest way to get started is to file an issue to tell us about a spelling mistake, some awkward wording, or a factual error. -This is a good way to introduce yourself -and to meet some of our community members. - -1. If you do not have a [GitHub][github] account, - you can [send us comments by email][contact]. - However, - we will be able to respond more quickly if you use one of the other methods described below. - -2. If you have a [GitHub][github] account, - or are willing to [create one][github-join], - but do not know how to use Git, - you can report problems or suggest improvements by [creating an issue][issues]. - This allows us to assign the item to someone - and to respond to it in a threaded discussion. - -3. If you are comfortable with Git, - and would like to add or change material, - you can submit a pull request (PR). - Instructions for doing this are [included below](#using-github). - -Note: if you want to build the website locally, please refer to [The Workbench documentation][template-doc]. +This is a good way to introduce yourself and to meet +some of our community members. + +1. If you do not have a [GitHub][github] account, + you can [send us comments by email][contact]. + However, + we will be able to respond more quickly if you + use one of the other methods described below. + +2. If you have a [GitHub][github] account, + or are willing to [create one][github-join], + but do not know how to use Git, + you can report problems or suggest improvements + by [creating an issue][issues]. + This allows us to assign the item to someone + and to respond to it in a threaded discussion. + +3. If you are comfortable with Git, + and would like to add or change material, + you can submit a pull request (PR). + Instructions for doing this are + [included below](#using-github). + +Note: +if you want to build the website locally, +please refer to [The Workbench documentation][template-doc]. ## Where to Contribute -1. If you wish to change this lesson, - add issues and PR here. -2. If you wish to change the template used for workshop websites, - please refer to [The Workbench documentation][template-doc]. - +1. If you wish to change this lesson, + add issues and PR here. +2. If you wish to change the template used for workshop + websites, please refer to + [The Workbench documentation][template-doc]. ## What to Contribute There are many ways to contribute, from writing new exercises and improving existing ones -to updating or filling in the documentation -and submitting [bug reports][issues] -about things that don't work, aren't clear, or are missing. -If you are looking for ideas, -please see [the list of issues for this repository][issues], +to updating or filling in the documentation and +submitting [bug reports][issues] about things that +don't work, aren't clear, or are missing. +If you are looking for ideas, please see the +[list of issues for this repository][issues], or the issues for [Data Carpentry][dc-issues] and [Software Carpentry][swc-issues] projects. -Comments on issues and reviews of pull requests are just as welcome: -we are smarter together than we are on our own. -**Reviews from novices and newcomers are particularly valuable**: -it's easy for people who have been using these lessons for a while -to forget how impenetrable some of this material can be, +Comments on issues and reviews of pull requests are +just as welcome: we are smarter together than we are on +our own. + +**Reviews from novices and newcomers are particularly +valuable**: +it's easy for people who have been using these lessons +for a while to forget how impenetrable some of this +material can be, so fresh eyes are always welcome. ## What *Not* to Contribute -Our lessons already contain more material than we can cover in a typical workshop, -so we are usually *not* looking for more concepts or tools to add to them. +Our lessons already contain more material than we can +cover in a typical workshop, +so we are usually *not* looking for more concepts or +tools to add to them. As a rule, if you want to introduce a new idea, you must (a) estimate how long it will take to teach -and (b) explain what you would take out to make room for it. -The first encourages contributors to be honest about requirements; +and (b) explain what you would take out to make room +for it. +The first encourages contributors to be honest about +requirements; the second, to think hard about priorities. -We are also not looking for exercises or other material that only run on one platform. -Our workshops typically contain a mixture of Windows, macOS, and Linux users; +We are also not looking for exercises or other material +that only run on one platform. +Our workshops typically contain a mixture of Windows, +macOS, and Linux users; in order to be usable, our lessons must run equally well on all three. @@ -93,32 +112,40 @@ our lessons must run equally well on all three. If you choose to contribute via GitHub, you may want to look at [How to Contribute to an Open Source Project on GitHub][how-contribute]. -In brief, we use [GitHub flow][github-flow] to manage changes: - 1. Create a new branch in your desktop copy of this repository for each significant change. - 2. Commit the change in that branch. - 3. Push that branch to your fork of this repository on GitHub. - 4. Submit a pull request from that branch to the [master repository][repo]. - 5. If you receive feedback, - make changes on your desktop and push to your branch on GitHub: - the pull request will update automatically. - -NB: The published copy of the lesson is usually in the `main` branch. - -Each lesson has two maintainers who review issues and pull requests -or encourage others to do so. +In brief, we use [GitHub flow][github-flow] to manage +changes: + +1. Create a new branch in your desktop copy of this + repository for each significant change. +2. Commit the change in that branch. +3. Push that branch to your fork of this repository on + GitHub. +4. Submit a pull request from that branch to the + [master repository][repo]. +5. If you receive feedback, + make changes on your desktop and push to your branch + on GitHub: + the pull request will update automatically. + +NB: The published copy of the lesson is usually in the +`main` branch. + +Each lesson has two maintainers who review issues and +pull requests or encourage others to do so. The maintainers are community volunteers, -and have final say over what gets merged into the lesson. +and have final say over what gets merged into the +lesson. ## Other Resources -General discussion of [Software Carpentry][swc-site] and [Data Carpentry][dc-site] -happens on the [discussion mailing list][discuss-list], +General discussion of [Software Carpentry][swc-site] +and [Data Carpentry][dc-site] happens on the +[discussion mailing list][discuss-list], which everyone is welcome to join. You can also [reach us by email][contact]. [contact]: mailto:admin@software-carpentry.org [dc-issues]: https://github.com/issues?q=user%3Adatacarpentry -[dc-lessons]: http://datacarpentry.org/lessons/ [dc-site]: http://datacarpentry.org/ [discuss-list]: http://lists.software-carpentry.org/listinfo/discuss [github]: http://github.com @@ -128,6 +155,5 @@ You can also [reach us by email][contact]. [issues]: https://github.com/swcarpentry/shell-novice/issues/ [repo]: https://github.com/swcarpentry/shell-novice/ [swc-issues]: https://github.com/issues?q=user%3Aswcarpentry -[swc-lessons]: http://software-carpentry.org/lessons/ [swc-site]: http://software-carpentry.org/ [template-doc]: https://carpentries.github.io/workbench/ diff --git a/LICENSE.md b/LICENSE.md index b6f5f2ce..609ddafa 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -4,15 +4,16 @@ title: "Licenses" ## Instructional Material -All Software Carpentry, Data Carpentry, and Library Carpentry instructional material is -made available under the [Creative Commons Attribution -license][cc-by-human]. The following is a human-readable summary of -(and not a substitute for) the [full legal text of the CC BY 4.0 -license][cc-by-legal]. +All Software Carpentry, Data Carpentry, and Library Carpentry +instructional material is made available under the +[Creative Commons Attribution license][cc-by-human]. +The following is a human-readable summary of (and not a substitute +for) the [full legal text of the CC BY 4.0 license][cc-by-legal]. You are free: -* to **Share**---copy and redistribute the material in any medium or format +* to **Share**---copy and redistribute the material in any medium or + format * to **Adapt**---remix, transform, and build upon the material for any purpose, even commercially. @@ -25,7 +26,7 @@ Under the following terms: * **Attribution**---You must give appropriate credit (mentioning that your work is derived from work that is Copyright © Software Carpentry and, where practical, linking to - http://software-carpentry.org/), provide a [link to the + ), provide a [link to the license][cc-by-human], and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use. @@ -47,9 +48,8 @@ Notices: ## Software Except where otherwise noted, the example programs and other software -provided by Software Carpentry and Data Carpentry are made available under the -[OSI][osi]-approved -[MIT license][mit-license]. +provided by Software Carpentry and Data Carpentry are made available +under the [OSI][osi]-approved [MIT license][mit-license]. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/README.md b/README.md index c1666924..c57cda4c 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,12 @@ # The Carpentries Workbench Template Markdown Lesson -This lesson is a template lesson that uses [The Carpentries Workbench][workbench]. +This lesson is a template lesson that uses +[The Carpentries Workbench][workbench]. -To get started using this template, make sure you're logged into Github and visit https://github.com/carpentries/workbench-template-md/generate +To get started using this template, +visit and follow the instructions. +Make sure you're logged into Github! If you have any questions, contact [@zkamvar](https://github.com/zkamvar) diff --git a/episodes/introduction.md b/episodes/introduction.md index 62a325a1..2d19c09e 100644 --- a/episodes/introduction.md +++ b/episodes/introduction.md @@ -4,7 +4,7 @@ teaching: 10 exercises: 2 --- -:::::::::::::::::::::::::::::::::::::: questions +:::::::::::::::::::::::::::::::::::::: questions - How do you write a lesson using Markdown and `{sandpaper}`? @@ -19,11 +19,12 @@ exercises: 2 ## Introduction -This is a lesson created via The Carpentries Workbench. It is written in -[Pandoc-flavored Markdown](https://pandoc.org/MANUAL.txt) for static files and -[R Markdown][r-markdown] for dynamic files that can render code into output. -Please refer to the [Introduction to The Carpentries -Workbench](https://carpentries.github.io/sandpaper-docs/) for full documentation. +This is a lesson created via The Carpentries Workbench. +It is written in [Pandoc-flavored Markdown](https://pandoc.org/MANUAL.txt) +for static files and [R Markdown][r-markdown] for dynamic files that can +render code into output. +Please refer to the [Introduction to The Carpentries Workbench]( +https://carpentries.github.io/sandpaper-docs/) for full documentation. What you need to know is that there are three sections required for a valid Carpentries lesson: @@ -40,9 +41,9 @@ Carpentries lesson: Inline instructor notes can help inform instructors of timing challenges associated with the lessons. They appear in the "Instructor View" -:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: +::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: -::::::::::::::::::::::::::::::::::::: challenge +::::::::::::::::::::::::::::::::::::: challenge ## Challenge 1: Can you do it? @@ -52,20 +53,19 @@ What is the output of this command? paste("This", "new", "lesson", "looks", "good") ``` -:::::::::::::::::::::::: solution +:::::::::::::::::::::::: solution ## Output - + ```output [1] "This new lesson looks good" ``` ::::::::::::::::::::::::::::::::: - ## Challenge 2: how do you nest solutions within challenge blocks? -:::::::::::::::::::::::: solution +:::::::::::::::::::::::: solution You can add a line with at least three colons and a `solution` tag. @@ -90,7 +90,7 @@ dynamic reports with {knitr}, so we now use mathjax to describe this: Cool, right? -::::::::::::::::::::::::::::::::::::: keypoints +::::::::::::::::::::::::::::::::::::: keypoints - Use `.md` files for episodes when you want static content - Use `.Rmd` files for episodes when you need to generate output diff --git a/index.md b/index.md index af662764..f6e31c6a 100644 --- a/index.md +++ b/index.md @@ -2,8 +2,7 @@ site: sandpaper::sandpaper_site --- -This is a new lesson built with [The Carpentries Workbench][workbench]. - +This is a new lesson built with +[The Carpentries Workbench][workbench]. [workbench]: https://carpentries.github.io/sandpaper-docs - diff --git a/instructors/instructor-notes.md b/instructors/instructor-notes.md index d9a67aaa..e2eec5f5 100644 --- a/instructors/instructor-notes.md +++ b/instructors/instructor-notes.md @@ -2,4 +2,4 @@ title: 'Instructor Notes' --- -This is a placeholder file. Please add content here. +This is a placeholder file. Please add content here. diff --git a/learners/reference.md b/learners/reference.md index ba26b9fe..3adc9c48 100644 --- a/learners/reference.md +++ b/learners/reference.md @@ -4,5 +4,4 @@ title: 'Reference' ## Glossary -This is a placeholder file. Please add content here. - +This is a placeholder file. Please add content here. diff --git a/links.md b/links.md index 4c5cd2f9..05a14a86 100644 --- a/links.md +++ b/links.md @@ -7,4 +7,3 @@ any links that you are not going to use. [r-markdown]: https://rmarkdown.rstudio.com/ [rstudio]: https://www.rstudio.com/ [carpentries-workbench]: https://carpentries.github.io/sandpaper-docs/ - diff --git a/profiles/learner-profiles.md b/profiles/learner-profiles.md index 434e335a..75b2c5ca 100644 --- a/profiles/learner-profiles.md +++ b/profiles/learner-profiles.md @@ -2,4 +2,4 @@ title: FIXME --- -This is a placeholder file. Please add content here. +This is a placeholder file. Please add content here. diff --git a/site/README.md b/site/README.md index 42997e3d..c32ce4de 100644 --- a/site/README.md +++ b/site/README.md @@ -1,2 +1,2 @@ -This directory contains rendered lesson materials. Please do not edit files -here. +This directory contains rendered lesson materials. +Please do not edit files here. From 96126ace48933f825c08a38d550f708d153e7382 Mon Sep 17 00:00:00 2001 From: Trevor Keller Date: Tue, 28 Mar 2023 17:52:40 -0400 Subject: [PATCH 2/3] YamlLint; use folded style where applicable --- .github/workflows/pr-close-signal.yaml | 2 +- .github/workflows/pr-comment.yaml | 8 +-- .github/workflows/pr-post-remove-branch.yaml | 1 + .github/workflows/pr-preflight.yaml | 1 + .github/workflows/pr-receive.yaml | 4 +- .github/workflows/sandpaper-main.yaml | 1 + .github/workflows/update-cache.yaml | 27 ++++++++--- .github/workflows/update-workflows.yaml | 24 ++++++--- .gitignore | 1 - config.yaml | 51 ++++++++++---------- 10 files changed, 74 insertions(+), 46 deletions(-) diff --git a/.github/workflows/pr-close-signal.yaml b/.github/workflows/pr-close-signal.yaml index 9b129d5d..7c7276c4 100644 --- a/.github/workflows/pr-close-signal.yaml +++ b/.github/workflows/pr-close-signal.yaml @@ -1,3 +1,4 @@ +--- name: "Bot: Send Close Pull Request Signal" on: @@ -20,4 +21,3 @@ jobs: with: name: pr path: ./pr - diff --git a/.github/workflows/pr-comment.yaml b/.github/workflows/pr-comment.yaml index bb2eb03c..f4682f03 100644 --- a/.github/workflows/pr-comment.yaml +++ b/.github/workflows/pr-comment.yaml @@ -1,3 +1,4 @@ +--- name: "Bot: Comment on the Pull Request" # read-write repo token @@ -48,7 +49,7 @@ jobs: id: bad-pr if: ${{ steps.dl.outputs.success != 'true' }} run: | - echo '::error::A pull request number was not recorded. The pull request that triggered this workflow is likely malicious.' + echo '::error:: A pull request number was not recorded. The pull request that triggered this workflow is likely malicious.' exit 1 - name: "Get Invalid Hashes File" id: hash @@ -63,9 +64,11 @@ jobs: with: pr: ${{ steps.get-pr.outputs.NUM }} sha: ${{ github.event.workflow_run.head_sha }} - headroom: 3 # if it's within the last three commits, we can keep going, because it's likely rapid-fire invalid: ${{ fromJSON(steps.hash.outputs.json)[github.repository] }} fail_on_error: true + # keep going if it's within the last three commits, + # because it's likely rapid-fire + headroom: 3 # Create an orphan branch on this repository with two commits # - the current HEAD of the md-outputs branch @@ -182,4 +185,3 @@ jobs: with: pr: ${{ env.NR }} body: ${{ env.body }} - diff --git a/.github/workflows/pr-post-remove-branch.yaml b/.github/workflows/pr-post-remove-branch.yaml index 62c2e98d..51ebf116 100644 --- a/.github/workflows/pr-post-remove-branch.yaml +++ b/.github/workflows/pr-post-remove-branch.yaml @@ -1,3 +1,4 @@ +--- name: "Bot: Remove Temporary PR Branch" on: diff --git a/.github/workflows/pr-preflight.yaml b/.github/workflows/pr-preflight.yaml index d0d7420d..23c6168d 100644 --- a/.github/workflows/pr-preflight.yaml +++ b/.github/workflows/pr-preflight.yaml @@ -1,3 +1,4 @@ +--- name: "Pull Request Preflight Check" on: diff --git a/.github/workflows/pr-receive.yaml b/.github/workflows/pr-receive.yaml index 371ef542..45835ebc 100644 --- a/.github/workflows/pr-receive.yaml +++ b/.github/workflows/pr-receive.yaml @@ -1,3 +1,4 @@ +--- name: "Receive Pull Request" on: @@ -20,8 +21,9 @@ jobs: - name: "Record PR number" id: record if: ${{ always() }} + # 2022-03-02: artifact name fixed to be NR run: | - echo ${{ github.event.number }} > ${{ github.workspace }}/NR # 2022-03-02: artifact name fixed to be NR + echo ${{ github.event.number }} > ${{ github.workspace }}/NR - name: "Upload PR number" id: upload if: ${{ always() }} diff --git a/.github/workflows/sandpaper-main.yaml b/.github/workflows/sandpaper-main.yaml index e17707ac..e8c8fdd6 100644 --- a/.github/workflows/sandpaper-main.yaml +++ b/.github/workflows/sandpaper-main.yaml @@ -1,3 +1,4 @@ +--- name: "01 Build and Deploy Site" on: diff --git a/.github/workflows/update-cache.yaml b/.github/workflows/update-cache.yaml index 676d7424..2908d6ba 100644 --- a/.github/workflows/update-cache.yaml +++ b/.github/workflows/update-cache.yaml @@ -1,10 +1,12 @@ +--- name: "03 Maintain: Update Package Cache" on: workflow_dispatch: inputs: name: - description: 'Who triggered this build (enter github username to tag yourself)?' + description: "Who triggered this build?\ + (enter github username to tag yourself)" required: true default: 'monthly run' schedule: @@ -98,27 +100,38 @@ jobs: token: ${{ secrets.SANDPAPER_WORKFLOW }} delete-branch: true branch: "update/packages" - commit-message: "[actions] update ${{ steps.update.outputs.n }} packages" + commit-message: > + [actions] update ${{ steps.update.outputs.n }} packages title: "Update ${{ steps.update.outputs.n }} packages" - body: | + body: > :robot: This is an automated build - This will update ${{ steps.update.outputs.n }} packages in your lesson with the following versions: + This will update ${{ steps.update.outputs.n }} packages + in your lesson with the following versions: + ``` + ${{ steps.update.outputs.report }} + ``` - :stopwatch: In a few minutes, a comment will appear that will show you how the output has changed based on these updates. + :stopwatch: In a few minutes, a comment will appear that + will show you how the output has changed based on these updates. - If you want to inspect these changes locally, you can use the following code to check out a new branch: + If you want to inspect these changes locally, you can use the + following code to check out a new branch: ```bash + git fetch origin update/packages + git checkout update/packages + ``` - - Auto-generated by [create-pull-request][1] on ${{ steps.update.outputs.date }} + Auto-generated by [create-pull-request][1] + on ${{ steps.update.outputs.date }} [1]: https://github.com/carpentries/create-pull-request/tree/main labels: "type: package cache" diff --git a/.github/workflows/update-workflows.yaml b/.github/workflows/update-workflows.yaml index 288bcd13..d6f2fbc1 100644 --- a/.github/workflows/update-workflows.yaml +++ b/.github/workflows/update-workflows.yaml @@ -1,14 +1,19 @@ +--- name: "02 Maintain: Update Workflow Files" on: workflow_dispatch: inputs: name: - description: 'Who triggered this build (enter github username to tag yourself)?' + description: > + Who triggered this build? + (enter github username to tag yourself) required: true default: 'weekly run' clean: - description: 'Workflow files/file extensions to clean (no wildcards, enter "" for none)' + description: > + Workflow files/file extensions to clean + (no wildcards, enter "" for none) required: false default: '.yaml' schedule: @@ -52,14 +57,19 @@ jobs: token: ${{ secrets.SANDPAPER_WORKFLOW }} delete-branch: true branch: "update/workflows" - commit-message: "[actions] update sandpaper workflow to version ${{ steps.update.outputs.new }}" - title: "Update Workflows to Version ${{ steps.update.outputs.new }}" - body: | + commit-message: > + [actions] update sandpaper workflow to + version ${{ steps.update.outputs.new }} + title: > + Update Workflows to Version ${{ steps.update.outputs.new }} + body: > :robot: This is an automated build - Update Workflows from sandpaper version ${{ steps.update.outputs.old }} -> ${{ steps.update.outputs.new }} + Update Workflows from sandpaper version + ${{ steps.update.outputs.old }} -> ${{ steps.update.outputs.new }} - - Auto-generated by [create-pull-request][1] on ${{ steps.update.outputs.date }} + Auto-generated by [create-pull-request][1] + on ${{ steps.update.outputs.date }} [1]: https://github.com/carpentries/create-pull-request/tree/main labels: "type: template and tools" diff --git a/.gitignore b/.gitignore index bd874548..1bb8a49f 100644 --- a/.gitignore +++ b/.gitignore @@ -48,4 +48,3 @@ docs/ # translation temp files po/*~ - diff --git a/config.yaml b/config.yaml index b3bfd794..513317ab 100644 --- a/config.yaml +++ b/config.yaml @@ -1,8 +1,9 @@ -#------------------------------------------------------------ -# Values for this lesson. -#------------------------------------------------------------ +--- +# ---------------------- +# Values for this lesson +# ---------------------- -# Which carpentry is this (swc, dc, lc, or cp)? +# Which carpentry is this? Choose one of: # swc: Software Carpentry # dc: Data Carpentry # lc: Library Carpentry @@ -11,68 +12,66 @@ carpentry: 'incubator' # Overall title for pages. -title: 'Lesson Title' # FIXME +title: 'Lesson Title' # FIXME # Date the lesson was created (YYYY-MM-DD, this is empty by default) -created: ~ # FIXME +created: ~ # FIXME # Comma-separated list of keywords for the lesson -keywords: 'software, data, lesson, The Carpentries' # FIXME +keywords: 'software, data, lesson, The Carpentries' # FIXME # Life cycle stage of the lesson # possible values: pre-alpha, alpha, beta, stable -life_cycle: 'pre-alpha' # FIXME +life_cycle: 'pre-alpha' # FIXME # License of the lesson license: 'CC-BY 4.0' # Link to the source repository for this lesson -source: 'https://github.com/carpentries/workbench-template-md' # FIXME +source: 'https://github.com/carpentries/workbench-template-md' # FIXME # Default branch of your lesson branch: 'main' # Who to contact if there are any issues -contact: 'team@carpentries.org' # FIXME +contact: 'team@carpentries.org' # FIXME -# Navigation ------------------------------------------------ +# Navigation ----------- # # Use the following menu items to specify the order of # individual pages in each dropdown section. Leave blank to # include all pages in the folder. # -# Example ------------- +# Example -------------- # # episodes: -# - introduction.md -# - first-steps.md +# - introduction.md +# - first-steps.md # # learners: -# - setup.md +# - setup.md # # instructors: -# - instructor-notes.md +# - instructor-notes.md # # profiles: -# - one-learner.md -# - another-learner.md +# - one-learner.md +# - another-learner.md # Order of episodes in your lesson -episodes: -- introduction.md +episodes: + - introduction.md # Information for Learners -learners: +learners: # Information for Instructors -instructors: +instructors: # Learner Profiles -profiles: +profiles: -# Customisation --------------------------------------------- +# Customisation -------- # # This space below is where custom yaml items (e.g. pinning # sandpaper and varnish versions) should live - - From fc313b8f55dfb2e0e28796c5c1d999c40cfe5142 Mon Sep 17 00:00:00 2001 From: Trevor Keller Date: Tue, 28 Mar 2023 18:11:04 -0400 Subject: [PATCH 3/3] Propose an editorconfig --- .editorconfig | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 .editorconfig diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 00000000..23b9f02e --- /dev/null +++ b/.editorconfig @@ -0,0 +1,20 @@ +# Propagate stylistic preferences across editors: +# + +# Look no further: this file governs everything below. +root = true + +# Files ought to end on a new line. +# Lines should not end in blank spaces. +[*] +insert_final_newline = true +trim_trailing_whitespace = true + +# Wrap Markdown at 75 characters +[*.md] +max_line_length = 75 + +# Indent YAML with 2 spaces. +[*.yaml] +indent_style = space +indent_size = 2