Update to GIT-HOWTO and INSTALLING docs
This commit is contained in:
Michael Spang
parent
5f8c0656a1
commit
ca33addaf1
|
|
@ -8,29 +8,17 @@ commits their changes to. Instead, collaboration is done by "pulling" changes
|
|||
from the repositories of other contributors.
|
||||
|
||||
When you check out the sources, you will get the entire history along with
|
||||
the latest version. You also don't need any special permissions (e.g. UNIX
|
||||
group membership) to clone a repository and start making changes.
|
||||
the latest version. You do not need any special permissions to clone a
|
||||
repository and start making changes.
|
||||
|
||||
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
|
||||
repository. To do this, type a command such as:
|
||||
To retrieve the ceo sources, type:
|
||||
|
||||
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 so desire. 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.
|
||||
This will give you the latest copy of mspang's source tree. Once cloned,
|
||||
the repository is independent from the original and collaboration is done
|
||||
by "pulling" changes. There may be other repositories to clone from in the
|
||||
future.
|
||||
|
||||
|
||||
Making Changes
|
||||
|
|
@ -41,51 +29,33 @@ 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
|
||||
CVS. For a tutorial on cogito, see [3] if you are used to CVS and [4] if
|
||||
you are used to Subversion.
|
||||
Git Resources
|
||||
-------------
|
||||
|
||||
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].
|
||||
For a tutorial, see [1] generally and [2] if you are familiar with CVS.
|
||||
The manpages for git are also invaluable, use `man git-foo` to view them,
|
||||
or look online at [3].
|
||||
|
||||
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.
|
||||
Finally, if you're interested in how git works internally, see [4] for
|
||||
documentation of the "core" commands, and [5] 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
|
||||
[3] http://www.kernel.org/pub/software/scm/git/docs/
|
||||
[4] http://www.kernel.org/pub/software/scm/git/docs/core-tutorial.html
|
||||
[5] 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.
|
||||
contributors. 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. With that they can use `git pull` to fetch and merge your changes.
|
||||
|
||||
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. With
|
||||
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 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 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.
|
||||
If you want to make changes but not publish them immediately after each
|
||||
commit, create a second "public" repository and use "git push" when you
|
||||
are ready to make your changes public. Refer to the Internet for more
|
||||
details.
|
||||
|
|
|
|||
101
docs/INSTALLING
101
docs/INSTALLING
|
|
@ -6,12 +6,6 @@ This document describes the steps needed to get the package built and
|
|||
installed on CSC systems. If you don't have authority to do this, you
|
||||
can safely skip it.
|
||||
|
||||
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
|
||||
--------------------
|
||||
|
||||
|
|
@ -19,7 +13,7 @@ To build a Debian package out of the sources, run one of the following
|
|||
commands at the top of the source tree:
|
||||
|
||||
A. debuild
|
||||
B. fakeroot dpkg-buildpackage -us -uc
|
||||
B. dpkg-buildpackage -rfakeroot
|
||||
C. git-buildpackage
|
||||
|
||||
It doesn't matter which, so 'debuild' is probably easiest. If all goes well,
|
||||
|
|
@ -36,71 +30,43 @@ of files that will be installed.
|
|||
|
||||
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).
|
||||
Otherwise copy it to a safe place.
|
||||
|
||||
|
||||
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.
|
||||
So you have made your changes and have committed them to your repository, your
|
||||
last test build was successful, and you're ready to install the package.
|
||||
|
||||
I'm assuming that you have made your changes and commited them to your
|
||||
repository, and that your last test build was successful and you're read to
|
||||
install the package. Before you install, you need to:
|
||||
To install the package:
|
||||
|
||||
1. Examine the currently installed package
|
||||
1. Compare your debian/changelog with the changelog from the currently
|
||||
installed package. If your changelog has entries missing, find and
|
||||
merge them with git. This will ensure you do not overwrite others'
|
||||
changes.
|
||||
|
||||
Your package should incorporate all of the changes that are in the
|
||||
currently installed package. Otherwise you may be installing a
|
||||
package that does not include important bug fixes and improvements.
|
||||
The changelog on caffeine is in "/usr/share/doc/csc/changelog.gz".
|
||||
|
||||
Since every release has a changelog entry, you can easily check
|
||||
that your source tree is up-to-date by comparing your
|
||||
debian/changelog with /usr/share/doc/csc/changelog.Debian.gz.
|
||||
The zdiff(1) utility is helpful for doing this comparison.
|
||||
2. Describe your changes in debian/changelog
|
||||
|
||||
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 and merge them into your tree.
|
||||
|
||||
2. Increase the package version number
|
||||
|
||||
Look at the version number of latest entry in debian/changelog.
|
||||
Think of a number that is greater than this number and that
|
||||
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>`
|
||||
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 readable. If in doubt,
|
||||
run `dpkg-parsechangelog` when you're done to see if it complains.
|
||||
Run "dch -v new_version" and add bullets to describe all changes
|
||||
in the new version. Note that this format must be readable by
|
||||
dpkg-parsechangelog.
|
||||
|
||||
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.
|
||||
You might want to mention that you are installing the package
|
||||
(i.e. it's a "release") in the commit message.
|
||||
|
||||
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, .dsc, and .changes.
|
||||
package.
|
||||
|
||||
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.
|
||||
Run `dpkg -i csc_<version>_<arch>.deb`.
|
||||
|
||||
6. Archive the package file and source
|
||||
|
||||
|
|
@ -111,34 +77,3 @@ install the package. Before you install, you need to:
|
|||
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 again 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 builds 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 can 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,
|
||||
these files changed significantly between versions 0.1 and 0.2. In this case
|
||||
install the old configuration files and then merge important information
|
||||
(e.g. passwords) into them from the .dpkg-old file.
|
||||
|
|
|
|||
Loading…
Reference in New Issue