version-control: Make README.md and instructor.md more generic
authorW. Trevor King <wking@tremily.us>
Mon, 10 Jun 2013 16:13:12 +0000 (12:13 -0400)
committerW. Trevor King <wking@tremily.us>
Wed, 23 Oct 2013 04:04:21 +0000 (21:04 -0700)
Don't assume we're teaching Subversion when explaining why version
control is important or what we expect students to get out of it.  The
Subversion-specific notes are now in the svn subdirectory.

version-control/README.md
version-control/instructor.md
version-control/svn/README.md [new file with mode: 0644]
version-control/svn/instructor.md [new file with mode: 0644]

index becae9b66f08162542821f587fede71d922f246b..4380bdb45073e8c7b3f434c2c15a0938bbce8bff 100644 (file)
@@ -8,12 +8,11 @@ Learning objectives
   information.
 * Check out a working copy of a repository.
 * View the history of changes to a project.
-* Explain why working copies of different projects should not overlap.
 * Add files to a project.
-* Commit changes made to a working copy to a repository.
-* Update a working copy to get changes from the repository.
-* Compare the current state of a working copy to the last update from
-  the repository, and to the current state of the repository.
+* Commit changes made to the working copy.
+* Get changes from an upstream repository.
+* Compare the current state of a working copy to the most recent
+  update from the upstream repository.
 * Explain what "version 123 of `xyz.txt`" actually means.
 
 Key points
@@ -21,39 +20,23 @@ Key points
 
 * Version control is a better way to manage shared files than email or
   shared folders.
-* The master copy is stored in a repository.
-* Nobody ever edits the master directory: instead, each person edits a
-  local working copy.
-* People share changes by committing them to the master or updating
-  their local copy from the master.
+* People share their changes by committing them to public repositories
+  and fetch other's changes by updating their local copy from public
+  repositories.
 * The version control system prevents people from overwriting each
-  other's work by forcing them to merge concurrent changes before
-  committing.
+  other's work by making merges explicit.
 * It also keeps a complete history of changes made to the master so
   that old versions can be recovered reliably.
 * Version control systems work best with text files, but can also
   handle binary files such as images and Word documents.
 * Every repository is identified by a URL.
-* Working copies of different repositories may not overlap.
-* Each changed to the master copy is identified by a unique revision
-  number.
+* Each change to the master copy is identified by a unique revision
+  ID.
 * Revisions identify snapshots of the entire repository, not changes
   to individual files.
 * Each change should be commented to make the history more readable.
 * Commits are transactions: either all changes are successfully
   committed, or none are.
-* The basic workflow for version control is update-change-commit.
-* `svn add <em>things</em>` tells Subversion to start managing
-  particular files or directories.
-* `svn checkout $URL` checks out a working copy of a repository.
-* `svn commit -m "$MESSAGE" $THINGS` sends changes to the repository.
-* `svn diff` compares the current state of a working copy to the state
-  after the most recent update.
-* `svn diff -r HEAD` compares the current state of a working copy to
-  the state of the master copy.
-* `svn history` shows the history of a working copy.
-* `svn status` shows the status of a working copy.
-* `svn update` updates a working copy from the repository.
 
 Merging conflicts
 =================
@@ -64,18 +47,13 @@ Learning objectives
 * Explain what causes conflicts to occur and how to tell when one has
   occurred.
 * Resolve a conflict.
-* Identify the auxiliary files created when a conflict occurs.
 
 Key points
 ----------
 
 * Conflicts must be resolved before a commit can be completed.
-* Subversion puts markers in text files to show regions of conflict.
-* For each conflicted file, Subversion creates auxiliary files
-  containing the common parent, the master version, and the local
-  version.
-* `svn resolve $FILES` tells Subversion that conflicts have been
-  resolved.
+* Most version control systems put markers in text files to show
+  regions of conflict.
 
 Recovering old versions
 =======================
@@ -90,13 +68,9 @@ Learning objectives
 Key points
 ----------
 
