Docstring update: documented parameters and exceptions of conf.read().
[public/pyceo-broken.git] / docs / INSTALLING
1
2                     BUILDING AND INSTALLING
3                     -----------------------
4
5 This document describes the steps needed to get the package built and
6 installed on CSC systems. If you don't have authority to do this, you
7 can safely skip it.
8
9 If you don't have the required authority, but have a Debian box of your own,
10 then note that you have all the tools required to replicate our setup
11 on your own system for testing. Of course, if you are capable of doing
12 so, you should probably be on the Systems Committee anyway.
13
14
15 Building the Package
16 --------------------
17
18 To build a Debian package out of the sources, run one of the following
19 commands at the top of the source tree:
20
21     A. debuild
22     B. fakeroot dpkg-buildpackage -us -uc
23     C. git-buildpackage
24
25 It doesn't matter which, so 'debuild' is probably easiest. If all goes well,
26 a Debian package and source tarball will appear in the parent directory.
27
28 Do NOT build the package as root (rather, don't build anything as root in
29 general). Use 'fakeroot' so that the permissions in the .deb can be set
30 correctly. It is only necessary to build as root if you are using pbuilder,
31 which builds in a chroot.
32
33 You can examine the package with tools like dpkg-deb(1) and debdiff(1).
34 One useful command is `dpkg-deb -c <deb-file>`. This will give you a list
35 of files that will be installed.
36
37 If your build is a development build, you can safely delete it (it will
38 be overwritten anyway if a subsequent build has the same version number).
39
40
41 Installing the Package
42 ----------------------
43
44 If you will be installing the package it is essential you follow certain
45 guidelines in order to avoid overwriting someone else's changes.
46
47 I'm assuming that you have made your changes and commited them to your
48 repository, and that your last test build was successful and you're read to
49 install the package. Before you install, you need to:
50
51     1. Examine the currently installed package
52
53         Your package should incorporate all of the changes that are in the
54         currently installed package. Otherwise you may be installing a
55         package that does not include important bug fixes and improvements.
56
57         Since every release has a changelog entry, you can easily check
58         that your source tree is up-to-date by comparing your
59         debian/changelog with /usr/share/doc/csc/changelog.Debian.gz.
60         The zdiff(1) utility is helpful for doing this comparison.
61
62         If your changelog is missing some entries, find the git repository
63         of the person who wrote the changelog entry (this will be easy if
64         they put a link in /users/git) and pull in their changes. Review
65         the changes and merge them into your tree.
66
67     2. Increase the package version number
68
69         Look at the version number of latest entry in debian/changelog.
70         Think of a number that is greater than this number and that
71         reflects the magnitude of your change. Generally just increase
72         last number by one.
73
74         To set the version number of the next build, run `dch -v <version>`
75         at the top of your source tree. This will create a new changelog
76         entry and open your favorite editor for the next step.
77
78     3. Write a changelog entry for your update
79
80         Step #2 will put you in your favorite text editor. Add some bullets
81         that describe all of the changes in the new version. Note that this
82         file follows a set format and must be machine readable. If in doubt,
83         run `dpkg-parsechangelog` when you're done to see if it complains.
84
85     4. Commit the changelog update to your repository
86
87         For your commit message, mention that that this is a new release
88         (include the version number) and copy your summary from the
89         changelog.
90
91     5. Build the package
92
93         Use 'debuild' or 'fakeroot dpkg-buildpackage -us -uc' to build the
94         package. Do not simply run 'debian/rules binary' as this will
95         create the .deb but not the .tar.gz, .dsc, and .changes.
96
97     5. Install the package
98
99         You're finally ready to run `dpkg -i csc_<version>_<arch>.deb`. Do
100         this and cross your fingers. Make sure to test ceo a bit to see if
101         it still works. If it doesn't, install the previous version and
102         investigate the problem. You will probably have to make more
103         changes and repeat this whole process.
104
105     6. Archive the package file and source
106
107         You will be left with four files: a .deb, a .tar.gz, a .changes,
108         and a .dsc. Save these to a safe place (preferably in /users/git
109         so other can find them easily).
110
111 If everyone follows these steps, every installed version will be a
112 descendant of the previous. Further, since old versions are archived it
113 will be easy to quickly get ceo working again after a bad update.
114
115 For the git skeptics: Yes, a central repository would serialize changes
116 automatically, making sure each is a descendant of the previous. The reason
117 I don't want to do this is that you have to trust everyone who can commit
118 not to break anything. With git any random CSC member can fetch the tree
119 and start making changes without any special permissions. Not that CSC
120 members are untrustworthy, but in my opinion git lowers the barrier for
121 potential contributors by giving them immediate write access to a
122 repository.
123
124
125 Old Versions
126 ------------
127
128 It is desirable that old, known-working builds be available to install in
129 an emergency. So, as described above, please store your release builds in
130 an easy to find place.
131
132 My (Michael Spang's) builds can be found in /users/git/mspang/csc.builds.
133 They are cryptographically signed (with debsign).
134
135 Old source tarballs are stored alongside the debs. To extract them, run
136 `dpkg-source -x csc_<version>.dsc`. You can use tar, too, but it will
137 not check for corruption and won't verify the signature.
138
139 If the current version is broken and you need to install an old version,
140 do so, but note that switching between some versions requires changes to
141 the configuration files (dpkg will bug you about this). For example,
142 these files changed significantly between versions 0.1 and 0.2. In this case
143 install the old configuration files and then merge important information
144 (e.g. passwords) into them from the .dpkg-old file.