Skip to content

Latest commit

 

History

History
106 lines (77 loc) · 4 KB

CONTRIBUTING.md

File metadata and controls

106 lines (77 loc) · 4 KB
Raw

Contributing New Material

Data Carpentry is an open source project, and we welcome contributions of all kinds: new and improved lessons, bug reports, and small fixes to existing material are all useful.

By contributing, you are agreeing that Data Carpentry may redistribute your work under these licenses.

Table of Contents

Working With GitHub

NOTE: this repository uses gh-pages as our default branch.

  1. Fork the datacarpentry/R-ecology repository on GitHub.

  2. Clone that repository to your own machine. (It is also possible to make minor edits right on GitHub.)

  3. Create a branch from gh-pages for your changes. Give your branch a meaningful name, such as fixing-typos-r-ecology-lesson or adding-tutorial-on-visualization.

  4. Make your changes, commit them, and push them to your repository on GitHub. If your change affects a lesson, please only commit and push the Rmd files. The rendered versions will be generated by the lesson maintainer to avoid merge conflicts.

  5. Send a pull request to the gh-pages branch of the datacarpentry repository for this lesson at http://github.com/datacarpentry/R-ecology

If it is easier for you to send them to us some other way, please mail us at [email protected]. Given a choice between you creating content or wrestling with Git, we'd rather have you doing the former.

File Locations and Formats

Each lesson contains files such as 00-intro.Rmd, 01-filedir.Rmd and so on. (We use two digits followed by a one-word topic key to ensure files appear in the right order when listed.)

For the R material, lessons must be written in RMarkdown (ending in Rmd). A Makefile converts the Rmd files into HTML that are processed by Jekyll (the tool GitHub uses to create websites) as explained in the README file.

Currently, the Makefile also generates the README file from index.md.

Important Note: We use the purl() function from knitr to generate a skeleton file that contains code to be distributed to the workshop participants. This strategy is useful in particular for error-prone pieces of code (e.g., if it contains long URLs). To take full advantage, every line of code that should be included in the handout must be enclosed in an R code chunk with purl=TRUE in the chunk options. Further, to aid students' use of the handout code, consider including explanatory comments. When writing Challenges in particular, you may need to include redundant comments and used the chunk option echo=FALSE. If in doubt consult the Rmd files for examples.

Datasets

We don't store data for lessons inside the lesson repositories. For completed lessons the data should be publicly available in a data repository appropriate to the data type. For lesson development the data may be provided in any way that is convenient including posting to a website, on figshare, a public dropbox link, a GitHub gist, or even included in the PR. Once the PR is ready to merge the data should be placed in the official data repository and all links to the data updated.

Formatting of the material

To ensure a consistent formatting of the lessons, we recommend the following guidelines:

  • No trailing white space
  • Wrap lines at 80 characters (unless it breaks URLs)
  • Use consistent capitalization (e.g., R not r, RStudio not rstudio or Rstudio)
  • Function names are written as function() while variables and packages are written as variable
  • Use unclosed atx style headers (see below):
## Use this format for headers

And not this format
-------------------

FAQ

  • Where can I get help?
    Mail us at [email protected], come chat with us on our IRC channel,