diff --git a/docs/GIT-HOWTO b/docs/GIT-HOWTO new file mode 100644 index 0000000..eb48d99 --- /dev/null +++ b/docs/GIT-HOWTO @@ -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 index 0000000..4935787 --- /dev/null +++ b/docs/INSTALLING @@ -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 `. 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 ` + 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__.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_.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.