-* Old versions of files can be recovered by merging their old state
-  with their current state.
-* Recovering an old version of a file does not erase the intervening
+* Recovering an old version of a file may not erase the intervening
   changes.
 * Use branches to support parallel independent development.
-* `svn revert` undoes local changes to files.
-* `svn merge` merges two revisions of a file.
 
 Setting up a repository
 =======================
@@ -109,7 +83,6 @@ Learning objectives
 Key points
 ----------
 
-* `svnadmin create $NAME` creates a new repository.
 * Repositories can be hosted locally, on local (departmental) servers,
   on hosting services, or on their owners' own domains.
 
@@ -127,9 +100,5 @@ Learning objectives
 Key points
 ----------
 
-* `$Keyword: …$` in a file can be filled in with a property value each
-  time the file is committed.
 * Put version numbers in programs' output to establish provenance for
   data.
-* `svn propset svn:keywords $PROPERTY $FILES` tells Subversion to
-  start filling in property values.
index 9fe2757739cad58af86641a74497ef4d779b4e05..78f16f0d09e74a473b73b96c0ab6790844868572 100644 (file)
@@ -1,25 +1,10 @@
 Version control is the most important practical skill we introduce.
-as the last paragraph of the introduction above says, the workflow
-matters more than the ins and outs of any particular tool.  By the end
-of 90 minutes, the instructor should be able to get learners to chant,
-"Update, edit, merge, commit," in unison, and have them understand
-what those terms mean and why that's a good way to structure their
-working day.
+By the end of 90 minutes, the instructor should be able to get
+learners to fetch upstream updates, make local edits, and submit their
+changes upstream and why that's a good way to structure development.
 
 Provided there aren't network problems, this entire lesson can be
-covered in 90 minutes.  The example at the end showing how to use
-Subversion keywords to track provenance is the "ah ha!" moment for
-many learners.  If time is short, skip the material on recovering old
-versions of files in order to get to this section instead.  (The fact
-that provenance is harder in Git, both mechanically and conceptually,
-is one reason to keep teaching Subversion.)
-
-Prerequisites
--------------
-
-* Basic shell concepts and skills (`ls`, `cd`, `mkdir`, editing
-  files).
-* Basic shell scripting (for the discussion of provenance).
+covered in 90 minutes.
 
 Teaching notes
 --------------
@@ -37,34 +22,9 @@ Teaching notes
   this really has to be the last version" to motivate version control
   as a better way to collaborate and as a better way to back work up.
 
-* Version control is typically taught after the shell, so collect
-  learners' names during that session and create a repository for them
-  to share with their names as both their IDs and their passwords.
-  The easiest way to create the repository is to use a server managed
-  by an ISP such as Dreamhost, or on SourceForge, Google Code, or some
-  other "forge" site, all of which provide web interfaces for
-  repository creation and management.  If your learners are advanced
-  enough to be using SSH, you can instead create it on any server they
-  can access, and connect with the `svn+ssh` protocol instead of
-  HTTPS.
-
-* Be very clear what files learners are to edit and what user IDs they
-  are to use when giving instructions.  It is common for them to edit
-  the instructor's biography, or to use the instructor's user ID and
-  password when committing.  Be equally clear *when* they are to edit
-  things: it's also common for someone to edit the file the instructor
-  is editing and commit changes while the instructor is explaining
-  what's going on, so that a conflict occurs when the instructor comes
-  to commit the file.
-
 * Learners could do most exercises with repositories on their own
   machines, but it's hard for them to see how version control helps
   collaboration unless they're sharing a repository with other
   learners.  In particular, showing learners who changed what using
