Minor update of getting started documents.
authorMichael Spang <mspang@uwaterloo.ca>
Sun, 28 Jan 2007 11:06:34 +0000 (06:06 -0500)
committerMichael Spang <mspang@uwaterloo.ca>
Sun, 28 Jan 2007 11:06:34 +0000 (06:06 -0500)
docs/GIT-HOWTO
docs/INSTALLING

index eb48d99..0bf0157 100644 (file)
@@ -2,22 +2,23 @@ Getting the Source
 ------------------
 
 The sources for this project are in a git repository. Git is a distributed
-SCM originally created by Linus Torvalds to track the Linux kernel tree.
-There is generally no central repository that everyone commits their changes
-to to with git. It is possible to make such a central repository, but this
-negates many of the advantages of using git. When you check out the sources,
-you will get the entire history along with the latest version. You don't
-need any special permissions (e.g. UNIX group membership) to check the
-sources out and start contributing.
-
-First, you must decide whether you wish to use git or cogito as your
-front-end of choice. For the most part you can use them interchangeably,
-but you will probably want to choose one and stick to it. Cogito will
-provide you with an interface that looks and acts slightly more like CVS and
-Subversion than native git.
+revision control tool originally created by Linus Torvalds to track the Linux
+kernel tree. With git, there is generally no central repository that everyone
+commits their changes to. Instead, collaboration is done by "pulling" changes
+from the repositories of other contributors.
+
+When you check out the sources, you will get the entire history along with
+the latest version. You also don't need any special permissions (e.g. UNIX
+group membership) to clone a repository and start making changes.
+
+To get started, you must first decide whether you wish to use git or cogito
+as your front-end of choice. For the most part you can use them
+interchangeably, but you will probably want to choose one and stick to it.
+Cogito will provide you with an interface that looks and acts slightly more
+like CVS and Subversion than native git does.
 
 In order to get a copy of the sources, you need to clone an existing
-repository. To do this, type something resembling:
+repository. To do this, type a command such as:
 
     git clone /users/git/mspang/csc.git
 
@@ -27,7 +28,7 @@ Or, with cogito:
 
 This will give you the latest copy of my source tree. Once other CSC
 members publish their repositories, you can clone your tree from theirs
-instead if you wish. You do not need to run this command more than
+instead if you so desire. You do not need to run this command more than
 once, and you are not limited to pulling changes from the repository
 you cloned from.
 
@@ -35,15 +36,17 @@ you cloned from.
 Making Changes
 --------------
 
-You may now add, update, or delete files as necessary in your own copy of
-the repository. Go through a tutorial or read the manpages to learn more.
+Now that you have your own repository, you can start making changes. You
+may can add, update, or delete files as necessary and then commit these
+changes to your local repository. Then you can make these changes available
+to others. Read the documentation to learn more about basic git usage.
 
 For a tutorial on plain git, see [1] generally and [2] if you are used to
 CVS. For a tutorial on cogito, see [3] if you are used to CVS and [4] if
 you are used to Subversion.
 
-The manpages for git and cogito commands are also invaluable, use man
-git-foo or man cg-foo to retrieve them or look online at [5] and [6].
+The manpages for git and cogito commands are also invaluable, use `man
+git-foo` or `man cg-foo` to retrieve them, or look online at [5] and [6].
 
 Finally, if you're interested in how git works internally, see [7] for
 documentation of the "core" commands, and [8] for documentation of the
@@ -68,16 +71,15 @@ Systems Committee, since in that case you can't deploy your changes
 yourself. Even if you are a committee member, confusion is sure to follow
 if you install an updated package and don't publish your updates.
 
-The only thing others need to retrieve your changes into their own
-repository is the location of your repository and read access to it.
-With that they can fetch, review, and merge your changes.
+The only thing other people need to fetch your changes into their own
+repository is the location of your repository and read access to it. With
+that they can use `git fetch` or `cg fetch` to retrieve your changes.
 
