Handling bug reports explicitly

(Thoughts after a recent mail conversation...)

As a project maintainer, it's helpful to all concerned, but most especially you, if you are as explicit as possible when handling bug reports. In other words, explain to the reporter exactly what you did to fix the problem they reported, and why you did it. (This might be as simple as saying you applied a patch written by the reporter, or showing the patch you wrote and applied, but usually that's not enough.) If you did nothing, explain why. If the report was made by email to a list, then make sure you CC the list with your explanation. If the report was via a bug-reporting facility, then make sure that your explanation goes into the facility.

This helps you because:

• It provides a historical record that will help you remember later what you did and why, and allow others to go back and find that information.
• It encourages your good bug reporters to make future reports, because they can see that their reports make a difference.
• It will help your bad bug reporters make better reports in the future.
• Perhaps most importantly... You'll always make mistakes (misunderstand the report, make the wrong fix, etc.): if you let as many people as possible (the reporter, readers of the mailing list to which the bug report was written, followers of traffic on the bug reporting facility) know as precisely as possible what you did, then you give them all a chance to spot your mistake. I've had (far too) many of my mistakes spotted by others by explicitly explaining what I've done. (People could always find out what you did by hunting down diffs in a source repository, or a tarball, or whatever, but the effort involved means that many people won't do that.)

It helps others because:

• The reporter of the bug knows how their problem got fixed.
• If you are an upstream package maintainer, it will help downstream maintainers know what you did and why.
• If you are a downstream package maintainer, it will help the upstream maintainer know what you did and why, which will help them decide whether to integrate your downstream changes upstream. 

(2012-03-25: Edit to fix a minor wording problem.)

man-pages-3.05 is released

I've uploaded man-pages-3.05 into the release directory (or view the online pages). Notable changes in man-pages-3.05 are:

• A new math_error(7) page describes how to diagnose errors when calling math functions.
• A new matherr(3) page describes the older SVID-specified mechanism for diagnosing errors from math functions.

There are a few other minor changes, but this week's release is indeed smaller than usual. That's because I'm working on pending changes to almost all of the math man pages to improve: the discussion of return values, treatment of special values (+0, -0, infinities, NaN), and error diagnostics; the accuracy of the description of feature test macro requirements; and various other details. Expect a (very) big release next week.

Blick auf die Grünegg, Konolfingen

Capabilities have fully arrived, finally

Linux 2.6.26 is out, which means that a complete Linux capabilities implementation has finally arrived, since we now have:

• The ability to attach capability sets to files (added in 2.6.24), so that a process can acquire capabilities during an execve(2).
• A CAP_SETPCAP capability with the proper semantics (since 2.6.25).
• A per-thread capability bounding set (added in 2.6.25).
• The per-thread securebits flags (added in 2.6.26), which can be used to restrict a thread and its children to a pure capabilities-only environment (i.e., one in which there is no special treatment of UID 0).

All of the details are provided in the recently revised capabilities(7) man page. A couple of other useful places to look for information on capabilities are Serge Hallyn's article, POSIX file capabilities: Parceling the power of root, and Chris Friedhoff's page on capabilities.

(2012-02-20: updated link to Serge Hallyn's article.)

man-pages-3.04 is released

I've uploaded man-pages-3.04 into the release directory (or view the online pages). Notable changes in man-pages-3.04 are:

• A new utimensat(2) page describes the utimensat() system call (new in kernel 2.6.22, fixed in 2.6.26) and the futimens() library function.
• A new end(3) page describes the end, etext, and edata variables.
• The capget(2) page was updated by Andrew Morgan, in line with changes in Linux capabilities in kernels 2.6.24, 2.6.25, and 2.6.26.
• The capabilities(7) page adds discussion of: file capabilities (new in Linux 2.6.24), the per-thread capability bounding set (new in Linux 2.6.25); the changed semantics for CAP_SETPCAP (Linux 2.6.25); per-thread securebits flags (new in Linux 2.6.26); three new capabilities, CAP_MAC_ADMIN, CAP_MAC_OVERRIDE, CAP_SETFCAP (Linux 2.6.25); historical CAP_SETPCAP semantics; the rules governing changes to capability sets; and the rationale for the inheritable set and capability bounding set. There were also many other more minor changes to this page. Thanks to Serge Hallyn for his contributions here.
• The getrusage(2) page adds a description of the RUSAGE_THREAD option, which is new in Linux 2.6.26.
• Many changes were made to the prctl(2) page, including adding documentation of: PR_CAPBSET_READ and PR_CAPBSET_DROP (thanks to Serge Hallyn); PR_GET_TSC and PR_SET_TSC (thanks to Erik Bosman); PR_SET_SECCOMP and PR_GET_SECCOMP; and PR_SET_SECUREBITS and PR_GET_SECUREBITS.
• The proc(5) page adds documentation of /proc/config.gz (new in kernel 2.6); /proc/sys/vm/oom_kill_allocating_task (new in Linux 2.6.24); /proc/sys/vm/oom_dump_tasks (new in Linux 2.6.25); and /proc/sys/vm/panic_on_oom (new in Linux 2.6.18).
• The getopt(3) page adds details on the use of optind for restarting an argument list scan.
• The memchr(3) page adds a description of rawmemchr().
• There were also very many minor content and and minor and major formatting fixes, many of them triggered by the around 70 mailed reports that I received from the Alain Portal, the French translator of man-pages. (Alain also provided dozens of reports that led to fixes in man-pages-3.03.) Thanks Alain!
  

man-pages-3.03 is released

I've uploaded man-pages-3.03 into the release directory (or view the online pages). Notable changes in man-pages-3.03 are:

• A new cpuset(7) page, written by Paul Jackson, describes the cpuset file system, the mechanism introduced in Linux 2.6.12 for confining processes to designated processors and nodes. This enormous page becomes the fourth largest in man-pages. Thanks for a great contribution Paul!


• A new getcpu(2) page, written by Andi Kleen, to document the getcpu(2) system call, introduced in Linux 2.6.19.


• A new sched_getcpu(3) page documents a glibc wrapper for getcpu(2).


• The readdir(3) page adds a description of readdir_r(3), the reentrant analog of readdir(3).


• The signal(7) page adds a section on system call restarting (SA_RESTART), and describes the aberrant Linux behavior whereby a stop signal plus SIGCONT can interrupt some system calls, even if no signal handler has been established.

man-pages-3.02 is released

I've uploaded man-pages-3.02 into the release directory (or view the online pages).

Notable changes in man-pages-3.02 are:

• A new clock_nanosleep(2) page, describing the system call introduced in kernel 2.6.


• A rewritten getgrouplist(3) page, which provides additional information and an example program.


• A new getutmp(3) page documenting the getutmp(3) and getutmpx(3) functions.


• A new gnu_get_libc_version(3) page documenting get_gnu_libc_version(3) and get_gnu_libc_release(3).


• A new sigwait(3) page documenting the sigwait(3) library function.


• A new shm_overview(7) page providing an overview of the POSIX shared memory API.


• Additional information in the sigreturn(2) man page.


• Additions and updates to various pages describing the login accounting APIs, including: a new getutmp(3) page documenting the getutmp(3) and getutmpx(3) functions; and various improvements in the getutent(3) and utmp(5) pages.

2014-05-21: Some typos fixed