Write about the more problematic GitHub configs

_bookdown.yml

@@ -42,7 +42,7 @@ rmd_files: [
 
   "remote-setups-intro.Rmd",
   "remote-setups-common.Rmd",
-  "remote-setups-peculiar.Rmd",
+  "remote-setups-equivocal.Rmd",
 
   "workflows-intro.Rmd",
   "workflows-repeated-amend.Rmd",

connect-credential-caching.Rmd

@@ -14,7 +14,7 @@ Remember: the transport protocol is controlled by the URL you use for remote rep
 HTTPS remotes look like `https://github.com/<OWNER>/<REPO>.git`.  
 SSH remotes look like `[email protected]:<OWNER>/<REPO>.git`.
 
-## You should get a personal access token (PAT)
+## You should get a personal access token (PAT) {#get-a-pat}
 
 ### Why a PAT?
 

process-github-config-diagrams-for-happy-git.R

@@ -5,12 +5,12 @@ library(here)
 
 # TODO: soon, I should move the source Keynote document (or part of it)
 # into this project
-img_paths <- dir_ls("~/rrr/happy-git-with-r-slides/github-configs/2020-06_usethis-motivated-git-diagrams/")
+exported_paths <- dir_ls("~/rrr/happy-git-with-r-slides/github-configs/2020-06_usethis-motivated-git-diagrams/")
 
-path_file(img_paths)
+path_file(exported_paths)
 
 # practicing
-y <- image_read(img_paths[[2]])
+y <- image_read(exported_paths[[2]])
 y
 
 # wow much fiddling here to get the crop geometry right
@@ -20,7 +20,11 @@ z %>%
   image_border(color = "blue")
 
 # doing it to all figs
-dir_create(here("img", "github-configs"))
+dir <- here("img", "github-configs")
+dir_create(dir)
+# clean out previous attempts
+dir_ls(dir) %>%
+  file_delete()
 
 f <- function(file) {
   file %>%
@@ -29,16 +33,14 @@ f <- function(file) {
     image_write(here("img", "github-configs", path_file(file)))
 }
 
-walk(img_paths, f)
+walk(exported_paths, f)
 
-cropped_paths <- dir_ls(here("img", "github-configs"))
+cropped_paths <- dir_ls(dir)
 
-path_file(img_paths)
+path_file(cropped_paths)
 
-name_dat <- tibble(
-  raw = path_file(img_paths)
-) %>%
-  mutate(number = str_extract(raw, "\\d+(?=[.]jpeg$)"))
+name_dat <- tibble(filename = path_file(cropped_paths)) %>%
+  mutate(number = str_extract(filename, "\\d+(?=[.]jpeg$)"))
 
 usethis_labels <- tribble(
   ~ number, ~ label,
@@ -49,13 +51,16 @@ usethis_labels <- tribble(
   "005", "fork-them",
   "006", "fork-them-pull-request",
   "007", "fork-ours",
-  "008", "fork_upstream_is_not_origin_parent"
+  "008", "fork_upstream_is_not_origin_parent",
+  "009", "maybe_ours_or_theirs",
+  "010", "maybe_fork"
 )
 
 name_dat <- name_dat %>%
   left_join(usethis_labels)
 
 file_copy(
   cropped_paths,
-  here("img", path_ext_set(name_dat$label, "png"))
+  here("img", path_ext_set(name_dat$label, "png")),
+  overwrite = TRUE
 )

remote-setups-common.Rmd

@@ -21,7 +21,7 @@ This is not very exciting, but sets the stage for what's to come. We introduce t
 
 `usethis::use_git()` can create this setup in a local project, i.e. it initializes a Git repo. usethis describes this setup as "no_github".
 
-## Ours (more specifically, mine)
+## Ours (more specifically, mine) {#ours-you}
 
 A common next step is to associate a local repo with a copy on GitHub, owned by you.
 
@@ -33,7 +33,7 @@ A remote named `origin` is configured and you have permission to push to (and pu
 
 `usethis::use_github()` can create this setup from a local repository, as long as you have configured a GitHub personal access token. usethis describes this setup as "ours".
 
-## Ours
+## Ours {#ours-them}
 
 Here is a variation on "ours" that is equivalent in practice.
 
@@ -55,7 +55,7 @@ Way to get here with usethis:
 
 usethis describes this setup as "ours".
 
-## Theirs
+## Theirs {#theirs}
 
 This is a setup that many people get themselves into, when it's not actually what they need. It's not broken *per se*, but it's limiting.
 
@@ -76,7 +76,7 @@ usethis describes this setup as "theirs".
 
 What if you do want to make a pull request? This means you should have done *fork-and-clone* instead of *clone*. If you've made no changes or they're easy to save somewhere temporarily, just start over with a fork-and-clone workflow (see below) and re-introduce your changes. It is also possible to preserve your work in a local branch, fork the primary repo, re-configure your remotes, re-sync up with the source repo, and get back on track. But this is much easier to goof up. And remember to use `usethis::create_from_github(fork = TRUE)` in the future!
 
-## Fork (of theirs)
+## Fork (of theirs) {#fork-them}
 
 This is an ideal setup if you want to make a pull request and generally follow the development of a source repo owned by someone else.
 
@@ -102,7 +102,7 @@ In this case, you have permission to push to the source repo, but you elect to c
 
 `usethis::create_from_github("OWNER/REPO", fork = TRUE)` can create this setup, as long as you have configured a GitHub personal access token (PAT). usethis describes this setup as "fork".
 
-## Fork (salvageable)
+## Fork (salvageable) {#fork_upstream_is_not_origin_parent}
 
 Here is one last fork setup that's sub-optimal, but it can be salvaged.
 

remote-setups-equivocal.Rmd

@@ -0,0 +1,51 @@
+# Equivocal remote setups {#equivocal}
+
+Just like the previous section about the most common setups, we only consider a very constrained set of remotes:
+
+* The remote is on GitHub, e.g. its URL looks something like `https://github.com/OWNER/REPO.git` or `[email protected]:OWNER/REPO.git`.
+* The remote is named `origin` or `upstream`.
+
+The setups described here are characterized by *incomplete information*.
+This section exists mostly to explain feedback that the usethis package might give about a GitHub remote configuration. *2020-10 note: this currently refers to features in a development version of usethis. These features will appear in usethis v2.0.0.*
+
+To identify any of the remote setups described in section \@ref(common-remote-setups), we need information from GitHub:
+
+  * Whether you can push to a repo
+  * Whether a repo is a fork
+  * For a fork, what is its source repo
+
+Sometimes some of this information is publicly available, but some of it never is, such as repo permissions.
+This means that programmatic access to this information, i.e. requests to the GitHub API, generally requires authorization by an authenticated GitHub user.
+
+This means that client packages, like usethis, work best when you have configured a GitHub personal access token (PAT).
+See section \@ref(get-a-pat) for more details on why and how to do that.
+
+(If you've configured a PAT and are being told your GitHub config is problematic, consider these other explanations: Are you offline? Is GitHub down?)
+
+## Maybe "ours" or "theirs"
+
+When we detect just one GitHub remote, but we can't verify the info above, usethis describes the setup as "maybe_ours_or_theirs".
+
+```{r maybe_ours_or_theirs, echo = FALSE, out.width = "60%"}
+knitr::include_graphics("img/maybe_ours_or_theirs.png")
+```
+
+Once a PAT is available, this setup can be identified as being ["ours" (belonging to you)](#ours-you), ["ours" (but belonging to someone else)](#ours-them), or ["theirs"](#theirs).
+
+## Maybe fork
+
+When we detect just two GitHub remotes, but we can't verify the info above, usethis describes the setup as "maybe_fork".
+
+```{r maybe_fork, echo = FALSE, out.width = "60%"}
+knitr::include_graphics("img/maybe_fork.png")
+```
+
+Once a PAT is available, this setup can be identified as being a well-configured [fork](#fork-them) or a [fork with incomplete setup](#fork_upstream_is_not_origin_parent) (or possibly something more weird).
+
+## How to fix
+
+These setups aren't necessarily broken, but usethis needs more information to operate.
+
+To "fix" this, set up a GitHub personal access token.
+See section \@ref(get-a-pat) for more details on why and how to do that.
+