appendix_pull_request_tutorial.Rmd

# Tutorial for pull request mergers

## General

The following is a checklist of steps to perform before merging the pull request. At any point, if you're not sure what to do, request a review from one of the PR leaders.

## Check branch

PR should be submitted from a **non-main** branch.

<img src="resources/tutorial_pull_request_mergers/1.png" width="700">
<br/>

If PR was submitted from the **main** branch, provide these instructions on how to fix the problem:

1. Close this PR.

2. Follow the instructions here for forgetting to branch if you committed and pushed to GitHub: https://edav.info/github#fixing-mistakes

3. If you have trouble with 2., then delete the local folder of the project, delete your fork on GitHub, and *start over.*

4. Open a new PR.

<br/>
<img src="resources/tutorial_pull_request_mergers/2.png" width="700">



<br/>

##  Examine files that were added or modified
<img src="resources/tutorial_pull_request_mergers/files_changed.png" width="700">
<br/><br/>

- There should be only ONE `.Rmd` file. 

- All of the additional resources should be in the `resources/<project_name>/` folder.

- There should be no other files in the root directory besides the `.Rmd` file.

## Check `.Rmd` filename

- The `.Rmd` filename should be words only and joined with underscores, no white space. (Update: It does not need to be the same as the branch name.)
- The `.Rmd` filename can only contain **lowercase letters**. (Otherwise the filenames do not sort nicely on the repo home page.)

## Check `.Rmd` file contents

- The file should **not** contain a YAML header nor a `---` line.
- The first line should start with a **single hashtag `#`**, followed by a **single whitespace**, and then the title.
- The second line should be blank, followed by the author name(s).
- There should be no additional single hashtag headers in the chapter. (If there are, new chapters will be created.)
- Other hashtag headers should **not** be followed by numbers since the hashtags will create numbered subheadings. Correct: `## Subheading`. Incorrect: `## 3. Subheading`.
- If the file contains a setup chunk in `.Rmd` file, it should **not** contain a `setup` label. (The bookdown render will fail if there are duplicate chunk labels.)
<br/>i.e. use `{r, include=FALSE}` instead of `{r setup, include=FALSE}`.
<br/>[See sample `.Rmd`](https://github.com/jtr13/cc21/blob/main/sample_project.Rmd)
- Links to internal files must contain `resources/<project_name>/` in the path, such as: `![Test Photo](resources/sample_project/election.jpg)`
- The file should not contain any `install.packages()`, `write` functions, `setwd()`, or `getwd()`. 
- If there's anything else that looks odd but you're not sure, assign `jtr13` to review and explain the issue.


## Request changes 

If there are problems with any of the checks listed above, explain why the pull request cannot be merged and request changes by following these steps:

<img src="resources/tutorial_pull_request_mergers/check_format.png" width="700">
<img src="resources/tutorial_pull_request_mergers/request_change_lines.png" width="700">
<img src="resources/tutorial_pull_request_mergers/request_change_files.png" width="700">
<img src="resources/tutorial_pull_request_mergers/request_change_submit_review.png" width="700">

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, review again and either move forward with the merge or explain what changes still need to be made.

<br/> 

## Merge the pull request

If all is good to go, it's time to merge the pull request. There are several steps. 

<!-- ### Add chapter filename to `_bookdown.yml` in PR's `branch` -->
### Steps to Merge the PR
<!-- - Open the `_bookdown.yml` file. -->
- Go to the main branch of our project (jtr13/cc21fall1) and open the `_bookdown.yml` file

- Copy the entire rmd_files section. It would look something like this
`rmd_files: [
'index.Rmd', # must be first chapter
'assignment.Rmd',
....,
....,
]`

<!-- - Open the branch of the submitted PR and open their _bookdown.yml file. -->
- Open the branch of the submitted PR by following these steps:

  + To access the PR branch:

  <img src="resources/tutorial_pull_request_mergers/3.png" width="700">

  + Make sure you are on the PR branch by checking that the PR branch name is shown (not `main`):

  <img src="resources/tutorial_pull_request_mergers/4.png" width="700">

- Remove their rmd_files: [] section and paste the one which we copied from the main branch of our project.

- Add the name of the new file in single quotes followed by a comma under the labelled section (eg. Cheatsheets, Tutorials etc).

- Save the edited version.

- Come back to the PR.

- Merge the PR.

- Click on the Actions tabs and check whether the build has been successful (A successful build will have a green dot in front of the actions). PLEASE NOTE that the actions take a while to complete (approximately 5-6 mins depending on the number of files to be rendered), so you might need to wait for some time to finally check whether the build was successful or not.

- In case the build fail and you are not able to understand or rectify it please tag one of the PR Assigners so that they can review it. PLEASE DO NOT `revert merge` as it would create new branches in the workflow.

<!-- - **delete everything in the file beginning with `rmd_files: [` and then add the name of the new file in single quotes followed by a comma:**

<img src="resources/tutorial_pull_request_mergers/delete_most_of_bookdown_yml.png" width="700">

Why? Because it will be easier to fix the merge conflicts this way. (A better way to do this is to merge main into the PR branch *before* adding the new file but this can't be done on GitHub. If there's interest I will explain how to do this locally.)

- Save the edited version.

- Click the resolve conflicts button:

<img src="resources/tutorial_pull_request_mergers/resolve_conflicts.png" width="700">

- Cut the new filename and paste it into the proper location. Then delete the lines with `<<<<<<< xxxx`, `=======` and `>>>>>>>> main`. In short, the file should look correct when you're done. Click the "Marked as resolved" button and then the green "Commit merge" button. -->

### PR Leaders only: Add part names to `.Rmd` for every first article in part

Only do this if you are adding the first chapter in a PART.

For every first article of each part, add the chapter name on the top of the `.Rmd` file, then propose changes. The example is like this.
<img src="resources/tutorial_pull_request_mergers/chap_1.png" width="700">
<br/><br/>

### Merge PR and leave a comment

Now comes the final step.

**Until you develop experience and are confident that you are doing things correctly, assign another PR merger to review your work:**

@aye21874	(Ayush), @clarissarjtai (Clarissa),	@ejosied (Josie), @hwelinkim (Hyo Won), @ivanye2509	(Xin)
@kfijan	(Katharina), @ktsht	(Alex), @mtz2110 (Maxwell), @s10singh97 (Shashwat), @ShiyuWang88 (Shiyu), @Shruti-Kaushal	(Shruti), @verlocks	(Zheyu)

(Please fix your names if there are mistakes or these aren't the names you go by... you don't need to submit a pull request, just edit the file and commit to the main branch.)

Go back to the conversation tab of the pull requests page, for example: 

https://github.com/jtr13/cc20/pull/23#issuecomment-728506101

Leave comments for congratulations 🎉 (type `:tada:`) and then click on the green button for merge.
<br/> 



### Check updated version

A successful merge means that the addition file or files were added to the project with no merge conflicts. It does not mean that the book will render and deploy to GitHub pages without issues. After the merge, it will take about 5-10 minutes for GitHub Actions to render the book and deploy the updated version. If there's a problem I will be notified by email and will address it. In other words, your job is done. However if you're interested, you can check the progress by clicking Actions at the top of the repo.