{renv}: Managing R packages{renv}: Managing R packages
+ We will refer to pull requests as PR from now on
-Think of a pull request like code peer review. The idea is have another maintainer go over your eidts and provide any constructive feedback/edits. This process ensures that the contributions are vetted by the maintainers and merged in to the main branch systematically.
Think of a pull request like code peer review. The idea is have another maintainer go over your edits and provide any constructive feedback/edits. This process ensures that the contributions are vetted by the maintainers and merged in to the main branch systematically.
There are two ways to create a pull request:
Once you are happy, click the green button “Create Pull Request”
TA-DA!!! 🎉 You’re done!!! That is the entire git/Github workflow. Now leave this with the maintainer you’ve tagged, they may request have some suggestions for you before the official approval but the hardest part is over!
You will be prompted via email if there are comments or suggestions made to our PR. The conversations are documented via the PR tab on the Github website. Your feature branch is still active, you can continue making changes and commits to your feature and once they are pushed. They are show up in the PR you have created.
-Before you launch into making actual edits to the book, let’s talk about how R packages are managed for this book. This is important since this is a book about using R and you will most definitely introduce packages in certain chapters. Its also important as the book gains more maintainers working across different computers.
+TA-DA!!! 🎉 You’re done!!! That is the entire git/Github workflow. Now leave this with the maintainer you’ve tagged, they may request have some suggestions for you before the official approval but the hardest part is over!
+Before you launch into making edits to the book, let’s talk about how R packages are managed for this book. This is important since this is a book about using R and you will most definitely introduce packages in certain chapters. Its also important as the book gains more maintainers working across different computers.
renv::restore() when they’re next working on a project.
diff --git a/search.json b/search.json
index 2a200c0..777f00a 100644
--- a/search.json
+++ b/search.json
@@ -294,7 +294,7 @@
"href": "maintain.html",
"title": "8 Maintainer’s Guide",
"section": "",
- "text": "8.0.1 Getting access\nFirst, let’s make sure you have collaborator access to the repository.\n\nHead over to your repository settings\nIf you see unsw-edu-au and the repo name: unsw-edu-au/r4psych in the list then you have collaborator access to the repository.\n\n\nIf you don’t, let’s go through how you can request an invite to be a collaborator\n\n8.0.1.1 Request access\nCreate an issue requesting for collaborator access and one of the maintainers with admin rights will send through an invite.\n\n\n\n8.0.2 The set up\nThe set up for maintainer’s is the same for contributors. Check out the following sections to get started:\n\nInstall Quarto\nGitHub Workflow\n\n\n\n8.0.3 The Maintainer’s workflow\nThe maintainer’s workflow goes like this:\n\nYou clone the remote repo\nYou create a new feature branch.\nYou work on your branch and make your edits, you commit regularly, you push regularly to the remote.\nWhen you are happy with your changes, you will create a pull request 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.\nOnce 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.\n\nThis workflow treats branches as temporary entities and will keeps the remote tidy and streamlined.\nNow let’s walk through this workflow step by step.\n\n\n\n\n\n\nNote\n\n\n\nThe next sections assumes you’ve completed the initial set-up of installing git and a git client. We will focus on using Github Desktop, but the main git commands should translate to whichever client you are using.\n\n\n\n\n8.0.4 Clone: Create a local copy of the book\nNow that we have all the installation/setup out of the way, we can get started!\nLets get you a local copy of the book onto your computer by “cloning” the repository\nHead over to the remote repo for the book:\n\nClick on the big green button that says Code\n\n\nHere you will find a drop-down menu showing different methods of cloning the code from the remote repo.\nWe will stick with the default option of using HTTPS a.k.a. cloning by using the URL of the remote repo.\n\nClick on the copy URL button (The stacked squares icon)\nNavigate to Github Desktop and click on the first drop down menu from the left. Here you will find the Add button.\n\n\n\nClick on Add and then Clone Repository\nClick on the URL option and paste in the URL of this book’s remote repo e.g. https://github.com/unsw-edu-au/r4psych\nUnder 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.\nFinally, 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!\nNavigate 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\n\n\n\n8.0.5 Branches: Create your own working copy\nAs maintainers, we will work on branches which are internal copies of the book. This is so we 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.\nThe main branch is currently the most recent approved version of the book - this is displayed at https://unsw-edu-au.github.io/r4psych/\nWhen you clone a repository, the main branch is selected by default.\nTo create your own branch:\n\nClick on the middle menu that says “Current branch main”\nClick on “New Branch”\n\n\n\nGive your branch a name.\n\nKeep it concise and related to the feature you are going to work on e.g restructure-wrangle. Separate words with a hyphen.\nAt 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\n\nClick on “Create Branch” and voila! Git will automatically switch from main to your branch for you.\n\nAt this stage, your branch exists locally on your computer, no where else.\n\nNext, 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.\n\n\n\n8.0.6 Make your changes\nNow that you have our own internal copy of the book, you can freely make changes pertaining to the feature you want to work on.\nNavigate to the local repo and click on the r4pysch.Rproj file. This will open up the project in RStudio.\nYou can also use the buttons in Github Desktop to quickly navigate to the project files.\n\n\n8.0.6.1 Commit: A save point for your work\nNow let’s make a change to a chapter.\n\nAs a proof of concept, let’s add a comment in the Wrangle chapter.\n\n\n\nSave this change and have a look at Github Desktop. Notice how git has detected your change? Additions are flagged in green, any deletions are flagged in red. Cool right?!\n\nNow we are going to commit these changes. Think of committing your work as saving your progress in a video. A commit is a safe anchor point to come back to if you need.\n\nBy default, git will tick the check box for you. This check box process is technically called “staging”. Its choosing the files you want git to track.\nNow include a meaningful, concise message that will be associated with your commit. These are usually summaries that pertains to the changes you’ve made. In this case, “Added comment to Wrangle chapter” will suffice.\nClick on the blue button Commit to restructure-wrangle and git will save your changes as a checkpoint.\n\nThere is not hard and fast rule with how often you should commit your work. Typically they are bite-sized amounts of work towards the feature you are working on. Thinking about commits as potential check points in time you want to come back to e.g. just after some restructuring/rewording of a big section.\n\n\n8.0.6.2 Push: Sync your work with remote\nUp until this point, all your changes exist locally on your computer. No one else has these changes. Our last step to complete our git/Github workflow is to push our work to the remote repo so other it is available for others to review.\nTo push your work:\n\nClick on the blue button that says “Push origin”\n\nThis is sync your local changes with those on the remote. Once you’ve done that, you can view your synced changes on the remote repo by selecting your feature branch name under the left dropdown menu\n\n\nAlternatively, you can click on the third tab menu also labelled as “Push origin” that has an up arrow ⬆️\n\nContinue committing and pushing your work as you make your edits on your feature branch. Its generally good practice to push your work before you step away from working on the book. This is to ensure all your work is synced and shared on the remote.\n\n\n\n8.0.7 Pull Request: Submit your feature for review\nOnce you are happy with your edits on your feature branch and we will prepare a pull request so we can merge them into the main branch.\n\nWe will refer to pull requests as PR from now on\n\nThink of a pull request like code peer review. The idea is have another maintainer go over your eidts and provide any constructive feedback/edits. This process ensures that the contributions are vetted by the maintainers and merged in to the main branch systematically.\nThere are two ways to create a pull request:\n\n8.0.7.1 A. Open PR within GitHub Desktop\n\nAfter pushing your changes, Github Desktop will automatically prompt you to “Preview Pull Request”. Clicking on this blue button will open a window showing you some key details\n\n\n\nAt the top, it will tell you what which base branch you are merging into. By default it will be set to main. In the screenshot above, we can see that we are proposing to merge restructure-wrangle into base: main\nYou will see a preview of the changes you’ve made to the book. Green are additions, red are deletions.\nAt the bottom, it will say whether your edits can be easily merged it or whether there are conflicts. We will talk about how to handle conflicts next.\n\nOnce you are happy with your preview, click on the blue botton to “Create Pull Request”\n\nClicking this button will open a browser to the Github website.\n\n Here you see the same sort of information from the preview. You are prompted to write a short title and short summary for your PR. These will form the basis of your commit message when it’s approved.\n\nKeep your summary concise, use bullet points or hyperlinks if you find them helpful. You can refer to a Github Issue number using a # suffix. (More of this later).\nRequest one of the maintainers using the Reviewer dropdown menu to they can review your PR.\nOnce you are happy, click the green button “Create Pull Request”\n\nTA-DA!!! 🎉 You’re done!!! That is the entire git/Github workflow. Now leave this with the maintainer you’ve tagged, they may request have some suggestions for you before the official approval but the hardest part is over!\n\n\n8.0.7.2 B: Open PR from Github Website\nYou can also directly open a PR via the Github website by clicking on the “Pull Request tab”.\n\nClick on the green button labelled “New Pull Request”\nSelect the branch you want merge into main. Github will display a preview of your PR here.\nClick on the green button “Create Pull Request” where you will be taken to the same screen as step 2. from the previous section.\n\n\n\n8.0.7.3 If suggestions are requested\nYou will be prompted via email if there are comments or suggestions made to our PR. The conversations are documented via the PR tab on the Github website. Your feature branch is still active, you can continue making changes and commits to your feature and once they are pushed. They are show up in the PR you have created.\nBefore you launch into making actual edits to the book, let’s talk about how R packages are managed for this book. This is important since this is a book about using R and you will most definitely introduce packages in certain chapters. Its also important as the book gains more maintainers working across different computers.\n\n\n\n8.0.8 {renv}: Managing R packages\nWe use renv to manage the R packages that are used by the book across different R versions and operating systems. renv uses a package cache. That means you only ever have to download and install a package once, and for each subsequent install!\nLearn more from the renv website\nBriefly, renv monitors and installs any R packages that are used in a project. renv records this information so that anyone opening up this book will have access to the same R package versions:\nrenv stores information in several places:\n\nrenv/library/ directory\n\nHere you can see R packages for the different versions of R that was used during the creation of this book.\n\nrenv.lock\n\nThis is a lockfile and contains information about the R packages so that it can be re-installed on a new computer. The great thing about a lockfile is that you can share this which colleagues and they can use renv to reproduce the exact R package environment that was recorded.\n\n.Rprofile This is a project profile and it is run automatically every time you start R. renv uses it to configure your R session to use the project library in renv/library/.\n\n\n8.0.8.1 {renv} workflow\nWe are going to learn some new renv lingo so help us manage our R package environment.\n\n8.0.8.1.1 When you open up the project\nEach time you open this book project up run:\n\n\n- The library is already synchronized with the lockfile.\n\n\nThis will prompt renv to check and install any R packages that you may not have locally. If you have all the packages installed already, renv will tell you you’re synchronised.\n\n\n8.0.8.1.2 When you want to add R packages\nOver time, our book will need more packages. You can continue to use familiar tools like install.packages(). You can also use renv::install() it’s a little less typing and can install packages from GitHub, Bioconductor, and more, not just CRAN. Ta-da!\n\n\nThe following package(s) will be installed:\n- janitor [2.2.0]\nThese packages will be installed into \"~/work/r4psych/r4psych/renv/library/R-4.4/x86_64-pc-linux-gnu\".\n\n# Installing packages --------------------------------------------------------\n- Installing janitor ... OK [linked from cache]\nSuccessfully installed 1 package in 5.4 milliseconds.\n\n\nAfter installing the package and checking that your code works, you should call renv::snapshot() to record the latest package versions in your lockfile. You’ll need to commit those changes to git and let your collaborators know that you’ve updated the lockfile and they should call renv::restore() when they’re next working on a project.\n\n\n\n\n\n\nNote\n\n\n\nThis is why its good practice to call renv::restore() each time you open the project 😁\n\n\n\n\n\n\n8.0.9 Book Structure",
+ "text": "8.0.1 Getting access\nFirst, let’s make sure you have collaborator access to the repository.\n\nHead over to your repository settings\nIf you see unsw-edu-au and the repo name: unsw-edu-au/r4psych in the list then you have collaborator access to the repository.\n\n\nIf you don’t, let’s go through how you can request an invite to be a collaborator\n\n8.0.1.1 Request access\nCreate an issue requesting for collaborator access and one of the maintainers with admin rights will send through an invite.\n\n\n\n8.0.2 The set up\nThe set up for maintainer’s is the same for contributors. Check out the following sections to get started:\n\nInstall Quarto\nGitHub Workflow\n\n\n\n8.0.3 The Maintainer’s workflow\nThe maintainer’s workflow goes like this:\n\nYou clone the remote repo\nYou create a new feature branch.\nYou work on your branch and make your edits, you commit regularly, you push regularly to the remote.\nWhen you are happy with your changes, you will create a pull request 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.\nOnce 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.\n\nThis workflow treats branches as temporary entities and will keeps the remote tidy and streamlined.\nNow let’s walk through this workflow step by step.\n\n\n\n\n\n\nNote\n\n\n\nThe next sections assumes you’ve completed the initial set-up of installing git and a git client. We will focus on using Github Desktop, but the main git commands should translate to whichever client you are using.\n\n\n\n\n8.0.4 Clone: Create a local copy of the book\nNow that we have all the installation/setup out of the way, we can get started!\nLets get you a local copy of the book onto your computer by “cloning” the repository\nHead over to the remote repo for the book:\n\nClick on the big green button that says Code\n\n\nHere you will find a drop-down menu showing different methods of cloning the code from the remote repo.\nWe will stick with the default option of using HTTPS a.k.a. cloning by using the URL of the remote repo.\n\nClick on the copy URL button (The stacked squares icon)\nNavigate to Github Desktop and click on the first drop down menu from the left. Here you will find the Add button.\n\n\n\nClick on Add and then Clone Repository\nClick on the URL option and paste in the URL of this book’s remote repo e.g. https://github.com/unsw-edu-au/r4psych\nUnder 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.\nFinally, 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!\nNavigate 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\n\n\n\n8.0.5 Branches: Create your own working copy\nAs maintainers, we will work on branches which are internal copies of the book. This is so we 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.\nThe main branch is currently the most recent approved version of the book - this is displayed at https://unsw-edu-au.github.io/r4psych/\nWhen you clone a repository, the main branch is selected by default.\nTo create your own branch:\n\nClick on the middle menu that says “Current branch main”\nClick on “New Branch”\n\n\n\nGive your branch a name.\n\nKeep it concise and related to the feature you are going to work on e.g restructure-wrangle. Separate words with a hyphen.\nAt 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\n\nClick on “Create Branch” and voila! Git will automatically switch from main to your branch for you.\n\nAt this stage, your branch exists locally on your computer, no where else.\n\nNext, 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.\n\n\n\n8.0.6 Make your changes\nNow that you have our own internal copy of the book, you can freely make changes pertaining to the feature you want to work on.\nNavigate to the local repo and click on the r4pysch.Rproj file. This will open up the project in RStudio.\nYou can also use the buttons in Github Desktop to quickly navigate to the project files.\n\n\n8.0.6.1 Commit: A save point for your work\nNow let’s make a change to a chapter.\n\nAs a proof of concept, let’s add a comment in the Wrangle chapter.\n\n\n\nSave this change and have a look at Github Desktop. Notice how git has detected your change? Additions are flagged in green, any deletions are flagged in red. Cool right?!\n\nNow we are going to commit these changes. Think of committing your work as saving your progress in a video. A commit is a safe anchor point to come back to if you need.\n\nBy default, git will tick the check box for you. This check box process is technically called “staging”. Its choosing the files you want git to track.\nNow include a meaningful, concise message that will be associated with your commit. These are usually summaries that pertains to the changes you’ve made. In this case, “Added comment to Wrangle chapter” will suffice.\nClick on the blue button Commit to restructure-wrangle and git will save your changes as a checkpoint.\n\nThere is not hard and fast rule with how often you should commit your work. Typically they are bite-sized amounts of work towards the feature you are working on. Thinking about commits as potential check points in time you want to come back to e.g. just after some restructuring/rewording of a big section.\n\n\n8.0.6.2 Push: Sync your work with remote\nUp until this point, all your changes exist locally on your computer. No one else has these changes. Our last step to complete our git/Github workflow is to push our work to the remote repo so other it is available for others to review.\nTo push your work:\n\nClick on the blue button that says “Push origin”\n\nThis is sync your local changes with those on the remote. Once you’ve done that, you can view your synced changes on the remote repo by selecting your feature branch name under the left dropdown menu\n\n\nAlternatively, you can click on the third tab menu also labelled as “Push origin” that has an up arrow ⬆️\n\nContinue committing and pushing your work as you make your edits on your feature branch. Its generally good practice to push your work before you step away from working on the book. This is to ensure all your work is synced and shared on the remote.\n\n\n\n8.0.7 Pull Request: Submit your feature for review\nOnce you are happy with your edits on your feature branch and we will prepare a pull request so we can merge them into the main branch.\n\nWe will refer to pull requests as PR from now on\n\nThink of a pull request like code peer review. The idea is have another maintainer go over your edits and provide any constructive feedback/edits. This process ensures that the contributions are vetted by the maintainers and merged in to the main branch systematically.\nThere are two ways to create a pull request:\n\n8.0.7.1 A. Open PR within GitHub Desktop\n\nAfter pushing your changes, Github Desktop will automatically prompt you to “Preview Pull Request”. Clicking on this blue button will open a window showing you some key details\n\n\n\nAt the top, it will tell you what which base branch you are merging into. By default it will be set to main. In the screenshot above, we can see that we are proposing to merge restructure-wrangle into base: main\nYou will see a preview of the changes you’ve made to the book. Green are additions, red are deletions.\nAt the bottom, it will say whether your edits can be easily merged it or whether there are conflicts. We will talk about how to handle conflicts next.\n\nOnce you are happy with your preview, click on the blue botton to “Create Pull Request”\n\nClicking this button will open a browser to the Github website.\n\n Here you see the same sort of information from the preview. You are prompted to write a short title and short summary for your PR. These will form the basis of your commit message when it’s approved.\n\nKeep your summary concise, use bullet points or hyperlinks if you find them helpful. You can refer to a Github Issue number using a # suffix. (More of this later).\nRequest one of the maintainers using the Reviewer dropdown menu to they can review your PR.\nOnce you are happy, click the green button “Create Pull Request”\n\n\n\n8.0.7.2 B: Open PR from Github Website\nYou can also directly open a PR via the Github website by clicking on the “Pull Request tab”.\n\nClick on the green button labelled “New Pull Request”\nSelect the branch you want merge into main. Github will display a preview of your PR here.\nClick on the green button “Create Pull Request” where you will be taken to the same screen as step 2. from the previous section.\n\n\n\n8.0.7.3 If suggestions are requested\nYou will be prompted via email if there are comments or suggestions made to our PR. The conversations are documented via the PR tab on the Github website. Your feature branch is still active, you can continue making changes and commits to your feature and once they are pushed. They are show up in the PR you have created.\nTA-DA!!! 🎉 You’re done!!! That is the entire git/Github workflow. Now leave this with the maintainer you’ve tagged, they may request have some suggestions for you before the official approval but the hardest part is over!\nBefore you launch into making edits to the book, let’s talk about how R packages are managed for this book. This is important since this is a book about using R and you will most definitely introduce packages in certain chapters. Its also important as the book gains more maintainers working across different computers.\n\n\n\n8.0.8 {renv}: Managing R packages\nWe use renv to manage the R packages that are used by the book across different R versions and operating systems. renv uses a package cache. That means you only ever have to download and install a package once, and for each subsequent install!\nLearn more from the renv website\nBriefly, renv monitors and installs any R packages that are used in a project. renv records this information so that anyone opening up this book will have access to the same R package versions:\nrenv stores information in several places:\n\nrenv/library/ directory\n\nHere you can see R packages for the different versions of R that was used during the creation of this book.\n\nrenv.lock\n\nThis is a lockfile and contains information about the R packages so that it can be re-installed on a new computer. The great thing about a lockfile is that you can share this which colleagues and they can use renv to reproduce the exact R package environment that was recorded.\n\n.Rprofile This is a project profile and it is run automatically every time you start R. renv uses it to configure your R session to use the project library in renv/library/.\n\n\n8.0.8.1 {renv} workflow\nWe are going to learn some new renv lingo so help us manage our R package environment.\n\n8.0.8.1.1 When you open up the project\nEach time you open this book project up run:\n\n\n- The library is already synchronized with the lockfile.\n\n\nThis will prompt renv to check and install any R packages that you may not have locally. If you have all the packages installed already, renv will tell you you’re synchronised.\n\n\n8.0.8.1.2 When you want to add R packages\nOver time, our book will need more packages. You can continue to use familiar tools like install.packages(). You can also use renv::install() it’s a little less typing and can install packages from GitHub, Bioconductor, and more, not just CRAN. Ta-da!\n\n\nThe following package(s) will be installed:\n- janitor [2.2.0]\nThese packages will be installed into \"~/work/r4psych/r4psych/renv/library/R-4.4/x86_64-pc-linux-gnu\".\n\n# Installing packages --------------------------------------------------------\n- Installing janitor ... OK [linked from cache]\nSuccessfully installed 1 package in 5.5 milliseconds.\n\n\nAfter installing the package and checking that your code works, you should call renv::snapshot() to record the latest package versions in your lockfile. You’ll need to commit those changes to git and let your collaborators know that you’ve updated the lockfile and they should call renv::restore() when they’re next working on a project.\n\n\n\n\n\n\nNote\n\n\n\nThis is why its good practice to call renv::restore() each time you open the project 😁\n\n\n\n\n\n\n8.0.9 Book Structure",
"crumbs": [
"8 Maintainer's Guide"
]