CONTRIBUTING.md

Contributing Guidelines

Contributions of all kinds are welcome. By offering a contribution, you agree to abide by our Code of Conduct and that your work may be made available under the terms of our license.

Decision Making

1. Before each meeting, anyone who wishes may sponsor a proposal by filing an issue in the GitHub repository tagged "proposal", at least 24 hours before the meeting. Follow the "Proposal Issue Template".

2. A quorum is established in a meeting if half or more of voting members are present.

3. Once a person has sponsored a proposal, they are responsible for it. The group may not discuss or vote on the issue unless the sponsor or their delegate is present. The sponsor is also responsible for presenting the item to the group.

4. After the sponsor presents the proposal, a "sense" vote is cast for the proposal prior to any discussion:

   • Who likes the proposal? (+1)
   • Who can live with the proposal? (0)
   • Who disagrees with the proposal? (-1)

5. If all or most of the group likes or can live with the proposal, it is immediately moved to a formal vote with no further discussion.

6. If most of the group disagrees with the proposal, it is postponed for further rework by the sponsor.

7. If some members disagree they can briefly state their objections. A timer is then set for a brief discussion moderated by the facilitator. After 10 minutes or when no one has anything further to add (whichever comes first), the facilitator calls for a yes-or-no vote on the question: "Should we implement this decision over the stated objections?" If a majority votes "yes" the proposal is implemented. Otherwise, the proposal is returned to the sponsor for further work.

Building and Previewing

Setup to locally preview the book:

1. Install R (we recommend that you also install and use the RStudio IDE).

2. Open RStudio by clicking on the novice-py.Rproj file (if not through RStudio, then open an R console in the location of the Merely Useful repo) and install the dependencies by typing in the console:

   # Make sure you have remotes installed
   # install.packages("remotes")
   remotes::install_deps()

Build and preview from the command line:

This book is written in bookdown. If you want to preview builds on your own computer, please:

1. make html and then open _book/index.html.
2. make pdf or make epub to build PDF and EPUB versions (also in the _book folder).

Or via RStudio:

1. When in the R Project (opened via the .Rproj file), use the key bindings Ctrl-Shift-B to build the html output.

For building the PDF, note that bookdown works best with TinyTeX. After installing it, you can run make tex-packages to install all the packages this book depends on.

Workflow for Adding Content

The main development branch is master and the website is built on gh-pages. To add content, create a new branch in the repository and submit a PR. Please only create a PR when you are ready for your change to be reviewed and merged in. In general, only the Rmd files need to be edited.

When reviewing PRs and making changes, it's probably easier to edit the branch directly and push the change up. For comments, please use the commenting features in the PR.

For larger changes (e.g. making a chapter):

• Pick a chapter (as assigned to or by you) and create a branch to work on for that chapter.
• Make some edits and changes.
• Create a Draft Pull Request to the main repo.
• Add the label "work in progress" to that PR.
• When it's ready for review, remove the label, change the PR status to "Ready to review", and post a note in Slack asking for a reviewer.

For other changes:

• If you are making a smaller change, please create a branch with a meaningful name, submit changes, and ask for a reviewer.
• Finally, if you are doing a major reorganization that involves multiple chapters, please put in a proposal first.

Reviewing PRs

• Add yourself as a reviewer to the PR.
• If making a suggested change to the actual text, please use the "Insert a suggestion"
  • For the "reviewee", please accept those changes. GitHub will insert the suggestion directly as a commit, thus giving attribution to the reviewer. Note: This does not work for multi-line suggestions edits (though you can add more lines in the suggestion if desired).
• For individual chapter reviews, look for consistency, content, clarity of material with exercises. Don't worry too much about grammar appearance, structure, etc. This will be done at the end stage.

Specific Content Guidelines

1. bookdown's behavior is controlled by the metadata in _bookdown.yml and in the YAML header of index.Rmd. Please do not add YAML headers to other .Rmd files, since it is ignored when building the entire book.

2. _bookdown.yml contains an ordered list of R Markdown chapters and appendices. This list is repeated in Makefile.

3. The first element of each chapter must be a level-1 heading. Anything before this heading is silently ignored.

