-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Seperated out contributing vs maintaining guidelines. (#9)
* Ignore regenerated dir * Source and call outs * Oh fork! * Restructured and added forks * Distinct files for contributing and maintaining * Request for access * Cross referencing * Added branching
- Loading branch information
Showing
8 changed files
with
187 additions
and
57 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
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,126 +1,135 @@ | ||
| # Contributing | ||
| # Contributing Guidelines | ||
|
|
||
| This resource is created in mind so that the community that uses it, can also contribute to it. We hope this mindset will encourage the resource to grow and stay up-to-date for R learners. | ||
| This resource is created in mind so that the community that uses it, can also contribute to it. We hope this mindset will encourage the resource to grow and stay up-to-date for R learners. | ||
|
|
||
| Importantly, **all skill levels** are welcome to contribute, even if you think your skills are not up to scratch - this is what this guide is for! | ||
| Importantly, **all skill levels** are welcome to contribute, even if you think your skills are not up to scratch - this is what this guide is for! There is also a way for you to contribute [if code/git/Quarto is not your cup of tea](#sec-noncode-contributions). | ||
|
|
||
| ### Hello Quarto! | ||
|
|
||
| This book is built by [Quarto](https://quarto.org/) which is an open source, cross-language publishing system that allows users to build beautiful things from blogs, to websites and books! | ||
|
|
||
| You can learn more about the capabilities of Quarto in [this talk](https://www.youtube.com/watch?v=p7Hxu4coDl8) by Mine Çetinkaya-Rundel & Julia Stewart Lowndes at posit::conf(2023) | ||
|
|
||
| #### Install Quarto | ||
| #### Install Quarto {#sec-installquarto} | ||
|
|
||
| Let's first make sure we the latest version of [Quarto](https://quarto.org/docs/get-started/) installed. | ||
| First things first, let's make sure we have the latest version of Quarto installed using these [instructions](https://quarto.org/docs/get-started/) | ||
|
|
||
| ### GitHub Workflow | ||
| ### GitHub Workflow {#sec-githubworkflow} | ||
|
|
||
| Let’s talk about the Git/GitHub part of the workflow. Git is a **version control** system. It that **tracks changes in our code** that generated this book and helps us **coordinate our collaborative edits**. | ||
| Next, we need to talk about the Git/GitHub part of the workflow. Git is a **version control** system. It that **tracks changes in our code** that generated this book and helps us **coordinate our collaborative edits**. | ||
|
|
||
| Git monitors the changes in a project directory a.k.a **repository** or "repo". There are two types of repositories: | ||
| Git monitors the changes in a project directory a.k.a **repository** or "repo". There are two types of repositories: | ||
|
|
||
| - **Local** repository: This is a project directory that exists _locally_ in your computer than git is actively watching over. | ||
| - **Local** repository: This is a project directory that exists *locally* in your computer than git is actively watching over. | ||
|
|
||
| - **Remote** repository: This is a **synced** copy of your local repo. The [remote repo](https://github.com/unsw-edu-au/r4psych) for this book lives on GitHub. GitHub **centralises** our collaborative efforts. It provides a platform for the community to make a local copy of the book, create changes and introduce them back to the remote repository. GitHub also acts as the hosting service for the book itself which is also a big bonus for us. | ||
| - **Remote** repository: This is a **synced** copy of your local repo. The [remote repo](https://github.com/unsw-edu-au/r4psych) for this book lives on GitHub. GitHub **centralises** our collaborative efforts. It provides a platform for the community to make a local copy of the book, create changes and introduce them back to the remote repository. GitHub also acts as the hosting service for the book itself which is also a big bonus for us. | ||
|
|
||
| ::: {.callout-tip} | ||
| A great resource on GitHub setup and collaboration is [Happy Git with R](https://happygitwithr.com/), which includes fantastic background philosophy as well as tips for set-up, workflows, and collaboration. | ||
| ::: | ||
|
|
||
| #### Sign up to GitHub | ||
|
|
||
| Start by getting yourself an account at GitHub [by signing up here](https://github.com/signup) | ||
|
|
||
| #### Install git {#sec-installgit} | ||
|
|
||
| #### Install git | ||
| Follow [these instructions](https://happygitwithr.com/install-git) from "Happy Git with R" to install git to your computer. There are specific instructions for different operating systems. | ||
|
|
||
| Follow [these instructions](https://happygitwithr.com/install-git) from "Happy Git with R" to install git to your computer. There are specific instructions for different operating systems. | ||
| #### Install a git client {#sec-installgitclient} | ||
|
|
||
| #### Install a git client | ||
| Traditionally, git has been used in the shell terminal. This is the 'back-end' of the computer and allows you to interact with your computer using code. This means that you have to type out commands to tell git what to do. This approach can become a little overwhelming when you are starting out. | ||
|
|
||
| Traditionally, git has been used in the shell terminal. This is the 'back-end' of the computer and you can interact with your computer using code. This means that you have to type out commands to tell git what to do. This method can become a little overwhelming when you are starting out because you have to learn all the different commands. | ||
| Instead, we suggest using a git client like [Github Desktop](https://desktop.github.com/), however it is limited to only to Windows and Mac. If you use Linux, [GitKraken](https://www.gitkraken.com/git-client) is also a great alternative. There are many [git clients to choose from](https://git-scm.com/downloads/guis). Once you start to get the hang on things, all of these clients are much of the same and its a matter of personal preference. | ||
|
|
||
| If you are starting out with git and GitHub, we suggest using a git client like [Github Desktop](https://desktop.github.com/), however it is limited to only to Windows and Mac. If you use Linux, [GitKraken](https://www.gitkraken.com/git-client) is also a great alternative. | ||
| If you are an RStudio user, there is a [built-in git tab ](https://jennybc.github.io/2014-05-12-ubc/ubc-r/session03_git.html#configurerstudio) to the interface, its features are more simplified than the previously mentioned clients but does the basic commands that we will talk about next. | ||
|
|
||
| There are many [git clients to choose from](https://git-scm.com/downloads/guis). Once you start to get the hang on things, all of these clients are much of the same and its a matter of personal preference. | ||
| Once you have downloaded a client, follow it's instructions to login and connect your Github account to the client. | ||
|
|
||
| If you are an RStudio user, there is a [git tab that is built-in](https://jennybc.github.io/2014-05-12-ubc/ubc-r/session03_git.html#configurerstudio) to the interface, its features are more simplified than the previously mentioned clients but does the basic commands that we will talk about next. | ||
|
|
||
| ::: {.callout-note} | ||
| ::: callout-note | ||
| For the rest of the chapter, we will focus on using Github Desktop, but the main git commands should translate to whichever client you are using. | ||
| ::: | ||
|
|
||
| #### Cloning: make a local copy | ||
|
|
||
| Now that we have all the installation out of the way, we can get started! | ||
|
|
||
| Lets first get you a local copy of the book onto your computer by "cloning" the repository | ||
|
|
||
| Head over to the [remote repo for the book](https://github.com/unsw-edu-au/r4psych): | ||
|
|
||
| 1. Click on the big green button that says **Code** | ||
| ### The Contributor's workflow | ||
|
|
||
|  | ||
| We will work on forks (independent copies of the book) so as to not overwrite each other’s work and have a systematic way in introducing new contributions to the book. Coordinating collaborative changes on the same project is what GitHub does best. | ||
|
|
||
| Here you will find a drop-down menu showing different methods of cloning the code from the remote repo. | ||
| The `main` branch is currently the most recent approved version of the book - this is displayed at https://unsw-edu-au.github.io/r4psych/ | ||
|
|
||
| We will **stick with the default option of using HTTPS** a.k.a. cloning by using the URL of the remote repo. | ||
| The contributing workflow looks like this: | ||
|
|
||
| 3. Click on the copy URL button (The stacked squares icon) | ||
| 1. You fork the most recent version from `main` | ||
|
|
||
| 4. Navigate to Github Desktop and click on the first drop down menu from the left. Here you will find the **Add** button. | ||
| 2. You make your edits, you **commit** regularly, you **push** regularly to the remote (github.com) | ||
|
|
||
|  | ||
|
|
||
| 5. Click on **Add** and then **Clone Repository** | ||
| 3. When you are happy with your changes, you will create a **pull request** for your contribution and one of the core maintainers will review it. Edits may be requested or one of the maintainers will make the changes after having a conversation with you. | ||
|
|
||
| 6. Click on the **URL** option and paste in the URL of this book's remote repo e.g. **https://github.com/unsw-edu-au/r4psych** | ||
| 4. Once everything and everyone is happy and dandy with the final changes, your changes will be **approved and merged into main**. When this happens, your branch is deleted on the remote and you will also delete it locally. | ||
|
|
||
| 7. Under **Local Path**, you can choose where you want to place this cloned repo. Avoid putting your repos in Cloud services such as Dropbox or Google Drive. These can sometimes interfere with git's ability to track your changes. | ||
| Now let's walk through this workflow step by step | ||
|
|
||
| 8. Finally, click **Clone** and let git do the work! It will copy everything that is in the remote repo and bring it down locally on your computer! | ||
|
|
||
| 9. Navigate to the local path where you told git to clone to in Step 7 and check out the directories. You will learn more about these in [Book Structure](#sec-bookstructure) | ||
| ::: {.callout-note} | ||
| The following sections assumes you’ve completed the initial set-up of [installing git](#sec-installgit) and a [git client](#sec-installgitclient) | ||
| ::: | ||
|
|
||
| #### Branches | ||
| #### Fork: Create an independent copy of the book | ||
|
|
||
| We will work in branches so as to not overwrite each other’s work and have a systematic way in introducing new contributions to the book. Coordinating collaboratives changes on branches is what GitHub does best. | ||
| Now that we have all the installation out of the way, we can get started! | ||
|
|
||
| The `main` branch will be the current approved version of the book. The `main` branch is what displays at https://unsw-edu-au.github.io/r4psych/ | ||
| The best way to contribute to the book is to create an independent copy that lives in your Github account. This process is called **creating a fork** and it allows you to make your contributions without it affecting the approved version of the book. | ||
|
|
||
| A nice clean workflow with branches is to consider them temporary. You pull the most recent from `main`, you **create a branch locally**, you make your edits, you commit regularly, you push regularly to github.com, and then you create a pull request for it to be merged into main, and when it’s approved the branch is deleted on github.com and you also delete it locally. That’s the workflow we’ll walk through here. A great resource on GitHub setup and collaboration is Happy Git with R, which includes fantastic background philosophy as well as bash commands for setup, workflows, and collaboration. | ||
| 1. To create a fork, head over to the [remote repo for the book](https://github.com/unsw-edu-au/r4psych) and click on the **Fork** button on the right hand side of the webpage | ||
|
|
||
| The following assumes you’ve completed the initial setup from the previous chapter. | ||
|  | ||
|
|
||
| #### Fetch the latest version | ||
| 2. Continue to the next webpage and leave the default settings as they are and click the green button *Create fork* | ||
|
|
||
| #### Stage and add your changes | ||
|  | ||
|
|
||
| #### Push your work to remote | ||
| Forking will create a duplicate of the `r4psych` book remote repo into your account. This is **your** remote copy that you can make your contributions to. We will talk about how we bring your contributions back to the `r4psych` remote repo later in [Create a pull request](XX). | ||
|
|
||
| #### Clone: Create a local copy of your fork | ||
| Once you have a fork, we will get a local copy of the book onto your computer by "cloning" the forked repository. | ||
|
|
||
| 1. Head to the webpage of your forked repository. The URL for it should look something like: **https://github.com/your-usename/r4psych** | ||
|
|
||
| 2. Click on the big green button that says **Code** | ||
|
|
||
|  | ||
|
|
||
| Here you will find a drop-down menu showing different methods of cloning the code from the remote repo. | ||
|
|
||
| We will **stick with the default option of using HTTPS** a.k.a. cloning by using the URL of the remote repo. | ||
|
|
||
| 3. Click on the copy URL button (The stacked squares icon) | ||
|
|
||
| 4. Navigate to Github Desktop and click on the first drop down menu from the left. Here you will find the **Add** button. | ||
|
|
||
|  | ||
|
|
||
| 5. Click on **Add** and then **Clone Repository** | ||
|
|
||
| ### Quarto Workflow | ||
| 6. Click on the **URL** option and paste in the URL of your fork's remote repo e.g. **https://github.com/your-username/r4psych** | ||
|
|
||
| ## Book Structure {#sec-bookstructure} | ||
| 7. Under **Local Path**, you can choose where you want to place this cloned repo. Avoid putting your repos in Cloud services such as Dropbox or Google Drive. These can sometimes interfere with git's ability to track your changes. | ||
|
|
||
| ## Book Practices and Conventions | ||
| 8. Finally, click **Clone** and let git do the work! It will copy everything that is in the remote repo and bring it down locally on your computer! | ||
|
|
||
| ## Book Contributions | ||
| 9. Navigate to the local path where you told git to clone to in Step 7 and check out the directories. You will learn more about these in [Book Structure](#sec-bookstructure) | ||
|
|
||
| ### Edits | ||
| #### Make your changes | ||
|
|
||
| ### Additions | ||
| #### Push your work to remote | ||
|
|
||
| ## Submit a pull request | ||
| #### Create a pull request | ||
|
|
||
| ### `{renv}`: Managing R packages | ||
|
|
||
| #### `{renv}` workflow | ||
|
|
||
| ### Book Structure {#sec-bookstructure} | ||
|
|
||
| #### Book Practices and Conventions | ||
|
|
||
| ### Can I make a contribution without using Git? {#sec-noncode-contributions} | ||
|
|
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
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 |
|---|---|---|
| @@ -0,0 +1,120 @@ | ||
| # Maintainer's Guide | ||
|
|
||
| ### Getting access | ||
|
|
||
| First, let's make sure you have collaborator access to the repository. | ||
|
|
||
| 1. Head over to your [repository settings](https://github.com/settings/repositories) | ||
|
|
||
| 2. If you see **unsw-edu-au** and the repo name: `unsw-edu-au/r4psych` in the list then you have collaborator access to the repository. | ||
|
|
||
|  | ||
|
|
||
| If you don't, let's go through how you can request an invite to be a collaborator | ||
|
|
||
| #### Request access | ||
|
|
||
| [Create an issue](https://github.com/unsw-edu-au/r4psych/issues) requesting for collaborator access and one of the maintainers with admin rights will send through an invite. | ||
|
|
||
| ### The set up | ||
|
|
||
| The set up for maintainer's is the same for contributors. Check out the following sections to get started: | ||
|
|
||
| - [Install Quarto](#sec-installquarto) | ||
| - [GitHub Workflow](#sec-githubworkflow) | ||
|
|
||
| ### The Maintainer's workflow | ||
|
|
||
| The maintainer's workflow goes like this: | ||
|
|
||
| 1. You [clone](sec-maintain-clone) the [remote repo](https://github.com/unsw-edu-au/r4psych/) | ||
|
|
||
| 2. You create a new feature [**branch**](sec-maintain-branch). | ||
|
|
||
| 2. You work on your branch and [make your edits](sec-maintain-edit), you **commit** regularly, you **push** regularly to the remote. | ||
|
|
||
| 3. When you are happy with your changes, you will create a [**pull request**](sec-maintain-pr) for your contribution and one of the other maintainers will review it. Edits may be requested or one of the maintainers will make the changes after having a conversation with you. | ||
|
|
||
| 4. Once everything and everyone is happy and dandy with the final changes, your changes will be **approved and merged into main**. When this happens, your branch is deleted on the remote and you will also delete it locally. | ||
|
|
||
| This workflow treats branches as temporary entities and will keeps the remote tidy and streamlined. | ||
|
|
||
| Now let's walk through this workflow step by step. | ||
|
|
||
| ::: {.callout-note} | ||
| The next sections assumes you’ve completed the initial set-up of [installing git](#sec-installgit) and a [git client](#sec-installgitclient). We will focus on using Github Desktop, but the main git commands should translate to whichever client you are using. | ||
| ::: | ||
|
|
||
| #### Clone: Create a local copy of the book {sec-maintain-clone} | ||
|
|
||
| Now that we have all the installation/setup out of the way, we can get started! | ||
|
|
||
| Lets first get you a local copy of the book onto your computer by "cloning" the repository | ||
|
|
||
| Head over to the [remote repo for the book](https://github.com/unsw-edu-au/r4psych): | ||
|
|
||
| 1. Click on the big green button that says **Code** | ||
|
|
||
|  | ||
|
|
||
| Here you will find a drop-down menu showing different methods of cloning the code from the remote repo. | ||
|
|
||
| We will **stick with the default option of using HTTPS** a.k.a. cloning by using the URL of the remote repo. | ||
|
|
||
| 3. Click on the copy URL button (The stacked squares icon) | ||
|
|
||
| 4. Navigate to Github Desktop and click on the first drop down menu from the left. Here you will find the **Add** button. | ||
|
|
||
|  | ||
|
|
||
| 5. Click on **Add** and then **Clone Repository** | ||
|
|
||
| 6. Click on the **URL** option and paste in the URL of this book's remote repo e.g. **https://github.com/unsw-edu-au/r4psych** | ||
|
|
||
| 7. Under **Local Path**, you can choose where you want to place this cloned repo. Avoid putting your repos in Cloud services such as Dropbox or Google Drive. These can sometimes interfere with git's ability to track your changes. | ||
|
|
||
| 8. Finally, click **Clone** and let git do the work! It will copy everything that is in the remote repo and bring it down locally on your computer! | ||
|
|
||
| 9. Navigate to the local path where you told git to clone to in Step 7 and check out the directories. You will learn more about these in [Book Structure](#sec-bookstructure) | ||
|
|
||
| #### Branches: Create your own working copy {sec-maintain-branch} | ||
|
|
||
| As maintainers, we will work on [branches](sec-maintain-branch). (internal copies of the book) so as to not overwrite each other’s work. This approach will also allow us to have a systematic way in introducing new content to the book. Coordinating collaborative changes on the same project is what GitHub does best. | ||
|
|
||
| The `main` branch is currently the most recent approved version of the book - this is displayed at https://unsw-edu-au.github.io/r4psych/ | ||
|
|
||
| When you clone a repository, the `main` branch is selected by default. | ||
|
|
||
| To create your own branch: | ||
|
|
||
| 1. Click on the middle menu that says "Current branch **main**" | ||
|
|
||
| 2. Click on **"New Branch"** | ||
|
|
||
|  | ||
|
|
||
| 3. Give your branch a name. | ||
|
|
||
| Keep it concise and related to the feature you are going to work on e.g `restructure-wrangle`. Separate words with a hyphen. | ||
|
|
||
| At the end of your branch name, put down your initials, that way other maintainers know who is working on which branch. e.g `restructure-wrangle-fk` | ||
|
|
||
| 4. Click on "Create Branch" and voila! Git will automatically switch from `main` to your branch for you. | ||
|
|
||
| At this stage, your branch exists locally on your computer, no where else. | ||
|
|
||
| 5. Next, we will click on "Publish branch", this will make your branch available on the remote repo so we can formally incorporate its changes to the `main` once your edits are done. Publishing your branch also allows other maintainer's see your progress. | ||
|
|
||
| #### Make your changes {sec-maintain-edit} | ||
|
|
||
|
|
||
|
|
||
| #### Create a pull request {sec-maintain-pr} | ||
|
|
||
| ### `{renv}`: Managing R packages | ||
|
|
||
| #### `{renv}` workflow | ||
|
|
||
| ### Book Structure {#sec-bookstructure} | ||
|
|
||
|
|