You can install Kyber using the remotes
package:
remotes::install_github("openscapes/kyber@main")
Kyber contains tools for setting up learning cohorts on GitHub, purpose-built for the Openscapes Champions Program.
init_repo()
initializes a local git repository and new GitHub repository
with a README.Rmd, a code of conduct, and a gitignore.create_github_clinic()
creates all of the files you need for teaching a
GitHub clinic.create_team()
creates a new team on GitHub.add_team_members()
adds members to a team on GitHub based on their GitHub
usernames.add_team_to_repo()
adds a team to a GitHub repository.call_agenda()
creates agenda documents for each individual Cohort Call.The chronological steps for creating Openscapes repos and materials using Kyber are detailed in the ReadMe. See this flow chart for understanding how these steps fit together, including the requirements to complete each step. (Kyber flow chart pdf)
Using Kyber requires more configuration than most R packages since Kyber functions automate processes on GitHub that you would normally do by hand.
First, make sure that you have googlesheets4
installed and that you have
authorized your computer to read from Google Sheets. Run the following to
test your configuration settings:
library(googlesheets4)
cohort_registry_url <- "https://docs.google.com/spreadsheets/d/1Ys9KiTXXmZ_laBoCV2QWEm7AcnGSVQaXvm2xpi4XTSc/"
read_sheet(cohort_registry_url, sheet = "test-sheet")
For creating the GitHub Team and adding usernames, Kyber requires you to
set up a GitHub Personal Access Token with scopes for repo and
admin:org. See the GitHub PAT
documentation
for more information about how to generate your PAT. You can create your PAT with usethis::create_github_token()
with their defaults, plus admin:org
.
Please make sure that you do not share your PAT or commit it to a Git repository, since
anyone with your PAT can act as you on GitHub.
library(usethis)
library(gitcreds)
create_github_token(
scopes = c("repo", "user", "gist", "workflow", "admin:org")
)
gitcreds_set()
This workflow often happens in 4 separate stages:
github-clinic
files (days before GitHub Clinic in Call 2)Creating a repo creates a local folder with README.Rmd
library(kyber)
library(rmarkdown)
library(tibble)
library(fs)
repo_name <- "2021-ilm-rotj"
# This will open a README.Rmd for you to edit
# In yaml of README.Rmd, `cohort_name: "Cohort"` replace "Cohort" with specific cohort name
repo_path <- init_repo(repo_name)
# Then render the README.Rmd to README.md
render(path(repo_path, "README.Rmd"))
# We still need to work out the next part of the workflow and the extent to
# which it should be automated, but I imagine something like:
#
# 1. Move README.Rmd out of this repository to another repository that perhaps
# only contains README.Rmds.
# 2. Git add, commit, and push in the repo that only contains README.Rmds.
# 3. Git add, commit, and push in this repository.
Ensure cohort_metadata
is complete in the Cohort Registry sheet, including cohort_website, google_drive_folder and cohort_name_long. These will appear in the Agendas.
library(kyber)
library(googlesheets4)
kyber::call_agenda(
registry_url = "https://docs.google.com/spreadsheets/d/1Ys9KiTXXmZ_laBoCV2QWEm7AcnGSVQaXvm2xpi4XTSc/edit#gid=942365997",
cohort_id = "2022-nasa-champions",
call_number = 3)
The following suggestions aid next steps as of July 14, 2022:
2.1 Move agenda to Google Docs
agenda.md
created from the code above and copy-paste the result into a Google Doc (example: 03_CallAgenda [ 2022-noaa-afsc ]. You might need to to expand the knitted preview into the browser to get it to copy/paste correctly into Google Docs.2.2 Formatting your agenda
How to "update heading 1 to match": (Stef notes this has not been working in these docs) In Google Doc, to update a text style (headings, normal text, with font type, size etc), highlight a section with the style you want, click the styles dropdown shown in the screenshot, and select e.g. "Update Heading 1 to match". Double check the doc because we've noticed it missed some in an agenda.
If you haven't already, clone the Cohort Repo to RStudio (File > New Project > Version Control > Git) , then run the following code. Detailed instructions of what this looks like:
_demo.md
, which is what you'll demo live. first
and last
as is written in the kyber::short_names
call. The easiest thing is to update the column names in the kyber::short_names
code before running (for example: kyber::short_names(cohort$First.Name, cohort$Last.Name)
library(stringr)
library(datapasta) # install.packages("datapasta")
library(kyber) ## remotes::install_github("openscapes/kyber")
library(here)
library(fs)
## use `datapasta` addin to vector_tribble these names formatted from the spreadsheet!
cohort <- c(tibble::tribble(
~first, ~last,
"_demo", "",
"Erin", "Robinson",
"Julie", "Lowndes"
)
)
## create .md files for each Champion
kyber::short_names(cohort$first, cohort$last) |>
create_github_clinic(here())
## copy trailhead image into parent folder
trailhead_png <- system.file("kyber-templates",
"horst-champions-trailhead.png", package = "kyber")
fs::file_copy(trailhead_png, here())
You'll now have .md files for each participant in the cohort! Any duplicate names with have a _LastInitial
. Check by clicking into the github-clinic
folder and opening a file.
Now, commit and push the Markdown files in the github-clinic
folder plus the `horst-champions-trailhead.png in the top-level folder to GitHub.com. Don't push the .gitignore or .rproj since they're not relevant for the Clinic. (You can do Command-A to select all files and then unclick those 2 you don't want).
members
variable to check -members <-
and use the datapasta
Addin > Paste As Tribble to paste the usernames into the members
variable, deleting the previous example user. ## First make sure you have a GitHub PAT set. If you need one, here's what you'd do:
# usethis::create_github_token() ## use their defaults plus `admin:org`
# Sys.setenv(GITHUB_PAT = "ghp_0id4zkO4GqSuEsC6Zs22wf34Y0u3270")
library(kyber)
library(rmarkdown)
library(tibble)
library(fs)
library(datapasta)
## create naming for GitHub - do this once!
repo_name <- "2022-nasa-champions"
team_name <- paste0(repo_name, "-cohort")
create_team(team_name, maintainers = "jules32", org = "openscapes")
## create member variable - do this twice (first as test!)
## this is where you'll use datapasta and run everything below
members <- tibble::tribble(
~username,
"eeholmes"
)
add_team_members(team_name, members = members$username, org = "openscapes")
add_team_to_repo(repo_name, team_name, org = "openscapes")
Yay! Now highlight those usernames in green in the ParticipantList for our bookkeeping!
GitHub organization: https://github.com/nasa-openscapes-workshops
Teams: https://github.com/orgs/nasa-openscapes-workshops/teams
NASA Openscapes Mentors are given GitHub permissions to administer access for participants in workshops. To do this they must have an Owner
role in the AdminTeam
. To grant access to Mentor, an existing Owner of the GitHub Organization must add the Mentor's GitHub username to the AdminTeam
, then click on their name, which will take you to their page within the organization. Change their role to Owner
, which is in a pulldown menu on left side of screen.
Copy and run this code to give users access to the NASA Openscapes 2i2c JupyterHub by adding them to the relevant GitHub Team
library(kyber)
library(rmarkdown)
library(tibble)
library(fs)
library(datapasta)
team_name <- "WorkshopAccess-2i2c"
## for a long list of usernames, we can copy the list from a spreadsheet and use the datapasta Addin 'paste as tribble' and run everything below
members <- tibble::tribble(
~username,
"virdi",
"alexishunzinger"
)
add_team_members(team_name, members = members$username, org = "nasa-openscapes-workshops")
Steps to edit kyber
locally and review those edits:
kyber
project, pull main branch inst/agendas/team_culture.Rmd
)devtools::load_all()
to load local edits for kyber
kyber::call_agenda(
registry_url = "https://docs.google.com/spreadsheets/d/1Ys9KiTXXmZ_laBoCV2QWEm7AcnGSVQaXvm2xpi4XTSc/edit#gid=942365997",
cohort_id = "2022-noaa-afsc-fall",
call_number = 4)
agenda.md
, click Preview, and view it in the Viewer Tab. Usually you can repeat steps 3-5 whenever you make edits you want to review, however if there are problems try restarting you R session.
To contribute to Kyber, fork the repo, unchecking the "Copy the main branch only" box. Start working from the dev
branch, create a new branch like new-branch dev
, and then submit Pull Requests to dev
. If using Git on the command line the workflow would look like:
git checkout -b dev
git pull origin dev
git checkout -b new-branch dev
git push origin new-branch
We started using this workflow when the [California Water Boards Openscapes]((https://cawaterboarddatacenter.github.io/swrcb-openscapes/) team began using Kyber to create Agendas from some unique source Rmd files. For example, Water Boards Cohort Calls are 2 hours, not the default 1.5 hrs, their lesson order is different from Openscapes Core Lessons, and includes a new lesson on Documentation.