On Mon, 23 Apr 2007 16:15:02 -0500 Steve Greenland <[EMAIL PROTECTED]> wrote:
> On 23-Apr-07, 15:51 (CDT), Neil Williams <[EMAIL PROTECTED]> wrote: > > 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. > > That's not a Debian issue. All we can do is include the documentation > provided by upstream. Sure, a DD *can* write docs when they are > missing, but we don't (and shouldn't) require it. Why not? What is wrong with writing a basic man (3) for a library when we already have a requirement for a man (1) for the application? A lack of application documentation makes a system hard for users - we know that so Policy mandates a man (1) for these people whether one exists in the .orig or not, even if it is almost empty. A lack of library documentation makes a system hard for upstream developers - these people are also Debian users and deserve support too. True, they may be more 'advanced' than the average user in terms of their knowledge of C or the autotools - doesn't mean that DD's can assume that they know how a DD would find out the information they need. Upstream generally tries to be as distro-neutral as possible - this can be very difficult with inadequate documentation. It is a Debian issue - it is precisely because the impression has got about that Debian is unfriendly to upstream development that this kind of change is absolutely necessary. The information isn't being made accessible and that results in people thinking you have to know what a DD knows in order to work out what is wrong with the upstream build on your system. These are development builds, not releases - not even snapshots. Things often break and if we want upstream releases that build nicely on Debian, it is good to encourage more upstream developers to use Debian. DD's win in the end - cleaner upstream development builds make for cleaner released .orig builds, meaning less patches! That has to be AGoodThing (tm)! Conversely, a lack of information can result in those upstream developers who choose to use Debian being flamed as a result of that choice because their commits break the build for other distros (another snippet from my pre-DD days!) I can assure you, claiming that your changes haven't broken the build on your Debian system cuts no ice when the change has broken everyone else's build!!! Without the docs, the Debian user is left without the information required to either defend their change or fix the build. Not good. If there is no documentation, file a bug upstream and ask. If the response is RTSL, this should at least be documented in Debian so that users of the -dev know who to blame for the lack of docs. Having a Debian man (3) also provides a focus for contribution of suitable content for the man (3) which in turn could be forwarded upstream. It's easier to add content to an existing man (3) than to create a patch to create a whole one from scratch - especially when the contributors are not necessarily familiar with Debian packaging beyond apt-get. > Is there any case where existing valid distributable documentation is > *not* in the appropriate Debian package? (Not including issues like > the GDL). There is a distinct lack of man (3) and "coordinated" documentation for libraries in Debian. True, some poorly documented packages include test programs or examples somewhere under /usr/share/doc/ but it isn't simple to track these down. At the very least, the Debian maintainer should make it clear where these files are located in a man (3) for the library. Where possible though, a full -doc package is a far, far better option if Debian actually does want to support upstream development on Debian. That's why I stressed the registration of docs with dww and/or devhelp. Some libraries have very, very good docs - libglib2, libgtk2 - the problem comes with the smaller libraries, specialised tasks that are only used by a few applications. By definition, few people will know these API's yet these are often the very libraries that have the least documentation - hence mandatory -doc or man (3). > > 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. > > Huh? Why do upstreams think that they need to be DDs to use Debian? I can only speak from my own experience upstream on this - I wasn't new to Debian at the time but most questions that I asked (or problems that I experienced) came back with a response of "must be something wrong with Debian" because something everyone else did wasn't working for me. I didn't have the documentation available to find out what was wrong and it was very frustrating. In the end, I resorted to a laborious method involving rsync and simultaneous builds on Debian and Fedora prior to commits. That kind of hack can seriously drain ones motivation to continue with upstream development on Debian. Now, as a DD myself, I can see how some of these problems arose. Sometimes, it was something missing on my side, sometimes it was hidden assumptions in the build configuration that were distro-specific and sometimes it was simple version differences. With hindsight, what I needed was some tips from the respective DD's about how libfoo works - aimed at people only really interested in appA which uses libfoo, rather than information intended for those developing libfoo itself. I don't want to have to go through the ChangeLog for libfoo, libbar and libbaz everytime there is an update when what I'm really interested in is upstream development of AppA that may have 30 or 40 dependencies. (Yes, I was part of upstream for GnuCash at the time, how did you guess!) Seeing those changes at the time of the upgrade via apt-listchanges is also less than useful - it could be some time before a commit by someone else breaks the Debian build due to some change in libbaz that hasn't made Fedora yet. What I needed was simple, accessible, documentation of libfoo, libbar and libbaz that described the API, summarised changes, explained deprecated symbols and maybe listed new symbols. This gets all the more important when trying to port the app from, say, Gtk1 to Gtk2. ;-) Debian builds across multiple architectures - upstream has to build across multiple distributions and sometimes the way Debian does things causes problems for builds that are being tested on other distros. e.g. when a library transitions in Debian, it can be difficult to retain a sane build across other distros that have not migrated yet. If the response from the DD is "sorry, not a Debian problem" this is *extremely* unhelpful to an upstream developer trying to defend against flames from developers using other distros when all that is needed is accessible information on what changed. A sensible #ifdef can do the rest. DD's have a wide view of Debian - the tools are second nature and delving into the system is comparatively easy. Upstream developers may be concentrating just on one app and it's major tools but this is difficult enough with a large application. All it needs is for DD's to bring information about libraries closer to the developer of the application using the library. "ReadTheSource,Luke" is singularly unhelpful - whether or not upstream for the library concerned can be bothered to produce their own docs. > Because we discourage non-DD upstreams from distributing crappy > non-conforming .debs alongside their crappy non-conforming .rpms? (Not > that I blame upstreams for having crappy .debs; there's a lot of > policy and a lot of technology to understand - better to let a > specialist take care of it.) True - all the more reason to make it easier to find and use documentation of libraries without having to delve into dpkg -S and dpkg -L and wonder if any of the packaged files might include some help purely on the basis of a filename. It is more about providing the documentation to backup those Debian users who are also upstream developers when problems crop up outside Debian itself. Simple things, like a list of new functions without having to pick out relevant entries from the ChangeLog of someone else's upstream. Noting if the Debian library package differs significantly to the library upstream and why - not somewhere in NEWS.gz or README.gz, but in the one place application developers will look, the API docs. > > "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." > > I'd remove the "generated from the source code" clause. Yes, many > projects choose to do their docs that way. Some don't. Fair enough. As you noted above, as long as the docs are distributable there is no reason to exclude content from the project website etc. > > > > Would these changes need a GR? > > No. > > > Or submit these ideas to -policy and take from there? > > Yes. OK. Let me know what you think of the above and I'll move this to -policy tomorrow/later today. -- Neil Williams ============= http://www.data-freedom.org/ http://www.nosoftwarepatents.com/ http://www.linux.codehelp.co.uk/
pgpqJAl4iCZo1.pgp
Description: PGP signature
