public
/
pyceo-broken
11
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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:
Michael Spang 2007-01-28 01:37:38 -05:00
parent 58bf72726a
commit c372e60764
2 changed files with 233 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
docs/GIT-HOWTO Normal file
View File

@ -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.

144
docs/INSTALLING Normal file
View File

@ -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.