[Pkg-bazaar-commits] r187 ./bzr-builddeb/trunk: * Many documentation fixes from dAniel hAhler. Thanks very much.
James Westby
jw+debian at jameswestby.net
Tue Oct 23 21:25:20 UTC 2007
------------------------------------------------------------
revno: 187
committer: James Westby <jw+debian at jameswestby.net>
branch nick: trunk
timestamp: Tue 2007-10-23 22:25:20 +0100
message:
* Many documentation fixes from dAniel hAhler. Thanks very much.
modified:
debian/changelog
doc/user_manual/building.rst
doc/user_manual/configuration.rst
doc/user_manual/export_upstream.rst
doc/user_manual/merge.rst
doc/user_manual/native.rst
doc/user_manual/normal.rst
doc/user_manual/split.rst
doc/user_manual/upstream_tarballs.rst
-------------- next part --------------
=== modified file 'debian/changelog'
--- a/debian/changelog 2007-10-23 21:06:37 +0000
+++ b/debian/changelog 2007-10-23 21:25:20 +0000
@@ -29,8 +29,9 @@
option. This allows builddeb to find the correct upstream revision based
* Correct the pointer to the user manual in the README. Thanks to Achim
Bohnet for noticing the mistake. (LP: #145019)
+ * Many documentation fixes from dAniel hAhler. Thanks very much.
- -- James Westby <jw+debian at jameswestby.net> Tue, 23 Oct 2007 21:55:02 +0100
+ -- James Westby <jw+debian at jameswestby.net> Tue, 23 Oct 2007 22:24:40 +0100
bzr-builddeb (0.90) unstable; urgency=low
=== modified file 'doc/user_manual/building.rst'
--- a/doc/user_manual/building.rst 2007-09-13 21:56:04 +0000
+++ b/doc/user_manual/building.rst 2007-10-23 21:25:20 +0000
@@ -18,8 +18,8 @@
By default it uses ``dpkg-buildpackage -uc -us -rfakeroot`` to build the
package. If you would prefer to use something else then you can use the
-``--builder`` option to control this. For instance to build in a chroot
-you can run
+``--builder`` option to control this. For instance to build in a pbuilder
+chroot you can run
::
@@ -43,7 +43,7 @@
$ bzr builddeb --quick
-Uses the quick-builder. This command defaults to ``fakeroot debian/rules
+uses the quick-builder. This command defaults to ``fakeroot debian/rules
binary``, but you can set the ``quick-builder`` option in a configuration
file if you wish to customise it.
=== modified file 'doc/user_manual/configuration.rst'
--- a/doc/user_manual/configuration.rst 2007-09-15 13:06:13 +0000
+++ b/doc/user_manual/configuration.rst 2007-10-23 21:25:20 +0000
@@ -29,7 +29,7 @@
The following options are read from the configuration files. Most can also be
used as command line arguments by prepending ``--`` to the names and not using
-the ``\=`` symbol. There are a few exceptions to this that are noted in the
+the ``=`` symbol. There are a few exceptions to this that are noted in the
descriptions.
Directories
@@ -56,12 +56,13 @@
^^^^^
These change the way in which the plugin operates. They can be set depending
-on the type of package you are building.
+on the type of package you are building. If none of these are set then
+`normal mode`_ is used.
* ``merge = True``
- Turns on merge mode. This is where only the ``debian/`` directory is
- versioned. It uses and ``orig.tar.gz`` for the upstream and combines the
+ Turns on `merge mode`_. This is where only the ``debian/`` directory is
+ versioned. It uses an ``orig.tar.gz`` for the upstream and combines the
two before building. It works with both the ``debian/`` directory in the
branch, or the contents of ``debian/`` (e.g. ``rules``, ``control``)
directly in the top level directory of the branch. (Defaults to ``False``).
@@ -72,18 +73,23 @@
option. It will stop the plugin from looking for an ``orig.tar.gz`` and
build a native package instead. This has no effect if merge mode is on,
as I don't think it makes any sense to version the ``debian/`` separately
- for a native package. If you disagree let me know.
+ for a native package. If you disagree let me know. See `native mode`_.
* ``split = True``
This takes a package from a branch that includes both the upstream source
and the ``debian/`` dir and creates a non-native package from it by
creating an ``orig.tar.gz`` from the code outside of ``debian/``. This
- is probably most useful if you are bot upstream and Debian maintainer
+ is probably most useful if you are both upstream and Debian maintainer
of a non-native package. This has no effect if ``merge`` or ``native``
are true, the former is for use when you don't version the full source,
the second for when you don't need an ``orig.tar.gz`` so they make no sense
- to be used together.
+ to be used together. See `split mode`_.
+
+.. _normal mode: normal.html
+.. _merge mode: merge.html
+.. _native mode: native.html
+.. _split mode: split.html
Interaction with an upstream branch
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -97,8 +103,8 @@
This option takes a path (remote or local) to a bzr branch that contains
the upstream code. If this is set then the plugin will export the code
from that branch to create the ``.orig.tar.gz``. This option only has no
- effect if ``native`` of ``split`` is set, and causes any ``orig-dir``
- setting to be ignored.
+ effect if ``native`` or ``split`` is set, and causes any ``orig-dir``
+ setting to be ignored. See `export-upstream mode`.
* ``export-upstream-revision = revision``
@@ -114,7 +120,7 @@
local branch before exporting it. It is your responsibility to setup
the default pull location for the branch. It probably doesn't make too
much sense to use this option with the ``export-upstream-revision`` one
- as this will change the tip, but then wont use it. However this is allowed.
+ as this will change the tip, but then won't use it. However this is allowed.
This option only has an effect if ``export-upstream`` is set. Also note
that this option cannot be used when ``export-upstream`` is set to a
remote branch. [Not a command line option.]
@@ -127,6 +133,8 @@
the ``export-upstream-prepull`` option is true. [Not a command line
option.]
+.. _export-upstream mode: export_upstream.html
+
Builders
^^^^^^^^
@@ -136,21 +144,21 @@
* ``builder = command``
The command to use to build the package. Defaults to ``dpkg-buildpackage
- -rfakeroot -uc -us``). Will only be read from the file in your home
+ -rfakeroot -uc -us``. Will only be read from the file in your home
directory.
* ``quick-builder = command``
The command used to build the package if the ``--quick`` option is used.
(Defaults to ``fakeroot debian/rules binary``). Will only be read from
- the file in your home directory.
+ the config file in your home directory.
* ``source-builder = command``
The command used to build a source package if the ``--short`` or ``-S``
options are used. Overriden if ``--builder`` or ``--quick`` are given on
the command line. (Defaults to ``dpkg-buildpackage -rfakeroot -uc -us
- -S``). Will only be read from the file in your home directory.
+ -S``). Will only be read from the config file in your home directory.
The idea is that certain options can be set in ``.bzr-builddeb/default.conf``
that apply to the package on all systems, or that there is a default that is
@@ -162,5 +170,5 @@
``~/.bazaar/builddeb.conf``. They can override it for the package if they want
(e.g. they have a different location for upstream tarballs of a package if
they are involved with upstream as well, so they set ``orig_dir =
-/home/.../releases/``), this can be done in ``.bzr-builddeb/local.conf``).
+/home/.../releases/``), this can be done in ``.bzr-builddeb/local.conf``.
=== modified file 'doc/user_manual/export_upstream.rst'
--- a/doc/user_manual/export_upstream.rst 2007-09-17 20:46:33 +0000
+++ b/doc/user_manual/export_upstream.rst 2007-10-23 21:25:20 +0000
@@ -36,7 +36,7 @@
``export-upstream`` value. When this value is given then it enables
export-upstream mode. The value that you set for this should be the URI of
the branch that you wish to build against. This can be any URI or path, as
-you would use for ``bzr branch`` say. The second value to set is
+you would use for ``bzr branch``. The second value to set is
``export-upstream-revision``. This is the revision of the upstream branch
that you would like to build the package against. It can be specified in any
format that can be passed to a ``--r`` argument to a Bazaar command. This
@@ -90,7 +90,7 @@
The last step is to adapt the packaging to any changes in the upstream code.
If you are using merge mode then this section in the documentation of
-``merge mode`` may be useful here.
+`merge mode`_ may be useful here.
.. _merge mode: merge.html
=== modified file 'doc/user_manual/merge.rst'
--- a/doc/user_manual/merge.rst 2007-09-16 16:59:59 +0000
+++ b/doc/user_manual/merge.rst 2007-10-23 21:25:20 +0000
@@ -96,7 +96,7 @@
.. _Configuration Files: configuration.html
-One the tarballs are in place then you are ready to build the package. See
+Once the tarballs are in place then you are ready to build the package. See
the `Building the package`_ section for more details on this.
.. _Building the package: building.html
@@ -122,7 +122,7 @@
The last step is to update the packaging. The first part of this is changing
any files to reflect changes in the upstream build, for instance updating
``debian/rules``, or ``debian/install``. The last part is updating any
-patches that have against the upstream code to work against the latest
+patches against the upstream code to work against the latest
version. To make this easier you can use the ``bd-do`` command. This runs
the specified command in an exported directory (so you have the full source
of the package available). If the command is successful then the contents
=== modified file 'doc/user_manual/native.rst'
--- a/doc/user_manual/native.rst 2007-07-10 20:52:45 +0000
+++ b/doc/user_manual/native.rst 2007-10-23 21:25:20 +0000
@@ -4,7 +4,7 @@
Native mode is, unsurprisingly, the mode used for maintaining a native
package. The main difference to normal mode is that an upstream tarball is
not needed. The consequence of this is that most operations, such as
-importing a new upstream are not needed.
+importing a new upstream release are not needed.
Setting up the package
######################
=== modified file 'doc/user_manual/normal.rst'
--- a/doc/user_manual/normal.rst 2007-07-10 21:14:31 +0000
+++ b/doc/user_manual/normal.rst 2007-10-23 21:25:20 +0000
@@ -79,7 +79,7 @@
upstream tarball is named ``scruff-0.1.tar.gz`` and the version number is
``0.1``. As there is not code in the branch yet the plugin does not know
what package you are creating. So you must also supply the package name
-usinf the ``--package`` option. This means that once you have downloaded
+using the ``--package`` option. This means that once you have downloaded
the tarball you should run::
$ cd scruff/
@@ -213,7 +213,7 @@
####################
When a new upstream version is released then the package needs to be updated
-to deal use the new code. To do this, first the new upstream version is
+to use the new code. To do this, first the new upstream version is
imported on top of the last one, as it is a direct descendant of it. Then your
current packaging changes are merged in to the new version, which may cause
conflicts that need to be resolved.
=== modified file 'doc/user_manual/split.rst'
--- a/doc/user_manual/split.rst 2007-07-10 20:52:45 +0000
+++ b/doc/user_manual/split.rst 2007-10-23 21:25:20 +0000
@@ -2,29 +2,31 @@
----------
Split mode is quite a specialised mode. It is for people who are both the
-upstream author and maintainer of a package. It allows you to maintiain both
+upstream author and maintainer of a package. It allows you to maintain both
in a single branch, but have a separation during the build, and not have to
create the upstream tarball by hand.
-.. _normal mode: normal.html
-.. _export-upstream mode: export_upstream.html
-
Some people like this way of working, but it does make it harder for someone
-else to take over maintainance of the package at a later date.
+else to take over maintenance of the package at a later date.
This mode should not be used by those who are not the upstream author of a
package, and who are not making the upstream tarball releases.
This mode is a mixture of most of the other modes. You have the upstream
-code and the packaging in the same branch like normal mode and native mode,
-but the only packaging changes can be in the ``debian/`` directory, like
-merge mode. It also saves you having to manually create an upstream tarball,
-like export-upstream mode.
+code and the packaging in the same branch like `normal mode`_ and
+`native mode`_, but the only packaging changes can be in the ``debian/``
+directory, like `merge mode`_. It also saves you having to manually create
+an upstream tarball, like `export-upstream mode`_.
+
+.. _normal mode: normal.html
+.. _native mode: native.html
+.. _merge mode: merge.html
+.. _export-upstream mode: export_upstream.html
Setting up the package
######################
-Before creating the package you it may be beneficial to set up a shared
+Before creating the package it may be beneficial to set up a shared
repository for the package. Shared in this context means shared between your
branches, rather than shared between users in a public location, the latter
can be done later. To set up a repository then you should run (for a package
=== modified file 'doc/user_manual/upstream_tarballs.rst'
--- a/doc/user_manual/upstream_tarballs.rst 2007-07-10 21:36:23 +0000
+++ b/doc/user_manual/upstream_tarballs.rst 2007-10-23 21:25:20 +0000
@@ -2,7 +2,7 @@
-----------------
When you are building a version of a package that uses a version of the
-upstream package that you have not used in a build before the upstream
+upstream package that you have not used in a build yet the upstream
tarball for that version needs to be fetched from somewhere. It can be
tedious to track the correct file down, download it and rename or repack it
to have the correct name and be in the correct format.
More information about the Pkg-bazaar-commits
mailing list