Added GIT-HOWTO and INSTALLING docs.
authorMichael Spang <mspang@uwaterloo.ca>
Sun, 28 Jan 2007 06:37:38 +0000 (01:37 -0500)
committerMichael Spang <mspang@uwaterloo.ca>
Sun, 28 Jan 2007 06:37:38 +0000 (01:37 -0500)
These docs are intended to help potential contributors get started.

GIT-HOWTO explains how to set up a new repository. It also suggests several
resources to help users learn git or cogito.

INSTALLING suggests a procedure for coordinating the building and installing
of new versions of the Debian package.

docs/GIT-HOWTO [new file with mode: 0644]
docs/INSTALLING [new file with mode: 0644]

diff --git a/docs/GIT-HOWTO b/docs/GIT-HOWTO
new file mode 100644 (file)
index 0000000..eb48d99
--- /dev/null
@@ -0,0 +1,89 @@
+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.
+
+In order to get a copy of the sources, you need to clone an existing
+repository. To do this, type something resembling:
+
+    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 wish. 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.
+
+
+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.
+
+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].
+
+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. 
+
+[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
+
+
+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 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.
+
+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 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.
diff --git a/docs/INSTALLING b/docs/INSTALLING
new file mode 100644 (file)
index 0000000..4935787
--- /dev/null
@@ -0,0 +1,144 @@
+
+                    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).
+
+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
+--------------------
+
+To build a Debian package out of the sources, run one of the following
+commands in 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.
+
+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.
+
+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.
+
+If your build is a development build, you can safely destroy it (it will
+be overwritten anyway if a subsequent build has the same version number).
+
+
+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:
+
+    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.
+
+        Since every release has a changelog entry, you can easily check
+        that your package incorporates all the changes by comparing your
+        debian/changelog with /usr/share/doc/csc/changelog.Debian.gz.
+
+        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.
+
+    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.
+
+        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.
+
+    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,
+        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.
+
+    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.
+
+    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.
+
+    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
+        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.
+
+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 build 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 could 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.