From a27f06b690f64a862fe6f5d03d1446e87ba5c853 Mon Sep 17 00:00:00 2001
From: Matthew Butterick <mb@mbtype.com>
Date: Fri, 27 Mar 2015 15:07:48 -0700
Subject: [PATCH] further notes on Git workflow

---
 .../pkg/scribblings/git-workflow.scrbl        | 31 +++++++++++++++----
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/pkgs/racket-doc/pkg/scribblings/git-workflow.scrbl b/pkgs/racket-doc/pkg/scribblings/git-workflow.scrbl
index 78e655471b..1c334de087 100644
--- a/pkgs/racket-doc/pkg/scribblings/git-workflow.scrbl
+++ b/pkgs/racket-doc/pkg/scribblings/git-workflow.scrbl
@@ -82,7 +82,17 @@ develops only a few of them. The intended workflow is as follows:
   omitted. Put another way, the argument to @DFlag{clone} can be a
   path to @nonterm{pkg-name}:
 
-  @commandline{@command{update} --clone @nonterm{path-to}/@nonterm{pkg-name}}}
+  @commandline{@command{update} --clone @nonterm{path-to}/@nonterm{pkg-name}}
+
+  @margin-note{As a further convenience, when building from scratch
+  from the main Racket source repository, the Git configuration
+  ignores a top-level @filepath{extra-pkgs} directory. The directory
+  is intended to be used as a target for @DFlag{clone}:
+
+  @commandline{@command{update} --clone extra-pkgs/@nonterm{pkg-name}}
+
+  which creates the @filepath{extra-pkgs} subdirectory if it doesn't exist.}}
+
 
  @item{If a package's current installation is not drawn from a Git
   repository (e.g., it's drawn from a catalog of built packages for a
@@ -94,14 +104,23 @@ develops only a few of them. The intended workflow is as follows:
 
   A suitable @nonterm{catalog} might be @url{http://pkgs.racket-lang.org}.}
 
- @item{If the cloned Git repository is not the one where you want to
-  push and pull updates, use @exec{git} commands to add or change the
-  remote in your clone. For example, the command
+ @item{A newly cloned package will have the specified (or existing
+  installation's) repository as its Git @exec{origin}. If you want to
+  push and pull updates from a different repository---for instance,
+  your own fork of the package source---then use @exec{git} commands
+  to add or change the @exec{origin} of your clone to the other
+  repository. For example, the command
 
-  @commandline{git remote set-url origin @nonterm{url}}
+  @commandline{git remote set-url origin @nonterm{url-of-other-repo}}
 
   in the clone's directory causes @exec{git pull} and @exec{git push}
-  to pull and push to the given @nonterm{url}.
+  to pull and push to the given @nonterm{url-of-other-repo}.
+
+  @margin-note{You can preserve the clone's connection to its central
+  repository by setting an @exec{upstream} remote, e.g. @exec{git
+  remote add upstream @nonterm{url-of-central-repo}}. This gives you
+  the option to periodically pull in commits from the central
+  repository with @exec{git pull --ff-only upstream master}.}
 
   Alternatively, use @exec{git} to clone the target @nonterm{url}
   first, and then supply the local clone's path as @nonterm{dir} in