On Sun, 22 Apr 2007 20:39:26 +0100 Neil Williams <codehelp@debian.org> wrote: After reading the responses so far, the -doc element of my original idea needs modification. > I'd like to see all library source packages having a minimum of 4 > binary packages required by Policy: the SONAME, the -dev, the -dbg > and a -doc package. (Libraries for perl or other non-compiled > languages would be exempt from -dbg packages but not -doc.) The -doc is overkill for all packages but I still feel it is important for upstream development that all libraries have at least basic API documentation within Debian, not just somewhere in the Google cache. I think a -dbg package should be mandatory for all libraries that can support it, albeit with an introductory period where it is advisable, recommended then required. I think that all libraries - without exception - must come with some API documentation and the docs should be as complete and as accurate as possible - ideally generated from the source itself. Where such documentation makes a -doc package worthwhile, that should be done but a man (3) page in the -dev would be sufficient in some cases. I would like to see -doc packages - or at least substantive and reliable API documentation - being the norm for all libraries in Debian. As with the -dbg, the 'must' could be introduced as a recommendation prior to being mandatory. The tools exist for all these changes - only the incentive to use the tools is needed. > Things like that make Debian a nicer environment to be upstream, not > just a nice environment to be a DD or user. I'm upstream for many of > my Debian packages and I'd like to think that Debian unstable would > be the distribution of choice for upstream development. I was using Debian for upstream development long before I even considered being a DD. I chose Debian as a development platform for my own reasons and my decision was "not deemed to be wise" in the eyes of some of my upstream colleagues. As the newbie to that particular team, I was under significant pressure to "upgrade to Fedora or SuSE". Debian needs to reclaim the respect of upstream development teams and part of that is making it *a lot* easier to do upstream development on Debian without needing to become a DD as well. Debian is respected as a distribution for users because of the multiple architecture support and the patches and bug reports that are forwarded upstream - what is missing (IMHO) is respect for Debian as the distribution of choice for upstream development itself. > Possible policy amendment: > > "Any library source package capable of building with debug information > (i.e. with -g) must do so. Any such library source package must strip > the debug symbols into separate objects, provide a binary package > librarynamesoversion-dbg containing these separate objects > as /usr/lib/debug/path/to/ELF/object for each /path/to/ELF/object in > the main library package, and reference these separate objects in > a .gnu_debuglink section in the corresponding unstripped object." > (Thanks to Josh Triplett) > > I'd like to add something on -doc to that proposition but haven't > decided how just yet. "All library packages must include at least basic API documentation either in the -dev package or in a dedicated -doc package where sufficient documentation exists. Wherever possible, documentation should cover the entire library API, be generated from the source code of the library and be registered with helper programs like dwww and/or devhelp etc." (subject to being introduced as a recommendation prior to being made mandatory.) What happens now? Would these changes need a GR? Would it be sufficient to generate a bug report against Policy? Or submit these ideas to -policy and take from there? -- Neil Williams ============= http://www.data-freedom.org/ http://www.nosoftwarepatents.com/ http://www.linux.codehelp.co.uk/
Attachment:
pgpCdTy35foQ6.pgp
Description: PGP signature