-If you will be making lots of changes, it may be a good idea to
-put a link to your repository (or even an actual repository) in
-/users/git. To do this you will need to be added to the git group.
-Email systems-committee@csclub.uwaterloo.ca and someone will add you.
-It doesn't matter whether your repository itself is in /users/git or
-just a symlink, as it will count toward your quota regardless.
+If you will be making lots of changes, it may be a good idea to put a link
+to your repository (or even an actual repository) in /users/git. To do this
+you will need to be added to the git group. Email systems-committee and
+someone will add you. It doesn't matter whether your repository itself is
+in /users/git or just a symlink, as it will count toward your quota regardless.
 
 If you will be building and installing the package (i.e. you are the
 Sysadmin or a Systems Committee member) then please do create a public
index 4935787..6fd7f5a 100644 (file)
@@ -2,9 +2,9 @@
                     BUILDING AND INSTALLING
                     -----------------------
 
-This document describes how to get the package built and installed on
-CSC systems. If you don't have authority to do this, you can safely
-skip it (unless you are making changes to the build process).
+This document describes the steps needed to get the package built and
+installed on CSC systems. If you don't have authority to do this, you
+can safely skip it.
 
 If you don't have the required authority, but have a Debian box of your own,
 then note that you have all the tools required to replicate our setup
@@ -16,27 +16,25 @@ Building the Package
 --------------------
 
 To build a Debian package out of the sources, run one of the following
-commands in at the top of the source tree:
+commands at the top of the source tree:
 
     A. debuild
     B. fakeroot dpkg-buildpackage -us -uc
     C. git-buildpackage
 
-It doesn't matter which, so 'debuild' is probably easiest. If all
-goes well, a debian package and source tarball will appear in the
-parent directory.
+It doesn't matter which, so 'debuild' is probably easiest. If all goes well,
+a Debian package and source tarball will appear in the parent directory.
 
-Do NOT build the package as root (rather, don't build anything as root
-in general). This is never necessary. Use 'fakeroot' so that the permissions
-in the .deb can be set correctly. The only exception to this is if you are
-building with pbuilder, which builds the package in a chroot so it doesn't
-matter anyway.
+Do NOT build the package as root (rather, don't build anything as root in
+general). Use 'fakeroot' so that the permissions in the .deb can be set
+correctly. It is only necessary to build as root if you are using pbuilder,
+which builds in a chroot.
 
-You can examine the resulting package with tools like dpkg-deb(1) and
-debdiff(1). One useful command is `dpkg-deb -c <deb-file>`. This will
-give you a list of files that will be installed.
+You can examine the package with tools like dpkg-deb(1) and debdiff(1).
+One useful command is `dpkg-deb -c <deb-file>`. This will give you a list
+of files that will be installed.
 
