Minor update of getting started documents.
This commit is contained in:
parent
665080e71a
commit
5b4d603d25
|
@ -2,22 +2,23 @@ Getting the Source
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
The sources for this project are in a git repository. Git is a distributed
|
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.
|
revision control tool originally created by Linus Torvalds to track the Linux
|
||||||
There is generally no central repository that everyone commits their changes
|
kernel tree. With git, there is generally no central repository that everyone
|
||||||
to to with git. It is possible to make such a central repository, but this
|
commits their changes to. Instead, collaboration is done by "pulling" changes
|
||||||
negates many of the advantages of using git. When you check out the sources,
|
from the repositories of other contributors.
|
||||||
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
|
When you check out the sources, you will get the entire history along with
|
||||||
front-end of choice. For the most part you can use them interchangeably,
|
the latest version. You also don't need any special permissions (e.g. UNIX
|
||||||
but you will probably want to choose one and stick to it. Cogito will
|
group membership) to clone a repository and start making changes.
|
||||||
provide you with an interface that looks and acts slightly more like CVS and
|
|
||||||
Subversion than native git.
|
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
|
In order to get a copy of the sources, you need to clone an existing
|
||||||
repository. To do this, type something resembling:
|
repository. To do this, type a command such as:
|
||||||
|
|
||||||
git clone /users/git/mspang/csc.git
|
git clone /users/git/mspang/csc.git
|
||||||
|
|
||||||
|
@ -27,7 +28,7 @@ Or, with cogito:
|
||||||
|
|
||||||
This will give you the latest copy of my source tree. Once other CSC
|
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
|
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
|
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
|
once, and you are not limited to pulling changes from the repository
|
||||||
you cloned from.
|
you cloned from.
|
||||||
|
|
||||||
|
@ -35,15 +36,17 @@ you cloned from.
|
||||||
Making Changes
|
Making Changes
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
You may now add, update, or delete files as necessary in your own copy of
|
Now that you have your own repository, you can start making changes. You
|
||||||
the repository. Go through a tutorial or read the manpages to learn more.
|
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
|
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
|
CVS. For a tutorial on cogito, see [3] if you are used to CVS and [4] if
|
||||||
you are used to Subversion.
|
you are used to Subversion.
|
||||||
|
|
||||||
The manpages for git and cogito commands are also invaluable, use man
|
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].
|
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
|
Finally, if you're interested in how git works internally, see [7] for
|
||||||
documentation of the "core" commands, and [8] for documentation of the
|
documentation of the "core" commands, and [8] for documentation of the
|
||||||
|
@ -68,16 +71,15 @@ 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
|
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.
|
if you install an updated package and don't publish your updates.
|
||||||
|
|
||||||
The only thing others need to retrieve your changes into their own
|
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.
|
repository is the location of your repository and read access to it. With
|
||||||
With that they can fetch, review, and merge your changes.
|
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
|
If you will be making lots of changes, it may be a good idea to put a link
|
||||||
put a link to your repository (or even an actual repository) in
|
to your repository (or even an actual repository) in /users/git. To do this
|
||||||
/users/git. To do this you will need to be added to the git group.
|
you will need to be added to the git group. Email systems-committee and
|
||||||
Email systems-committee@csclub.uwaterloo.ca and someone will add you.
|
someone will add you. It doesn't matter whether your repository itself is
|
||||||
It doesn't matter whether your repository itself is in /users/git or
|
in /users/git or just a symlink, as it will count toward your quota regardless.
|
||||||
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
|
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
|
Sysadmin or a Systems Committee member) then please do create a public
|
||||||
|
|
104
docs/INSTALLING
104
docs/INSTALLING
|
@ -2,9 +2,9 @@
|
||||||
BUILDING AND INSTALLING
|
BUILDING AND INSTALLING
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
This document describes how to get the package built and installed on
|
This document describes the steps needed to get the package built and
|
||||||
CSC systems. If you don't have authority to do this, you can safely
|
installed on CSC systems. If you don't have authority to do this, you
|
||||||
skip it (unless you are making changes to the build process).
|
can safely skip it.
|
||||||
|
|
||||||
If you don't have the required authority, but have a Debian box of your own,
|
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
|
then note that you have all the tools required to replicate our setup
|
||||||
|
@ -16,27 +16,25 @@ Building the Package
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
To build a Debian package out of the sources, run one of the following
|
To build a Debian package out of the sources, run one of the following
|
||||||
commands in at the top of the source tree:
|
commands at the top of the source tree:
|
||||||
|
|
||||||
A. debuild
|
A. debuild
|
||||||
B. fakeroot dpkg-buildpackage -us -uc
|
B. fakeroot dpkg-buildpackage -us -uc
|
||||||
C. git-buildpackage
|
C. git-buildpackage
|
||||||
|
|
||||||
It doesn't matter which, so 'debuild' is probably easiest. If all
|
It doesn't matter which, so 'debuild' is probably easiest. If all goes well,
|
||||||
goes well, a debian package and source tarball will appear in the
|
a Debian package and source tarball will appear in the parent directory.
|
||||||
parent directory.
|
|
||||||
|
|
||||||
Do NOT build the package as root (rather, don't build anything as root
|
Do NOT build the package as root (rather, don't build anything as root in
|
||||||
in general). This is never necessary. Use 'fakeroot' so that the permissions
|
general). Use 'fakeroot' so that the permissions in the .deb can be set
|
||||||
in the .deb can be set correctly. The only exception to this is if you are
|
correctly. It is only necessary to build as root if you are using pbuilder,
|
||||||
building with pbuilder, which builds the package in a chroot so it doesn't
|
which builds in a chroot.
|
||||||
matter anyway.
|
|
||||||
|
|
||||||
You can examine the resulting package with tools like dpkg-deb(1) and
|
You can examine the package with tools like dpkg-deb(1) and debdiff(1).
|
||||||
debdiff(1). One useful command is `dpkg-deb -c <deb-file>`. This will
|
One useful command is `dpkg-deb -c <deb-file>`. This will give you a list
|
||||||
give you a list of files that will be installed.
|
of files that will be installed.
|
||||||
|
|
||||||
If your build is a development build, you can safely destroy it (it will
|
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).
|
be overwritten anyway if a subsequent build has the same version number).
|
||||||
|
|
||||||
|
|
||||||
|
@ -46,84 +44,88 @@ Installing the Package
|
||||||
If you will be installing the package it is essential you follow certain
|
If you will be installing the package it is essential you follow certain
|
||||||
guidelines in order to avoid overwriting someone else's changes.
|
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
|
I'm assuming that you have made your changes and commited them to your
|
||||||
test build succeeded and you're ready to install the package. Before you do,
|
repository, and that your last test build was successful and you're read to
|
||||||
you need to:
|
install the package. Before you install, you need to:
|
||||||
|
|
||||||
1. Examine the currently installed package
|
1. Examine the currently installed package
|
||||||
|
|
||||||
Your package should incorporate all of the changes in the one that's
|
Your package should incorporate all of the changes that are in the
|
||||||
installed. Otherwise you may be installing a package that does not
|
currently installed package. Otherwise you may be installing a
|
||||||
include important bug fixes and improvements.
|
package that does not include important bug fixes and improvements.
|
||||||
|
|
||||||
Since every release has a changelog entry, you can easily check
|
Since every release has a changelog entry, you can easily check
|
||||||
that your package incorporates all the changes by comparing your
|
that your source tree is up-to-date by comparing your
|
||||||
debian/changelog with /usr/share/doc/csc/changelog.Debian.gz.
|
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
|
If your changelog is missing some entries, find the git repository
|
||||||
of the person who wrote the changelog entry (this will be easy if
|
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
|
they put a link in /users/git) and pull in their changes. Review
|
||||||
the changes while merging, for good measure.
|
the changes and merge them into your tree.
|
||||||
|
|
||||||
2. Increase the package version number
|
2. Increase the package version number
|
||||||
|
|
||||||
Look at the version number of latest entry in debian/changelog. Think
|
Look at the version number of latest entry in debian/changelog.
|
||||||
of a number that is greater then this number and that reflects the
|
Think of a number that is greater than this number and that
|
||||||
magnitude of your change. Probably, just change last number by one.
|
reflects the magnitude of your change. Generally just increase
|
||||||
|
last number by one.
|
||||||
|
|
||||||
To set the version number of the next build, run `dch -v <version>`
|
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
|
at the top of your source tree. This will create a new changelog
|
||||||
and open your favorite editor for the next step.
|
entry and open your favorite editor for the next step.
|
||||||
|
|
||||||
3. Write a changelog entry for your update
|
3. Write a changelog entry for your update
|
||||||
|
|
||||||
Step #2 will put you in your favorite text editor. Add some bullets
|
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
|
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,
|
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 `dpkg-parsechangelog` when you're done to see if it complains.
|
||||||
|
|
||||||
4. Commit the changelog update to your repository
|
4. Commit the changelog update to your repository
|
||||||
|
|
||||||
For your commit message, mention that that this is a new release
|
For your commit message, mention that that this is a new release
|
||||||
(include the version number) and copy your summary from the changelog.
|
(include the version number) and copy your summary from the
|
||||||
|
changelog.
|
||||||
|
|
||||||
5. Build the package
|
5. Build the package
|
||||||
|
|
||||||
Use 'debuild' or 'fakeroot dpkg-buildpackage -us -uc' to build the
|
Use 'debuild' or 'fakeroot dpkg-buildpackage -us -uc' to build the
|
||||||
package. Do not simply run 'debian/rules binary' as this will create
|
package. Do not simply run 'debian/rules binary' as this will
|
||||||
the .deb but not the .tar.gz and .dsc and .changes.
|
create the .deb but not the .tar.gz, .dsc, and .changes.
|
||||||
|
|
||||||
5. Install the package
|
5. Install the package
|
||||||
|
|
||||||
You're finally ready to run `dpkg -i csc_<version>_<arch>.deb`. Do
|
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
|
this and cross your fingers. Make sure to test ceo a bit to see if
|
||||||
still works. If it doesn't, install the previous version and investigate
|
it still works. If it doesn't, install the previous version and
|
||||||
the problem. You will probably have to make more changes and repeat
|
investigate the problem. You will probably have to make more
|
||||||
this whole process.
|
changes and repeat this whole process.
|
||||||
|
|
||||||
6. Archive the package file and source
|
6. Archive the package file and source
|
||||||
|
|
||||||
You will be left with four files: a *.deb, a *.tar.gz, a *.changes,
|
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
|
and a .dsc. Save these to a safe place (preferably in /users/git
|
||||||
so other can find them easily).
|
so other can find them easily).
|
||||||
|
|
||||||
If everyone follows these steps, every installed version will be a descendant
|
If everyone follows these steps, every installed version will be a
|
||||||
of the previous. Further, since old versions are archived it will be easy
|
descendant of the previous. Further, since old versions are archived it
|
||||||
to quickly get ceo working after a bad update.
|
will be easy to quickly get ceo working again after a bad update.
|
||||||
|
|
||||||
For the git skeptics: Yes, a central repository would serialize changes
|
For the git skeptics: Yes, a central repository would serialize changes
|
||||||
automatically, making sure each is a descendant of the previous. The reason
|
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
|
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
|
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
|
and start making changes without any special permissions. Not that CSC
|
||||||
are untrustworthy, but in my opinion git lowers the barrier for potential
|
members are untrustworthy, but in my opinion git lowers the barrier for
|
||||||
contributors by giving them immediate write access to a repository.
|
potential contributors by giving them immediate write access to a
|
||||||
|
repository.
|
||||||
|
|
||||||
|
|
||||||
Old Versions
|
Old Versions
|
||||||
------------
|
------------
|
||||||
|
|
||||||
It is desirable that old, known-working build be available to install in
|
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 emergency. So, as described above, please store your release builds in
|
||||||
an easy to find place.
|
an easy to find place.
|
||||||
|
|
||||||
|
@ -131,14 +133,12 @@ My (Michael Spang's) builds can be found in /users/git/mspang/csc.builds.
|
||||||
They are cryptographically signed (with debsign).
|
They are cryptographically signed (with debsign).
|
||||||
|
|
||||||
Old source tarballs are stored alongside the debs. To extract them, run
|
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
|
`dpkg-source -x csc_<version>.dsc`. You can use tar, too, but it will
|
||||||
not check for corruption and won't verify the signature.
|
not check for corruption and won't verify the signature.
|
||||||
|
|
||||||
If the current version is broken and you need to install an old version,
|
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
|
do so, but note that switching between some versions requires changes to
|
||||||
the configuration files (dpkg will bug you about this). For example,
|
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
|
these files changed significantly between versions 0.1 and 0.2. In this case
|
||||||
just make note of any passwords in the current files, and then overwrite
|
install the old configuration files and then merge important information
|
||||||
the current files with the templates of the version you are installing.
|
(e.g. passwords) into them from the .dpkg-old file.
|
||||||
Then fill in the blanks in the templates (e.g. passwords), and it should
|
|
||||||
work.
|
|
||||||
|
|
Loading…
Reference in New Issue