Skip to content

Tutorial for maintainers

Jump to bottom
Tian Wang edited this page Nov 1, 2019 · 21 revisions

TODO:

  1. Travis check details add graphs

This tutorial describes the entire workflow of pull request management. Students create pull requests from their branches. Our job is to merge them to the master branch if all requirements are met or request changes otherwise. Refer to the submission instructions on the class website for more information regarding the Bookdown structure.

1. Tagging and assigning

CC1 and CC2 are responsible for this part.

When each pull request comes in, it will be tagged with two labels: type label and content label, which is the same as the Google Sheet on Courseworks. A maintainer will be assigned (referred to as assignee in step 2), and he/she will be responsible for checking whether all requirements are met.

2. Requirement checking and request handling

CC8, CC9, and CC10 are responsible for this part.

There are certain checks that a pull request needs to pass before it can be merged into the master branch. When you are assigned a pull request, work on that pull request by following the steps below.

2.1 Submission requirements

2.1.0 Branch name

A pull request must not be from a master branch of contributors' fork. If it is, let contributors know that they need to create a new branch. You can direct them to this link which explains what to do if you forgot to branch.

2.1.1 .Rmd File Format

  1. Each group should submit exactly one .Rmd file.
  2. The .Rmd filenames in the project repo are words only and joined with underscores, i.e. Do not include whitespace in the name.
  3. The .Rmd files must not contain the YAML header (the section at the top of the .Rmd that includes name, title, date, output, etc.) including the --- line.
  4. The first line starts with a single hashtag (#) followed by a project name (this does not have to be exact same as the project folder name and may include white space). There should be a whitespace after the hashtag, otherwise it will not be rendered as header. No single # headers are used anywhere else in the document (multiple hashtag headers (e.g. ##, ###) are fine).
  5. The second line must be a blank line.
  6. if they have a setup chunk, the label setup must be removed.

2.1.2 Files in Directory

  1. They should not submit a .html version of their project.
  2. Additional resources are in resources/<project_name>/ only.
  3. Remind contributors of a possibility of path change in their .rmd files when resources/<project_name>/ is created.

2.2 Response

You will either merge a pull request or request a change.

2.2.1 Request a change

If there is any requirement that a request does not meet, request a change and add reasons why the pull request cannot be merged.

Then, add a changes requested label to this pull request.

Your job for this pull request is done for now. Once contributors fix their requests, repeat the checking in 2.1 again on updated requests.

2.3 Put the Rmd file into yml

When you are satisfied that all the files in the pull request are in the proper format, you will make some changes to bookdown files on the branch of the pull request, and then merge the pull request, as described below. Do not make these changes to the master branch, because they will cause the book to fail to render.

To let bookdown render successfully, we need to put that Rmd file into _bookdown.yml.

  1. In _bookdown.yml, add the name of the Rmd file in the branch under rmd_files. Try your best to put the file name under the right tag. The class website should now be updated and show the content from the rmd file you just added to _bookdown.yml.

  1. If the project includes any packages that can be only installed by devtools::install_github(), such as ucidata. Go to .travis.yml, add the package name in the rmd file in the branch under r_github_packages.

  1. If the project includes any packages that can be installed by install.packages(), such as tidyverse. Go to DESCRIPTION, add the package name in the branch under Imports.

2.4 Travis Checklist

Navigate to check tab of a pull request. You see a green check mark if the rmd file in the request is compatible with the class website. Note that it may take a while for this automatic checking process.

2.5 Merge the request

  1. Request review of Bo (CC8)/ Yingyu (CC9)/ Tian (CC10).

  2. Merge the request.

  3. Go to the website to see if it's working. Travis needs to rebuild the book after a pull request is merged. Check here to see the progress. You have to clear cache before refreshing the website page to see this. If anything goes wrong, revert the merge and repeat step 2.3.1.

  4. Comment under that pull request to congratulate them on successfully being merged.

3. Merge Chapters

There may only be less than 10 lines in some submissions as they link their contributions to outside source, and these chapters should be merged together.

4. Examples

A standard operation: #29.

Clone this wiki locally