generated from carpentries/workbench-template-rmd
-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
61 additions
and
18 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,8 +1,7 @@ | ||
| ## Contributing | ||
|
|
||
| [The Carpentries][cp-site] ([Software Carpentry][swc-site], [Data | ||
| Carpentry][dc-site], and [Library Carpentry][lc-site]) are open source | ||
| projects, and we welcome contributions of all kinds: new lessons, fixes to | ||
| [The Epiverse-TRACE][cp-site] is an open source | ||
| project, and we welcome contributions of all kinds: new documentation, fixes to | ||
| existing material, bug reports, and reviews of proposed changes are all | ||
| welcome. | ||
|
|
||
|
|
@@ -11,7 +10,7 @@ welcome. | |
| By contributing, 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, and help you become a member of our | ||
| community. Everyone involved in [The Carpentries][cp-site] agrees to abide by | ||
| community. Everyone involved in [The Epiverse-TRACE][cp-site] agrees to abide by | ||
| our [code of conduct](CODE_OF_CONDUCT.md). | ||
|
|
||
| ### How to Contribute | ||
|
|
@@ -32,14 +31,14 @@ introduce yourself and to meet some of our community members. | |
| 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). For inspiration about changes that need to | ||
| be made, check out the [list of open issues][issues] across the Carpentries. | ||
| be made, check out the [list of open issues][issues]. | ||
|
|
||
| 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 pull requests here. | ||
| 1. If you wish to change this tutorial, add issues and pull requests here. | ||
| 2. If you wish to change the template used for workshop websites, please refer | ||
| to [The Workbench documentation][template-doc]. | ||
|
|
||
|
|
@@ -50,18 +49,17 @@ 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 do not work, are not clear, or are missing. | ||
| If you are looking for ideas, please see [the list of issues for this | ||
| repository][repo-issues], or the issues for [Data Carpentry][dc-issues], | ||
| [Library Carpentry][lc-issues], and [Software Carpentry][swc-issues] projects. | ||
| repository][repo-issues]. | ||
|
|
||
| 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 | ||
| tutorials 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 | ||
| Our tutorials 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 | ||
|
|
@@ -70,9 +68,54 @@ 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; in order to be usable, our lessons must run equally well on all | ||
| Linux users; in order to be usable, our tutorials must run equally well on all | ||
| three. | ||
|
|
||
| ### Contribution roles | ||
|
|
||
| For a tutorial your role could be of a __Developer__, __Reviewer__, or __Maintainer__. Our goal is to keep an homogeneous package environment among Developers and Reviewers of a “development branch” different to main. This implies that: | ||
|
|
||
| - We will use [`sandpaper::use_package_cache()`](https://carpentries.github.io/sandpaper/reference/package_cache.html#background) in the R project. | ||
| - The Developer will need to register the package version to use in a `renv.lock` file. | ||
| - The Reviewer will need to restore environment defined by Developer, if needs to build the website locally. | ||
|
|
||
|
|
||
| #### Developer: | ||
|
|
||
| If you need to work with the most recent versions: | ||
|
|
||
| - Use [`sandpaper::update_cache()`](https://carpentries.github.io/sandpaper/reference/dependency_management.html). This will: | ||
| + Fetch updates from CRAN or GitHub, | ||
| + Update the `renv.lock` file with package specific versions, and | ||
| + Update the cache. This is located in a folder called `renv/library/` in the same directory of the `renv.lock`, only visible locally. | ||
| - Push the updated `renv.lock` file to the GitHub “development branch”. | ||
|
|
||
| If you need to work with a specific stable version: | ||
|
|
||
| - Use [`sandpaper::pin_version()`](https://carpentries.github.io/sandpaper/articles/building-with-renv.html#pinning-specific-package-versions). This will: | ||
| + Update the `renv.lock` file with the specific version, | ||
| + Update the cache. | ||
| - Push the updated `renv.lock` file. | ||
|
|
||
| #### Reviewer: | ||
|
|
||
| You can follow this steps: | ||
|
|
||
| - Clone the repo or Pull the branch on Rstudio. | ||
| - Checkout to the branch to review. | ||
| - Use [`renv::restore()`](https://carpentries.github.io/sandpaper/reference/dependency_management.html#details) to align the packages in your cache with the ones in the `renv.lock` file (defined by the Developer). | ||
| - Render lesson with [`sandpaper::build_lesson()`](https://carpentries.github.io/sandpaper/reference/build_lesson.html). This will open an html tab in your browser to review. | ||
| - Make any edit suggestion in the `.Rmd` files inside the `episodes/` folder. | ||
|
|
||
| #### Maintainer: | ||
|
|
||
| You can follow this references: | ||
|
|
||
| - Update these steps from any discussion on issues. | ||
| - Review how to [maintain a Healthy Infrastructure](https://carpentries.github.io/sandpaper-docs/update.html). | ||
| - Review how to [Automate a Pull Request](https://carpentries.github.io/sandpaper-docs/pull-request.html#automated-pull-requests). Lessons outside of the carpentries need to [set up a Pull Request bot](https://carpentries.github.io/sandpaper-docs/pull-request.html#automated-pull-requests) with the [Carpentries Apprentice bot](https://github.com/carpentries-bot). | ||
|
|
||
|
|
||
| ### Using GitHub | ||
|
|
||
| If you choose to contribute via GitHub, you may want to look at [How to | ||
|
|
@@ -95,17 +138,17 @@ final say over what gets merged into the lesson. | |
|
|
||
| ### Other Resources | ||
|
|
||
| The Carpentries is a global organisation with volunteers and learners all over | ||
| The Epiverse-TRACE is a global organisation with volunteers and learners all over | ||
| the world. We share values of inclusivity and a passion for sharing knowledge, | ||
| teaching and learning. There are several ways to connect with The Carpentries | ||
| community listed at <https://carpentries.org/connect/> including via social | ||
| teaching and learning. There are several ways to connect with The Epiverse-TRACE | ||
| community listed at <https://github.com/epiverse-trace/> including via social | ||
| media, slack, newsletters, and email lists. You can also [reach us by | ||
| email][contact]. | ||
|
|
||
| [repo]: https://example.com/FIXME | ||
| [repo-issues]: https://example.com/FIXME/issues | ||
| [contact]: mailto:[email protected] | ||
| [cp-site]: https://carpentries.org/ | ||
| [repo-issues]: https://github.com/epiverse-trace/tutorials/issues | ||
| [contact]: mailto:[email protected] | ||
| [cp-site]: https://epiverse-trace.github.io/ | ||
| [dc-issues]: https://github.com/issues?q=user%3Adatacarpentry | ||
| [dc-lessons]: https://datacarpentry.org/lessons/ | ||
| [dc-site]: https://datacarpentry.org/ | ||
|
|
@@ -114,7 +157,7 @@ email][contact]. | |
| [github-flow]: https://guides.github.com/introduction/flow/ | ||
| [github-join]: https://github.com/join | ||
| [how-contribute]: https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github | ||
| [issues]: https://carpentries.org/help-wanted-issues/ | ||
| [issues]: https://github.com/epiverse-trace/tutorials/issues | ||
| [lc-issues]: https://github.com/issues?q=user%3ALibraryCarpentry | ||
| [swc-issues]: https://github.com/issues?q=user%3Aswcarpentry | ||
| [swc-lessons]: https://software-carpentry.org/lessons/ | ||
|
|
||