Hi Russ,
First, thanks for your great work on this bug.
On Tue, Jan 01, 2008 at 10:54:06PM -0800, Russ Allbery wrote:
> This is the last Policy bug I had tagged as wording. It started with a
> proposal for a README.source file documenting how to do things with a
> package that uses a non-trivial source format, and then expanded into
> standardizing debian/rules targets for doing various things.
>
> Having reviewed the entire bug thread, I think there are a few
> misconceptions and a few different cases mingled together, so I'm going to
> attempt a summary.
>
> The original concern was being able to unpack a Debian source package and
> immediately start patching it, with a goal of creating a modified source
> package (for local modifications, security fixes, RC bug fixes, or what
> have you).
I think that sums it up quite right, yeah :)
> Among the source package formats in Debian, I know of two possible
> situations:
[...summary of patch systems snipped...]
> Now, I think that everyone (possibly except Marco) agrees with the basic
> idea of providing a README.source file explaining how to deal with a
> package that has a non-trivial source layout. In particular, I think
> someone needs to know how to do all of the following:
>
> 1. Generate the fully patched sources, the sources in the state in which
> they'll be built, so that one can check to see if problems have been
> patched, look at the source, and so forth.
>
> 2. Add a new patch to the build process (including any special techniques
> to use to generate the patch if there's an easier tool than recursive
> diff from an unmodified package and the like).
>
> 3. Remove an existing patch from the build process.
>
> 4. Ideally, explain how to upgrade the package to a new upstream version,
> although this should probably be optional.
>
> However, when we get into standardizing targets, this gets a lot murkier.
> I think the discussion above makes it clear that the only thing that we
> can really address with a target is point 1 above. For all of the
> systems, in the general case of modifications that overlap with existing
> patches, I don't think we can provide targets that do 2. 3 and 4 are
> obviously outside what a target can do.
Yes, that seems correct. I hadn't thought of that problem, actually, but
now that you mention it, I don't think there are ways of making that
easy. In short, as you show, sticking to just adding one or more
optional targets to debian/rules isn't going to cut it.
> Accordingly, I think moving forward with specifying a README.source file
> that explains the above three or four points is something we can reach
> consensus on. I'm not as sure about standardizing a target for 1 (setup,
> unpack, and patch are all currently in use), but I suppose that we could
> standardize on patched. This does raise insta-buggy issues since existing
> packages don't provide that target.
>
> However, I don't think it's going to work to say that after running some
> target, people should be able to make modifications and run
> dpkg-buildpackage and expect to have that work. In each case, it looks
> like there are cases where that isn't going to work, and I don't think
> it's viable to say that those patch systems can't be used.
Makes sense.
> So, finally, I propose the following patch:
>
> --- orig/policy.sgml
> +++ mod/policy.sgml
> @@ -1926,6 +1926,19 @@
> possible is a good idea.
> </p>
> </item>
> +
> + <tag><tt>patched</tt> (optional)</tag>
> + <item>
> + <p>
> + This target performs whatever additional actions are
> + required to make the source ready for editing (unpacking
> + additional upstream archives, applying patches, etc.).
> + It is recommended to be implemented for any package where
> + <tt>dpkg-source -x</tt> does not result in source ready
> + for additional modification. See
> + <ref id="readmesource">.
> + </p>
> + </item>
> </taglist>
>
> <p>
> @@ -2076,6 +2089,50 @@
> the file to the list in <file>debian/files</file>.</p>
> </sect>
>
> + <sect>
> + <heading>Source package handling:
> + <file>debian/README.source</file></heading>
> +
> + <p>
> + If running <prgn>dpkg-source -x</prgn> on a source package
> + doesn't produce the source of the package, ready for editing,
> + and allow one to make changes and run
> + <prng>dpkg-buildpackage</prgn to produce a modified package
---^
Seems you've missed a > there.
> + without taking any additional steps, creating a
> + <file>debian/README.source</file> documentation file is
> + recommended. This file should explain how to do all of the
> + following:
> + <enumlist>
> + <item>Generate the fully patched source, in a form ready for
> + editing, that would be built to create Debian
> + packages. Doing this with a <tt>patched</tt> target in
> + <file>debian/rules</file> is recommended; see
> + <ref id="debianrules">.</item>
> + <item>Modify the source and save those modifications so that
> + they will be applied when building the package.</item>
> + <item>Remove existing source modifications that previously
> + were applied.</item>
> + <item>Optionally, document what steps are necessary to
> + upgrade the Debian source package to a new upstream version,
> + if applicable.</item>
> + </enumlist>
> + This explanation should include specific commands and mention
> + any additional required Debian packages. It should not assume
> + familiarity with any specific Debian packaging system or patch
> + management tools.
> + </p>
> +
> + <p>
> + <file>debian/README.source</file> may also include any other
> + information that would be helpful to someone modifying the
> + source package. Even if the package doesn't fit the above
> + description, maintainers are encouraged to document in a
> + <file>debian/README.source</file> file any source package with a
> + particularly complex or unintuitive source layout or build
> + system (for example, a package that builds the same source
> + multiple times to generate different binary packages).
> + </p>
> + </sect>
> </chapt>
I guess it was obvious from my above comments, but I'll second this
patch (or accept it as a replacement of my original one, or whatever
procedure requires me to do now).
Thanks again,
--
<Lo-lan-do> Home is where you have to wash the dishes.
-- #debian-devel, Freenode, 2004-09-22
Attachment:
signature.asc
Description: Digital signature