blob: 2fdfe7a0b267fba209abf448860318dc6fb5eede [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"https://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8" />
<link rel=stylesheet type="text/css" href="style.css" title="style">
<title>
Patches for man-pages
</title>
</head>
<body>
<!--BEGIN-LINKS-->
<form method="get" action="https://www.google.com/search">
<table border=0 cellpadding=0 cellspacing=0 width="100%">
<tr>
<td align="left">
<font size="-1">
Linux <em>man-pages</em>: &nbsp;
<a href="./index.html">home</a> |
<a href="./contributing.html">contributing</a> |
<a href="./reporting_bugs.html">bugs</a> |
patches |
<a href="./download.html">download</a>
&nbsp; || &nbsp;
<a href="https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git">git</a> |
<a href="https://man7.org/linux/man-pages/index.html">online pages</a></font>
</td>
<td align="right">
<input type="text" name="q" size=10 maxlength=255 value="">
<input type="hidden" name="sitesearch" value="man7.org/linux/man-pages">
<input type="submit" name="sa" value="Search online pages">
</td>
</tr>
</table>
</form>
<!--END-LINKS-->
<h1>Patches for <em>man-pages</em></h1>
<p>
If you know how to fix a problem in a manual page (if not, look
<a href="reporting_bugs.html">here</a>), then send a patch,
and <strong>make sure that you</strong>:
</p>
<ul>
<li>
Put <span class="email">linux-man@vger.kernel.org</span>
into "To:" or "CC:"
(<a href="linux-man-ml.html"><em>no HTML mail please</em></a>),
</li>
<li>
Include the string "[patch]" in the subject line
</li>
<li>
Include either or both comaintainers
(Alejandro Colomar <span class="email">&lt;alx.manpages@gmail.com&gt;</span>
and
Michael Kerrisk <span class="email">&lt;mtk.manpages@gmail.com&gt;</span>)
in "To:" or "CC:".
(Please do <strong>not</strong> CC mtk's
<span class="email">@man7.org</span> email address.)
</li>
</ul>
<p>
<strong>The above is the minimum needed so that someone
might respond to your patch.</strong>
(If you did that, and someone does not respond within a few days,
then ping the mail thread, "replying to all".)
</p>
<p>
<strong>To make your patch even more useful</strong>,
please note the following points:
</p>
<ul>
<li>
<strong>Make sure that the mail has a suitable <em>Subject</em>
line</strong>
(i.e., one that mentions the name(s) of the page(s) being patched).
<!--
Don't put the
<em>man-pages</em>
version in the subject line (it should
already be in the body, and cluttering the subject line with a version
number does not help me when filing messages...).
-->
A suitable subject line might be something like:
<pre>
[patch] shmop.2: Add "(void *)" cast to RETURN VALUE </pre>
</li>
<li>
For nontrivial patches, it is helpful if you add a
<span class="const">Signed-off-by:</span>
tag to certify that you wrote the patch or otherwise have the
right to pass it on as an open-source patch.
Such a tag is added near the end of the commit message, and has the form:
</br>
</br>
<span class="const">Signed-off-by: Firstname Lastname &lt;your-email-address&gt;</span>
</br>
</br>
For details, see the section on the "Developer's Certificate of Origin" in the file
<a href="https://www.kernel.org/doc/Documentation/process/submitting-patches.rst"><span class="pathname">Documentation/process/submitting-patches.rst</span></a>
in the Linux kernel source tree.
Where appropriate, other tags documented in that file, such as
<span class="const">Reported-by:</span>,
<span class="const">Reviewed-by:</span>,
<span class="const">Acked-by:</span>,
and
<span class="const">Suggested-by:</span>
can be added to the patch.
The
<em>man-pages</em> project also uses a
<span class="const">Cowritten-by:</span>
tag with the obvious meaning.
<br>
<br>
</li>
<li>
<strong>PLEASE NOTE</strong>: for <strong>nontrivial patches</strong>,
you can save the maintainers a <em>lot</em> of time by attending
to the following:
<br>
<br>
</li>
<ul>
<li>
<strong>Describe how you obtained the information in your patch</strong>.
For example, was it:
<ul>
<li>
by reading (or writing) the relevant kernel or (g)libc source code?
(please provide a pointer to the relevant code)
</li>
<li>
from a commit message in the kernel or (g)libc
source code repository?
(please provide a commit ID)
</li>
<li>
by writing a test program?
(send it with the patch, but please make sure it is as simple
as possible,
and provide instructions on how to use and/or a demo run)
</li>
<li>
from a standards document?
(please name the standard and quote the relevant text)
</li>
<li>
from other documentation?
(please provide a pointer to that documentation)
</li>
<li>
from a mailing list or online forum?
(please provide a URL if possible)
</li>
</ul>
The more information that you can provide, the easier you make it
for the maintainers and others to review your patch.
<br>
<br>
</li>
<li>
Where relevant, include source code comments that
<strong>cite commit hashes</strong> for relevant kernel or glibc changes:
<pre>
.\" commit <40-character-git-hash></pre>
Doing so can be useful to help verify details of the patch,
or for later historical reference.
<br>
<br>
</li>
<li>
<strong>Please CC relevant developers.</strong>
If your patch documents a substantial feature or change, and you
know which developers added the feature or made the change
that your patch documents, please CC them on the patch;
with luck they may review and fix your patch.
If you don't know who the developers are, you may be
able to discover that information from mailing list archives
or from Git logs or logs in other version control systems.
Obviously, if you are the developer of the feature being documented
in a <em>man-pages</em> patch, please identify yourself as such.
<br>
<br>
</li>
<li>
<strong>Please CC relevant mailing lists</strong>.
If your patch documents a substantial feature or change, please
consider CCing relevant mailing lists on your patch.
With luck, subscribers on the mailing list might review your patch.
Relevant mailing lists may include:
<br>
<br>
<ul>
<li>
<span class="email">linux-kernel@vger.kernel.org</span> for patches to system call pages
</li>
<li>
<span class="email">netdev@vger.kernel.org</span> for patches to pages relating to networking and sockets
</li>
</ul>
<br>
The GNU C library developers
don't consider
<em>man-pages</em> to
be official documentation for the library.
However, if you have a new page for Section 3 or a substantial addition
to one of those pages, you might consider CCing
<span class="email">libc-alpha@sourceware.org</span>;
there are some friendly folk there who may review or comment.
<br>
<br>
</li>
</ul>
<li>
For <strong>trivial patches</strong>,
the project uses a number of keywords that are processed by
scripts that automatically build the release changelogs.
Please employ the following in the patch subject line,
where appropriate:
<br />
<br />
<ul>
<li>
<strong>ffix</strong>: Formatting fix.
</li>
<li>
<strong>wfix</strong>: Minor wording fix.
</li>
<li>
<strong>tfix</strong>: Typo fix.
</li>
<li>
<strong>srcfix</strong>: Change to manual page source that
doesn't affect formatted output.
</li>
</ul>
<br />
Obviously, there's some overlap between the above cases;
just choose the one that you think fits best.
Using this scheme, a patch's subject line might look like:
<pre>
[patch] tcp.7: tfix</pre>
</li>
<li>
<strong>Some general tips</strong> on how to make life easier
for the maintainers:
<br>
<br>
</li>
<ul>
<li>
<strong>Send logically separate patches</strong> (e.g., for unrelated pages,
or for logically separate issues in the same page)
as separate mails.
<br>
<br>
</li>
<li>
<strong>Patches that contain correctly formatted
<em>groff</em> are preferred</strong>.
The basics of
<em>groff</em>
are pretty simple, and you can probably learn as much as you need
by just looking at the source of the page to be patched;
for more information, take a look at the
<span class="man-page"><a href="https://man7.org/linux/man-pages/man7/groff_man.7.html">groff_man(7)</a></span>,
<span class="man-page"><a href="https://man7.org/linux/man-pages/man7/groff_man_style.7.html">groff_man_style(7)</a></span>,
and
<span class="man-page"><a href="https://man7.org/linux/man-pages/man7/man-pages.7.html">man-pages(7)</a></span>
manual pages.
If you are uncertain of
<em>groff</em>,
then send a patch that uses some plain text.
<br>
<br>
</li>
<li>
<strong>Make patches against the latest version of the manual page</strong>.
For information on downloading the latest tarball, or pulling from the
<em>man-pages</em>
<a href="https://git-scm.com/">Git</a> repository, see the
<a href="download.html">download</a> page.
<blockquote>
If the manual page that you want to patch is not in the tarball or
Git repository,
that's because it comes from a package other than <em>man-pages</em>;
in that case, you should look
<a href="man_pages_other.html">here</a>.
</blockquote>
</li>
<li>
<strong>Send patches in
<span class="cmd">diff -u</span>
format</strong>; inline inside the mail message
is usually best.
If you're worried about your mailer breaking the patch,
then send it both inline and as an attachment.
Since the
<em>man-pages</em>
project
uses Git, you may find it useful to employ
<span class="cmd">git-send-email</span>
or
<span class="cmd">git-format-patch</span>.
<br>
<br>
</li>
</ul>
<!--
<li>
If editing a page, and you find one or two white spaces at the end
of an existing line, <strong>don't</strong> bother removing them.
The reason is that in a
<span class="cmd">diff -u</span>
patch this will make it look like there is a
change when in fact nothing has changed.
In most cases, these extra white spaces do no harm,
so just leave them be.
</li>
-->
<li>
Some <strong>things that you don't need to do</strong>:
<br>
<br>
</li>
<ul>
<li>
Don't try to patch the COLOPHON section of a page in
one of the release tarballs. That text is autogenerated
as part of the release process.
<br>
<br>
</li>
<li>
You don't need to update the page timestamp (".TH" line);
the project release scripts do that automatically.
</li>
</ul>
</ul>
<!--BEGIN-STATCOUNTER-->
<!-- SITETRACKING.linux_man-pages -->
<!-- Start of StatCounter Code -->
<script type="text/javascript">
var sc_project=5618989;
var sc_invisible=1;
var sc_partition=60;
var sc_click_stat=1;
var sc_security="4f8507d7";
</script>
<script type="text/javascript"
src="https://www.statcounter.com/counter/counter.js"></script><noscript><div
class="statcounter"><a title="customisable counter"
href="https://www.statcounter.com/free_hit_counter.html"
target="_blank"><img class="statcounter"
src="https://c.statcounter.com/5618989/0/4f8507d7/1/" alt="customisable
counter" ></a></div></noscript>
<!-- End of StatCounter Code -->
<!--END-STATCOUNTER-->
</body>
</html>