ubuntu-packaging-guide-team team mailing list archive

[Dmitry Shachnev <mitya57@xxxxxxxxx>]

Dmitry Shachnev has proposed merging lp:~mitya57/ubuntu-packaging-guide/patch-headers-and-formatting into lp:ubuntu-packaging-guide.

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

For more details, see:
https://code.launchpad.net/~mitya57/ubuntu-packaging-guide/patch-headers-and-formatting/+merge/167469

This adds two new sections to the article about patches: a section about DEP-3 patch and a section about configuring quilt.

Since I used Docutils field lists there, I also added some theming to make them look better.
-- 
https://code.launchpad.net/~mitya57/ubuntu-packaging-guide/patch-headers-and-formatting/+merge/167469
Your team Ubuntu Packaging Guide Team is requested to review the proposed merge of lp:~mitya57/ubuntu-packaging-guide/patch-headers-and-formatting into lp:ubuntu-packaging-guide.

=== modified file 'debian/changelog'
--- debian/changelog	2013-05-22 15:24:46 +0000
+++ debian/changelog	2013-06-05 08:07:50 +0000
@@ -8,6 +8,9 @@
     - Miscellaneous code improvements and simplifications.
   * debian/scripts/build-list-of-translators: close the <li> tag correctly.
   * po/pt_BR.po: use correct backticks (LP: #1154087).
+  * patches-to-packages.rst: add "Patch Headers" and "Configuring Quilt"
+    sections.
+  * style.css: add styling for Docutils field lists.
 
   [ Daniel Holbach ]
   * add Brazilian Portuguese.

=== modified file 'po/ubuntu-packaging-guide.pot'
--- po/ubuntu-packaging-guide.pot	2013-05-22 16:56:24 +0000
+++ po/ubuntu-packaging-guide.pot	2013-06-05 08:07:50 +0000
@@ -8,7 +8,7 @@
 msgstr ""
 "Project-Id-Version: ubuntu-packaging-guide 0.3.2\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2013-05-22 20:55\n"
+"POT-Creation-Date: 2013-06-05 11:24\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@xxxxxx>\n"
@@ -1897,67 +1897,103 @@
 msgid "As a general rule you should be careful adding patches to programs unless they come from upstream, there is often a good reason why that change has not already been made.  The above example changes a user interface string for example, so it would break all translations.  If in doubt, do ask the upstream author before adding a patch."
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:104
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:105
+msgid "Patch Headers"
+msgstr ""
+
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:107
+msgid "We recommend that you tag every patch with DEP-3_ headers by putting them at the top of patch file. Here are some headers that you can use:"
+msgstr ""
+
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:110
+msgid "Description of what the patch does."
+msgstr ""
+
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:111
+msgid "Who wrote the patch (i.e. \"Jane Doe <packager@xxxxxxxxxxx>\")."
+msgstr ""
+
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:112
+msgid "Where this patch comes from (i.e. \"upstream\"), when *Author* is not present."
+msgstr ""
+
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:114
+msgid "Whether the patch was forwarded upstream. Either \"yes\", \"no\" or \"not-needed\"."
+msgstr ""
+
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:116
+msgid "Date of the last revision (in form \"YYYY-MM-DD\")."
+msgstr ""
+
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:120
 msgid "Upgrading to New Upstream Versions"
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:106
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:122
 msgid "When you upgrade to a new upstream version, patches will often become out of date.  They might need to be refreshed to match the new upstream source or they might need to be removed altogether."
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:110
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:126
 msgid "You should start by ensuring no patches are applied.  Unfortunately a commit is needed before you can merge in the new upstream (this is `bug 815854`_)::"
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:116
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:132
 msgid "Then upgrade to the new version::"
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:120
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:136
 msgid "Then apply the patches one at a time to check for problems::"
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:129
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:145
 msgid "If it can be reverse-applied this means the patch has been applied already by upstream, so we can delete the patch::"
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:135
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:151
 msgid "Then carry on::"
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:140
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:156
 msgid "It is a good idea to run refresh, this will update the patch relative to the changed upstream source::"
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:146
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:162
 msgid "Then commit as usual::"
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:152
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:168
 msgid "Making A Package Use Quilt"
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:154
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:170
 msgid "Modern packages use Quilt by default, it is built into the packaging format.  Check in ``debian/source/format`` to ensure it says ``3.0 (quilt)``."
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:158
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:174
 msgid "Older packages using source format 1.0 will need to explicitly use Quilt, usually by including a makefile into ``debian/rules``."
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:163
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:179
+msgid "Configuring Quilt"
+msgstr ""
+
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:181
+msgid "You can use ``~/.quiltrc`` file to configure quilt. Here are some options that can be useful for using quilt with debian/packages:"
+msgstr ""
+
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:195
 msgid "Other Patch Systems"
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:165
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:197
 msgid "Other patch systems used by packages include ``dpatch`` and ``cdbs simple-patchsys``, these work similarly to Quilt by keeping patches in ``debian/patches`` but have different commands to apply, un-apply or create patches. You can find out which patch system is used by a package by using the ``what-patch`` command (from the ``ubuntu-dev-tools`` package). You can use ``edit-patch``, shown in :ref:`previous chapters <working-on-a-fix>`, as a reliable way to work with all systems."
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:173
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:205
 msgid "In even older packages changes will be included directly to sources and kept in the ``diff.gz`` source file.  This makes it hard to upgrade to new upstream versions or differentiate between patches and is best avoided."
 msgstr ""
 
-#: ../ubuntu-packaging-guide/patches-to-packages.rst:177
+#: ../ubuntu-packaging-guide/patches-to-packages.rst:209
 msgid "Do not change a package's patch system without discussing it with the Debian maintainer or relevant Ubuntu team.  If there is no existing patch system then feel free to add Quilt."
 msgstr ""
 

=== modified file 'themes/ubuntu/static/guide.css'
--- themes/ubuntu/static/guide.css	2012-10-16 12:17:06 +0000
+++ themes/ubuntu/static/guide.css	2013-06-05 08:07:50 +0000
@@ -1,5 +1,5 @@
 /* CSS style bits for Ubuntu developer guide */
-/* Author: Dmitry Shachnev <mitya57@xxxxxxxxx>, 2012 */
+/* Author: Dmitry Shachnev <mitya57@xxxxxxxxxx>, 2012-2013 */
 
 .section li, ul.search li {
     list-style-type: disc;
@@ -47,3 +47,15 @@
 .context {
     margin-left: 30px;
 }
+
+th.field-name {
+    font-weight: bold;
+}
+
+table.field-list {
+    margin-bottom: 10px;
+}
+
+table.field-list td, table.field-list th {
+    padding: 2px;
+}

=== modified file 'ubuntu-packaging-guide/patches-to-packages.rst'
--- ubuntu-packaging-guide/patches-to-packages.rst	2012-11-21 09:38:11 +0000
+++ ubuntu-packaging-guide/patches-to-packages.rst	2013-06-05 08:07:50 +0000
@@ -100,6 +100,22 @@
 example, so it would break all translations.  If in doubt, do ask the upstream
 author before adding a patch.
 
+
+Patch Headers
+-------------
+
+We recommend that you tag every patch with DEP-3_ headers by putting them at the top
+of patch file. Here are some headers that you can use:
+
+:Description: Description of what the patch does.
+:Author:      Who wrote the patch (i.e. "Jane Doe <packager@xxxxxxxxxxx>").
+:Origin:      Where this patch comes from (i.e. "upstream"), when *Author* is
+              not present.
+:Forwarded:   Whether the patch was forwarded upstream. Either "yes", "no" or
+              "not-needed".
+:Last-Update: Date of the last revision (in form "YYYY-MM-DD").
+
+
 Upgrading to New Upstream Versions
 -----------------------------------
 
@@ -159,6 +175,22 @@
 Quilt, usually by including a makefile into ``debian/rules``.
 
 
+Configuring Quilt
+-----------------
+
+You can use ``~/.quiltrc`` file to configure quilt. Here are some options
+that can be useful for using quilt with debian/packages:
+
+.. code-block:: sh
+
+   # Set the patches directory
+   QUILT_PATCHES="debian/patches"
+   # Remove all useless formatting from the patches
+   QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
+   # The same for quilt diff command, and use colored output
+   QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
+
+
 Other Patch Systems
 --------------------
 
@@ -180,3 +212,4 @@
 
 .. _`Quilt`: http://wiki.debian.org/UsingQuilt
 .. _`bug 815854`: https://bugs.launchpad.net/bzr-builddeb/+bug/815854
+.. _DEP-3: http://dep.debian.net/deps/dep3/