ubuntu-packaging-guide-team team mailing list archive

[Daniel Holbach <daniel.holbach@xxxxxxxxxx>]

Daniel Holbach has proposed merging lp:~dholbach/ubuntu-packaging-guide/restructure into lp:ubuntu-packaging-guide.

Requested reviews:
  Ubuntu Packaging Guide Team (ubuntu-packaging-guide-team)

For more details, see:
https://code.launchpad.net/~dholbach/ubuntu-packaging-guide/restructure/+merge/52674

As discussed in the UDD merge: I think it's valuable to have the knowledge base bits in a separate index to make the landing page easier to read, also do I think it's valuable to have brief information on how to test a fix in the "fixing an ubuntu bug" article, so I re-added them there. The rest is untouched.
-- 
https://code.launchpad.net/~dholbach/ubuntu-packaging-guide/restructure/+merge/52674
Your team Ubuntu Packaging Guide Team is requested to review the proposed merge of lp:~dholbach/ubuntu-packaging-guide/restructure into lp:ubuntu-packaging-guide.

=== modified file 'fixing-a-bug.rst'
--- fixing-a-bug.rst	2011-02-07 15:34:46 +0000
+++ fixing-a-bug.rst	2011-03-09 13:05:10 +0000
@@ -115,3 +115,93 @@
 
 Refer to the ``patch(1)`` manpage for options and arguments such as 
 ``--dry-run``, ``-p<num>``, etc.
+
+Testing the fix
+===============
+
+To build a test package with your changes, run these commands::
+
+  $ bzr bd -- -S -us -uc
+  $ pbuilder-dist <release> build ../<package>_<version>.dsc
+
+This will create a source package from the branch contents (``-us -uc`` will
+just omit the step to sign the source package) and ``pbuilder-dist`` will
+build the package from source for whatever ``release`` you choose.
+
+Once the build succeeded, install the package from 
+``~/pbuilder/<release>_result/`` (using ``sudo dpkg -i 
+<package>_<version>.deb``).  Then test to see if the bug is fixed.
+
+
+
+Documenting the fix
+-------------------
+
+It is very important to document your change sufficiently so developers who 
+look at the code in the future won't have to guess what your reasoning was and
+what your assumptions were. Every Debian and Ubuntu package source includes 
+``debian/changelog``, where changes of each uploaded package are tracked.
+
+The easiest way to do this is to run::
+
+  $ dch -i
+
+This will add a boilerplate changelog entry for you and launch an editor 
+where you can fill out the blanks. An example of this could be::
+
+  specialpackage (1.2-3ubuntu4) natty; urgency=low
+
+    * debian/control: updated description to include frobnicator (LP: #123456)
+
+   -- Emma Adams <emma.adams@xxxxxxx>  Sat, 17 Jul 2010 02:53:39 +0200
+
+``dch`` should fill out the first and last line of such a changelog entry for
+you already. Line 1 consists of the source package name, the version number,
+which Ubuntu release it is uploaded to, the urgency (which almost always is 
+'low'). The last line always contains the name, email address and timestamp
+(in :rfc:`5322` format) of the change.
+
+With that out of the way, let's focus on the actual changelog entry itself: 
+it is very important to document:
+
+    #. where the change was done
+    #. what was changed
+    #. where the discussion of the change happened
+
+In our (very sparse) example the last point is covered by ``(LP: #123456)``
+which refers to Launchpad bug 123456. Bug reports or mailing list threads or
+specifications are usually good information to provide as a rationale for a
+change. As a bonus, if you use the ``LP: #<number>`` notation for Launchpad
+bugs, the bug will be automatically closed when the package is uploaded to 
+Ubuntu.
+
+
+Committing the fix
+------------------
+
+With the changelog entry written and saved, you can just run::
+
+  debcommit
+
+and the change will be committed (locally) with your changelog entry as a 
+commit message.
+
+To push it to Launchpad, as the remote branch name, you need to stick to the 
+following nomenclature::
+
+  lp:~<yourlpid>/ubuntu/<release>/<package>/<branchname>
+
+This could for example be::
+
+  lp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456
+
+So if you just run::
+
+  bzr push lp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456
+  bzr lp-open
+
+you should be all set. The push command should push it to Launchpad and the 
+second command will open the Launchpad page of the remote branch in your 
+browser. There find the "(+) Propose for merging" link, click it to get the
+change reviewed by somebody and included in Ubuntu.
+

=== modified file 'index.rst'
--- index.rst	2011-02-05 01:44:04 +0000
+++ index.rst	2011-03-09 13:05:10 +0000
@@ -6,7 +6,11 @@
 Welcome to ubuntu-packaging-guide's documentation!
 ==================================================
 
-Contents:
+The guide is split up into two sections:
+
+* A list of articles based on tasks, so things you want to get done.
+* A set of :doc:`knowledge base</knowledge-base>` articles that dig deeper 
+  into specific bits of our tools and workflows.
 
 .. toctree::
    :maxdepth: 2
@@ -14,15 +18,7 @@
    introduction-to-ubuntu-development
    getting-set-up
    fixing-a-bug
-   udd-intro
-   udd-working
-   udd-sponsorship
-   udd-uploading
-   udd-latest
-   udd-merging
-   udd-patchsys
-   udd-newpackage
-   testing
+   knowledge-base
 
 
 Indices and tables

=== added file 'knowledge-base.rst'
--- knowledge-base.rst	1970-01-01 00:00:00 +0000
+++ knowledge-base.rst	2011-03-09 13:05:10 +0000
@@ -0,0 +1,18 @@
+============================================
+Knowledge base of the Ubuntu Packaging Guide
+============================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   udd-intro
+   udd-working
+   udd-sponsorship
+   udd-uploading
+   udd-latest
+   udd-merging
+   udd-patchsys
+   udd-newpackage
+   testing