install.packages("devtools")
install.packages("BiocManager")
library(devtools)
library(BiocManager)Forking the project
Once your GitHub account is set up, it’s time to use it. Our core’s version of the dashboard is contained within the InstrumentQC repository. This is publicly available, and since the software repository is licensed under a free copyleft license, you are able to fork (ie. copy) the existing project and modify it.
To do so, you will first navigate to the InstrumentQC repository. From here you will select the fork the repository option
GitHub will then give you the option to rename the project or to keep the existing name. If you modify the name, there may be a couple additional lines of code you will need to also adjust in the future, but this will be minor enough of a concern so don’t let that stop you if you hate the existing name.
With that done, you now have your own copy of the repository. Since it is forked, you can now modify and customize the dashboard so that is customized to your instruments and tracks their QC data. Before proceeding, please make a note about your forked repositories url as you will need it later when when bringing in the project to the local computer environment with Rstudio in a little bit.
Linking Rstudio and GitHub
Setup
The next big task is to set up Rstudio, making sure that Git is set up properly and that you can send the version changes to the repository files to GitHub without any issues.
Go ahead and open up Rstudio. If it is your first time doing so, select the default R installation from the first pop-up window. Open up Rstudio for the first time, and set to use the default R installation.
We first need to make sure Rstudio can communicate with GitHub through Git. To do this we will first install the R package devtools. To do so, copy the following lines of code invidivually into the console window and hit enter to run the commands:
For coding-beginners, please note, if any errors pop up during the installation of devtools, read the red troubleshooting explanations shown, and install any missing package dependencies by swapping in the package name between the quotation marks similar to what was done in the code chunk above to install the devtools package.
Once devtools is installed, and you have called it via library, we can now continue.
Adjacent to your console tab on the lower left, there is another tab called terminal. Go ahead and click it.
Now that you have switched from the console to the terminal, copy-paste using your mouse/right-click the following lines of code individually, editing in your GitHub UserName, and email linked to your GitHub account:
git config --global user.email "JohnDoe@gmail.com"
git config --global user.name "John Doe"GitHub Token
With this done, it is now time to get a GitHub Token that will be used for authorization for your local computer to send/receive files from your GitHub repository.
To do this, open a browser, and navigate back to your GitHub account, click on your profile icon on the far upper right, and then select settings
From here, you will navigate to the lower left side and click on developer settings
Once you are on the next page, you will select Tokens (classic) option
From there, you will now proceed to click on Generate new token and select the classic option
On the next screen, things get busy. Go ahead and place a note for the token with the instrument name so you know which match with each other. Set the expiration for no expiration or a long-period, and only click on the repo option to grant those accesses. Proceed down to the bottom of the screen and click on the green generate token button.
The website will refresh and provide you a GitHub token and the option to copy it. Copy it and temporarily store it in a .txt file (notepad) as you will need it when setting up the connection between Github and Rstudio. You will not be able to see the code again from this screen, so stash wisely, and be cautious not to store this anywhere that others may find it.
Rstudio
Now that you have your token, go back to Rstudio, and enter the following lines of code into your console:
gitcreds::gitcreds_set()A pop-up window will appear. Follow the instructions and when prompted, provide it the Github Token code that you generated. Next hit enter. You should be all set to now pull/push (ie. receive/send) files to GitHub from your local computer.
While we are here, let’s address the last thing we will need to do with the GitHub access token for. Go ahead and enter the following line of code in the console:
usethis::edit_r_environ()This will open an .Renviron file that will likely be blank. Enter the following line of code, swapping in your specific token in its entirety between the quotation marks.
GITHUB_PAT <- "GitHubTokenGoesHere"Once this is done, save and close out of Rstudio. Open it again to make sure the changes are saved.
New Project
Having completed the above, you should now have Git setup to allow Rstudio to communicate with your GitHub account. This should allow you to bring in the copy of the forked InstrumentQC repository to your local computer, and as you modify it, track and save the changes to your GitHub repository where you can access them remotely.
To do this, upon opening Rstudio, navigate to the upper left corner to the File tab and select create a New Project
From here, you will select the Version Control option
You will next select to use the Git option
And now you will provide the url to the forked repository, (ie. the version on your own GitHub). The Project directory should autopopulate.
Before hitting Create Project, make note of where the project is set to be saved at by hitting browse.
In general, for many windows computers, it will be under the document folder, which should be fine. Alternatively, if your workplace forces everyone to save things on OneDrive, the default folder may be somewhere in the cloud. Ideally, try to store it on the local computer to avoid complicating the file.path setup in the next section, so if in a OneDrive scenario, create a new folder under the local C: drive and save it within that folder.
Once you know where you are saving the project to, hit Create Project.
With all that done, you now have the project and all it’s associated code available locally.
Making Changes
To continue, either use the Ctrl + O shortcut to view inside the repository folder, or alternatively, navigate to the upper-left of R studio screen, click file, and Open File. Select the Examples_staff.qmd file and open it.
We want to make sure you can make changes to the file, and that these changes once saved can be committed and pushed to GitHub. Between the first line of text and the code block, add a couple spaces, and then save the file (step 1).
Navigate to the upper right-side of your Rstudio window and click on Git. Under Staged tab, click the white box next to Examples_staff.qmd (step 2). Then hit the Commit button (step 3).
A new window will appear. Write a brief commit message (“Testing that GitHub is setup correctly”) (step 4) and hit commit (step 5). If you get a successful commit message, proceed and click the green push up-arrow (step 6).
If the push to GitHub was successful, you should see a screen that looks similar to this one:
Your system should now be set up correctly. To verify, open your browser and navigate back to your Github repository. You will then click on your commits.
If the version control chages were successfully pushed, you should find your most recent commits and your commit message shown at the top of the page, looking something similar to this.
And if this is the case, congratulations! You have set up the software and connections that are necessary for your local instrument computer to talk with the GitHub repository. The next steps should be easier.