Update to GIT-HOWTO and INSTALLING docs
authorMichael Spang <mspang@uwaterloo.ca>
Fri, 4 May 2007 19:10:28 +0000 (15:10 -0400)
committerMichael Spang <mspang@uwaterloo.ca>
Fri, 4 May 2007 19:10:37 +0000 (15:10 -0400)
docs/GIT-HOWTO
docs/INSTALLING

index 0bf0157..ceb739f 100644 (file)
@@ -8,29 +8,17 @@ 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.
+the latest version. You do not need any special permissions 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 a command such as:
+To retrieve the ceo sources, type:
 
     git clone /users/git/mspang/csc.git
 
-Or, with cogito:
-
-    cg clone /users/git/mspang/csc.git
-
-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 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.
+This will give you the latest copy of mspang's source tree. Once cloned,
+the repository is independent from the original and collaboration is done
+by "pulling" changes. There may be other repositories to clone from in the
+future.
 
 
 Making Changes
@@ -41,51 +29,33 @@ 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.
+Git Resources
+-------------
 
-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].
+For a tutorial, see [1] generally and [2] if you are familiar with CVS.
+The manpages for git are also invaluable, use `man git-foo` to view them,
+or look online at [3].
 
-Finally, if you're interested in how git works internally, see [7] for
-documentation of the "core" commands, and [8] for documentation of the
-repository format. 
+Finally, if you're interested in how git works internally, see [4] for
+documentation of the "core" commands, and [5] for documentation of the
+repository format.
 
 [1] http://www.kernel.org/pub/software/scm/git/docs/tutorial.html
 [2] http://www.kernel.org/pub/software/scm/git/docs/cvs-migration.html
-[3] http://git.or.cz/course/cvs.html
-[4] http://git.or.cz/course/svn.html
-[5] http://www.kernel.org/pub/software/scm/git/docs/
-[6] http://www.kernel.org/pub/software/scm/cogito/docs/
-[7] http://www.kernel.org/pub/software/scm/git/docs/core-tutorial.html
-[8] http://www.kernel.org/pub/software/scm/git/docs/repository-layout.html
+[3] http://www.kernel.org/pub/software/scm/git/docs/
+[4] http://www.kernel.org/pub/software/scm/git/docs/core-tutorial.html
+[5] http://www.kernel.org/pub/software/scm/git/docs/repository-layout.html
 
 
 Setting up a Public Repository
 ------------------------------
 
 If you make changes, you will probably want to share them with the other
-contributors. This is especially true if you are not on the CSC
-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 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 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
-repository in /users/git so the next person who installs can incorporate
-all of your changes.
-
-If you want to make changes but not publish them immediately after
-each commit, create a second repository and "push" your changes
-into your public repository. Refer to the Internet for more details.
+contributors. 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 pull` to fetch and merge your changes.
+
+If you want to make changes but not publish them immediately after each
+commit, create a second "public" repository and use "git push" when you
+are ready to make your changes public. Refer to the Internet for more
+details.
index 6fd7f5a..53068b2 100644 (file)
@@ -6,12 +6,6 @@ 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
-on your own system for testing. Of course, if you are capable of doing
-so, you should probably be on the Systems Committee anyway.
-
-
 Building the Package
 --------------------
 
@@ -19,7 +13,7 @@ To build a Debian package out of the sources, run one of the following
 commands at the top of the source tree:
 
     A. debuild
-    B. fakeroot dpkg-buildpackage -us -uc
+    B. dpkg-buildpackage -rfakeroot
     C. git-buildpackage
 
 It doesn't matter which, so 'debuild' is probably easiest. If all goes well,
@@ -36,71 +30,43 @@ of files that will be installed.
 
 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).
+Otherwise copy it to a safe place.
 
 
 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 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 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 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 and merge them into your tree.
+So you have made your changes and have committed them to your repository, your
+last test build was successful, and you're ready to install the package.
 
-    2. Increase the package version number
+To install the package:
 
-        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.
+    1. Compare your debian/changelog with the changelog from the currently
+       installed package. If your changelog has entries missing, find and
+       merge them with git. This will ensure you do not overwrite others'
+       changes.
 
-        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.
+       The changelog on caffeine is in "/usr/share/doc/csc/changelog.gz".
 
-    3. Write a changelog entry for your update
+    2. Describe your changes in debian/changelog
 
-        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 readable. If in doubt,
-        run `dpkg-parsechangelog` when you're done to see if it complains.
+        Run "dch -v new_version" and add bullets to describe all changes
+        in the new version. Note that this format must be readable by
+        dpkg-parsechangelog.
 
     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.
+        You might want to mention that you are installing the package
+        (i.e. it's a "release") in the commit message.
 
     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, .dsc, and .changes.
+        package.
 
     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.
+        Run `dpkg -i csc_<version>_<arch>.deb`.
 
     6. Archive the package file and source
 
@@ -111,34 +77,3 @@ install the package. Before you install, you need to:
 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.
-
-
-Old Versions
-------------
-
-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.
-
-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 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,
-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.