-  `svn blame` is only compelling if a file has been edited by at least
-  two people.
-
-* If some learners are using Windows, there will inevitably be issues
-  merging files with different line endings.  `svn diff -x -w` is
-  supposed to suppress differences in whitespace, but we have found
-  that it doesn't always work as advertised.
+  `blame` is only compelling if a file has been edited by at least two
+  people.
diff --git a/version-control/svn/README.md b/version-control/svn/README.md
new file mode 100644 (file)
index 0000000..3131911
--- /dev/null
@@ -0,0 +1,77 @@
+In addition to the generic version control objectives and points.
+
+Basic use
+=========
+
+Learning objectives
+-------------------
+
+* Explain why working copies of different projects should not overlap.
+
+Key points
+----------
+
+* The master copy is stored in a repository.
+* Nobody ever edits the master directory: instead, each person edits a
+  local working copy.
+* The basic workflow for version control is update-change-commit.
+* `svn add <em>things</em>` tells Subversion to start managing
+  particular files or directories.
+* `svn checkout $URL` checks out a working copy of a repository.
+* `svn commit -m "$MESSAGE" $THINGS` sends changes to the repository.
+* `svn diff` compares the current state of a working copy to the state
+  after the most recent update.
+* `svn diff -r HEAD` compares the current state of a working copy to
+  the state of the master copy.
+* `svn history` shows the history of a working copy.
+* `svn status` shows the status of a working copy.
+* `svn update` updates a working copy from the repository.
+
+Merging conflicts
+=================
+
+Learning objectives
+-------------------
+
+* Identify the auxiliary files created when a conflict occurs.
+
+Key points
+----------
+
+* For each conflicted file, Subversion creates auxiliary files
+  containing the common parent, the master version, and the local
+  version.
+* `svn resolve $FILES` tells Subversion that conflicts have been
+  resolved.
+
+Recovering old versions
+=======================
+
+Key points
+----------
+
+* Old versions of files can be recovered by merging their old state
+  with their current state.
+* Recovering an old version of a file does not erase the intervening
+  changes.
+* `svn revert` undoes local changes to files.
+* `svn merge` merges two revisions of a file.
+
+Setting up a repository
+=======================
+
+Key points
+----------
+
+* `svnadmin create $NAME` creates a new repository.
+
+Provenance
+==========
+
+Key points
+----------
+
+* `$Keyword: …$` in a file can be filled in with a property value each
+  time the file is committed.
+* `svn propset svn:keywords $PROPERTY $FILES` tells Subversion to
+  start filling in property values.
diff --git a/version-control/svn/instructor.md b/version-control/svn/instructor.md
new file mode 100644 (file)
index 0000000..45a0b0b
--- /dev/null
@@ -0,0 +1,36 @@
+In addition to the generic version control notes.
+
+The example at the end showing how to use Subversion keywords to track
+provenance is the "ah ha!" moment for many learners.  If time is
+short, skip the material on recovering old versions of files in order
+to get to this section instead.  (The fact that provenance is harder
+in Git, both mechanically and conceptually, is one reason to keep
+teaching Subversion.)
+
+Teaching notes
+--------------
+
+* Version control is typically taught after the shell, so collect
+  learners' names during that session and create a repository for them
+  to share with their names as both their IDs and their passwords.
+  The easiest way to create the repository is to use a server managed
+  by an ISP such as Dreamhost, or on SourceForge, Google Code, or some
+  other "forge" site, all of which provide web interfaces for
+  repository creation and management.  If your learners are advanced
+  enough to be using SSH, you can instead create it on any server they
+  can access, and connect with the `svn+ssh` protocol instead of
+  HTTPS.
+
+* Be very clear what files learners are to edit and what user IDs they
+  are to use when giving instructions.  It is common for them to edit
+  the instructor's biography, or to use the instructor's user ID and
+  password when committing.  Be equally clear *when* they are to edit
+  things: it's also common for someone to edit the file the instructor
+  is editing and commit changes while the instructor is explaining
+  what's going on, so that a conflict occurs when the instructor comes
+  to commit the file.
+
+* If some learners are using Windows, there will inevitably be issues
+  merging files with different line endings.  `svn diff -x -w` is
+  supposed to suppress differences in whitespace, but we have found
+  that it doesn't always work as advertised.