-If your build is a development build, you can safely destroy it (it will
+If your build is a development build, you can safely delete it (it will
 be overwritten anyway if a subsequent build has the same version number).
 
 
@@ -46,84 +44,88 @@ Installing the Package
 If you will be installing the package it is essential you follow certain
 guidelines in order to avoid overwriting someone else's changes.
 
-I'm assuming you have made your changes and commited them to git. Your last
-test build succeeded and you're ready to install the package. Before you do,
-you need to:
+I'm assuming that you have made your changes and commited them to your
+repository, and that your last test build was successful and you're read to
+install the package. Before you install, you need to:
 
     1. Examine the currently installed package
 
-        Your package should incorporate all of the changes in the one that's
-        installed. Otherwise you may be installing a package that does not
-        include important bug fixes and improvements.
+        Your package should incorporate all of the changes that are in the
+        currently installed package. Otherwise you may be installing a
+        package that does not include important bug fixes and improvements.
 
         Since every release has a changelog entry, you can easily check
-        that your package incorporates all the changes by comparing your
+        that your source tree is up-to-date by comparing your
         debian/changelog with /usr/share/doc/csc/changelog.Debian.gz.
+        The zdiff(1) utility is helpful for doing this comparison.
 
         If your changelog is missing some entries, find the git repository
         of the person who wrote the changelog entry (this will be easy if
         they put a link in /users/git) and pull in their changes. Review
-        the changes while merging, for good measure.
+        the changes and merge them into your tree.
 
     2. Increase the package version number
 
-        Look at the version number of latest entry in debian/changelog. Think
-        of a number that is greater then this number and that reflects the
-        magnitude of your change. Probably, just change last number by one.
+        Look at the version number of latest entry in debian/changelog.
+        Think of a number that is greater than this number and that
+        reflects the magnitude of your change. Generally just increase
+        last number by one.
 
         To set the version number of the next build, run `dch -v <version>`
-        at the top of your source tree. This will create a new changelog entry
-        and open your favorite editor for the next step.
+        at the top of your source tree. This will create a new changelog
+        entry and open your favorite editor for the next step.
 
     3. Write a changelog entry for your update
 
         Step #2 will put you in your favorite text editor. Add some bullets
         that describe all of the changes in the new version. Note that this
-        file follows a set format and must be machine parseable. If in doubt,
+        file follows a set format and must be machine readable. If in doubt,
         run `dpkg-parsechangelog` when you're done to see if it complains.
 
     4. Commit the changelog update to your repository
 
         For your commit message, mention that that this is a new release
-        (include the version number) and copy your summary from the changelog.
+        (include the version number) and copy your summary from the
+        changelog.
 
     5. Build the package
 
         Use 'debuild' or 'fakeroot dpkg-buildpackage -us -uc' to build the
-        package. Do not simply run 'debian/rules binary' as this will create
-        the .deb but not the .tar.gz and .dsc and .changes.
+        package. Do not simply run 'debian/rules binary' as this will
+        create the .deb but not the .tar.gz, .dsc, and .changes.
 
     5. Install the package
 
         You're finally ready to run `dpkg -i csc_<version>_<arch>.deb`. Do
-        this and cross your fingers. Make sure to test ceo a bit to see if it
-        still works. If it doesn't, install the previous version and investigate
-        the problem. You will probably have to make more changes and repeat
-        this whole process.
+        this and cross your fingers. Make sure to test ceo a bit to see if
+        it still works. If it doesn't, install the previous version and
+        investigate the problem. You will probably have to make more
+        changes and repeat this whole process.
 
     6. Archive the package file and source
 
-        You will be left with four files: a *.deb, a *.tar.gz, a *.changes,
-        and a *.dsc. Save these to a safe place (preferably in /users/git
+        You will be left with four files: a .deb, a .tar.gz, a .changes,
+        and a .dsc. Save these to a safe place (preferably in /users/git
         so other can find them easily).
 
-If everyone follows these steps, every installed version will be a descendant
-of the previous. Further, since old versions are archived it will be easy
-to quickly get ceo working after a bad update.
+If everyone follows these steps, every installed version will be a
+descendant of the previous. Further, since old versions are archived it
+will be easy to quickly get ceo working again after a bad update.
 
 For the git skeptics: Yes, a central repository would serialize changes
 automatically, making sure each is a descendant of the previous. The reason
 I don't want to do this is that you have to trust everyone who can commit
 not to break anything. With git any random CSC member can fetch the tree
-and start making changes without any special permissions. Not that CSC members
-are untrustworthy, but in my opinion git lowers the barrier for potential
-contributors by giving them immediate write access to a repository.
+and start making changes without any special permissions. Not that CSC
+members are untrustworthy, but in my opinion git lowers the barrier for
+potential contributors by giving them immediate write access to a
+repository.
 
 
 Old Versions
 ------------
 
-It is desirable that old, known-working build be available to install in
+It is desirable that old, known-working builds be available to install in
 an emergency. So, as described above, please store your release builds in
 an easy to find place.
 
@@ -131,14 +133,12 @@ My (Michael Spang's) builds can be found in /users/git/mspang/csc.builds.
 They are cryptographically signed (with debsign).
 
 Old source tarballs are stored alongside the debs. To extract them, run
-`dpkg-source -x csc_<version>.dsc`. You could use tar, too, but it will
+`dpkg-source -x csc_<version>.dsc`. You can use tar, too, but it will
 not check for corruption and won't verify the signature.
 
 If the current version is broken and you need to install an old version,
 do so, but note that switching between some versions requires changes to
 the configuration files (dpkg will bug you about this). For example,
-the file format changed between versions 0.1 and 0.2. In this case
-just make note of any passwords in the current files, and then overwrite
-the current files with the templates of the version you are installing.
-Then fill in the blanks in the templates (e.g. passwords), and it should
-work.
+these files changed significantly between versions 0.1 and 0.2. In this case
+install the old configuration files and then merge important information
+(e.g. passwords) into them from the .dpkg-old file.