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

Reply via email to