Added GIT-HOWTO and INSTALLING docs.
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.
This commit is contained in:
parent
58bf72726a
commit
c372e60764
|
@ -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.
|
|
@ -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.
|
Loading…
Reference in New Issue