4. The ID for each chapter and section heading is set by putting {#some-label} on the heading line. Please use the stem of the file's name in labels, i.e., start all labels for chapter stuff.Rmd with the word stuff. Also include the course type to the beginning (e.g. "r-", "py-", and "rse-").

5. Each chapter starts with a list of questions and a list of learning objectives and ends with a list of key points. These lists are kept in plain Markdown files in the questions, objectives, and keypoints folders respectively so that they can be included in both the chapters and the objectives.Rmd and keypoints.Rmd appendices.

6. The last line in each chapter includes the file links.md, which gives symbolic names to all the external links used in the book. Please always use [text][label] to refer to links and put the URL itself in this file to ensure consistency between chapters.

7. Please use the free desktop version of draw.io to draw diagrams. Save the source as figures/stem/stem.drawio and export drawings as all of PDF, PNG, and SVG.

8. Since LaTeX doesn't understand SVG images, hand-drawn diagrams are included as follows:

   • Create an R code block with the header {r stem-label, echo=FALSE, fig.cap="Some Caption"}, which means:
     • Give this figure the ID fig:stem-label. (Bookdown automatically puts fig: in front of figure labels, though it doesn't prefix section labels with anything.)
     • Don't show the R code used to load the image, just its output (i.e., the image).
     • Give the figure the specified caption.
   • Use insert_graphic("figures/stem/filename.ext") to include your image. If you are using a .pdf image, make sure that you have the same file but as a .svg as well.

9. Use @Name1234 or [@Name1234] to refer to bibliography entries. These entries must exist in the book.bib file. For multiple entries, separate the entries with ;, i.e. [@Name1234;@Name5678].

10. Use \@ref(label) to refer to labels for sections and figures. Note that:

    • This only inserts the section number, not the words Chapter, Appendix, Section, or Figure.
    • Those are round parentheses, not curly braces.
    • If the figure's chunk ID is stem-label, use fig:stem-label to refer to it.

11. Glossary entries are in gloss.md, which is plain Markdown rather than R Markdown.

    • To refer to a glossary entry, use a direct link of the form [text]``(glossary.html#term-label).
    • Glossary definitions are set in bold and use an HTML anchor tag to provide the ID. We should find a more elegant way to do this.

12. There are also some HTML comments containing the word noindent left over from formatting with an earlier template. These were used to prevent indentation of the first line of continuation paragraphs. We will find a more elegant way to handle this as we get closer to production.

13. Do not use View() in your R snippets, as Travis will fail when it tries to launch a viewer from the command line.

Guide for code and text styling

See the code and text style guide here.

Using Python Code Chunks

The process for inserting Python code chunks in R Markdown is the same as for inserting R code chunks. Simply replace {r} with {python} on the first line of the fenced code chunk:

```{python}
# Python chunks will also be syntax highlighted
for num in range(5):
    print(num)
```

Code chunks have options that apply to both R and Python.

When Using Other Software Packages

Travis needs to know what packages to install to build the website:

• For R packages, it is very easy. When in the Merely Useful R Project (by opening the merely-useful.github.io.Rproj file), type usethis::use_package("packagename") in the R Console. This will add the package dependency to the DESCRIPTION file under the imports section.

• For Python packages you'll need to add the package to the .travis.yml under the addons section:

addons:
  apt:
    packages:
    - python3
    # Add more packages below here
    # and looks like "python3-packagename"
    # e.g.:
    - python3-numpy

Documentation on Continuous Building using Travis CI

NOTE: This section is only to document what was done and why. This does not need to be done, unless others want to clone this repository for their own purposes.

Final building of the website is done via Travis CI. In order to get Travis set up to push the final generated book to the master branch, a GitHub Personal Access Token (PAT) must be added. This PAT can be generated and assigned to Travis with the following steps:

1. Create a PAT for your account on GitHub (make sure to enable the "repo" scope so that using this token will enable writing to your GitHub repos) and copy the token to your clipboard.
2. Go to https://travis-ci.org/USER/REPO/settings replacing USER with your GitHub ID and REPO with the name of the forked repository.
3. Under the section "Environment Variables", type GITHUB_TOKEN in the "Name" text box and paste your personal access token into the "Value" text box.
4. The deploy Travis commands found in .travis.yml are then used to access this GitHub PAT.