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
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.
-
-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.
+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.
+
+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.
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
--------------------
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,
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.
-
-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:
-
- 1. Examine the currently installed package
-
- 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.
-
- 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.
-
- 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.
+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.
- 2. Increase the package version number
+To install the package:
- 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.
+ 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.
- 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.
+ The changelog on caffeine is in "/usr/share/doc/csc/changelog.gz".
- 3. Write a changelog entry for your update
+ 2. Describe your changes in debian/changelog
- 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
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.
projects / public / pyceo-broken.git / commitdiff