From: W. Trevor King Date: Mon, 10 Jun 2013 16:13:12 +0000 (-0400) Subject: version-control: Make README.md and instructor.md more generic X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=1bdd155b3bbe3c84eb2d7c199c581c913448f200;p=swc-version-control-svn.git version-control: Make README.md and instructor.md more generic 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. --- diff --git a/version-control/README.md b/version-control/README.md index becae9b..4380bdb 100644 --- a/version-control/README.md +++ b/version-control/README.md @@ -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 things` 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. diff --git a/version-control/instructor.md b/version-control/instructor.md index 9fe2757..78f16f0 100644 --- a/version-control/instructor.md +++ b/version-control/instructor.md @@ -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 index 0000000..3131911 --- /dev/null +++ b/version-control/svn/README.md @@ -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 things` 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 index 0000000..45a0b0b --- /dev/null +++ b/version-control/svn/instructor.md @@ -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.