os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update the "How do I submit documentation changes" for Bugzilla, and

Browse source 
more generally for the 21st century.
This commit is contained in:
Gavin Atkinson 2014-08-07 12:56:37 +00:00
parent 5d1911645d
commit e8375f83b3
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=45415
1 changed files with 15 additions and 48 deletions

63
en_US.ISO8859-1/htdocs/docproj/submitting.xml
View file

@ -19,53 +19,29 @@
<p>First, thank you for taking the time to do this.</p>
<p>You should make your documentation available for review. If you can,
put it on an FTP site or a website.</p>
upload it to a website somewhere.</p>
<p>Then post a message to the <tt>FreeBSD-doc</tt> mailing list, with a brief outline of
the documentation and the pointer to its location, and solicit
feedback.</p>
<p>If, for some reason, you cannot put the documentation up for FTP or on
<p>If, for some reason, you cannot put the documentation on
a website somewhere you can send it directly to the <tt>FreeBSD-doc</tt> mailing list.
If you do this, please only send plain-text documents.</p>
<p>You should probably cc: this request for comments to other appropriate
mailing lists. For example, something that relates to how to use SVN to
<p>You may wish to cc: this request for comments to another appropriate
mailing list. For example, something that relates to how to use SVN to
keep your source tree up to date would be of interest to the subscribers
of the <tt>FreeBSD-current</tt> and <tt>FreeBSD-stable</tt> mailing
lists.</p>
of the <tt>FreeBSD-stable</tt> mailing list. Please only cc: at most
one other mailing list.</p>
<p>After people have looked over your documentation, and you have had
the chance to incorporate any of their suggestions, you are ready
to submit it.</p>
<p>To do this, wrap it up into a tar file. If your documentation consists
of three files, <tt>one</tt>, <tt>two</tt>, and <tt>three</tt>, and you want it
all to go into <tt>doc.tar</tt>, do</p>
<pre>
% <b>tar cf doc.tar one two three</b>
</pre>
<p>which does just that. Then compress the tar file,</p>
<pre>
% <b>gzip -9 doc.tar</b>
</pre>
<p>which will produce <tt>doc.tar.gz</tt>.</p>
<p>Finally, encode the file so that it will not be mangled by any email
programs.</p>
<pre>
% <b>uuencode doc.tar.gz doc.tar.gz > doc.uue</b>
</pre>
<p>You should then let the Documentation Project know about it. The
correct way to do this is to use a command called <b>send-pr</b>, which
should be installed on your machine.
The <a href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi">WWW problem report form</a> may also be used.</p>
<p>The correct way to do this is to open a Problem Report. Instructions
for doing this can be found at
<a href="https://www.FreeBSD.org/support/bugreports.html">https://www.FreeBSD.org/support/bugreports.html</a>.</p>
<p>You do this so that your submission can be tracked. When you submit a PR
(Problem Report) it is assigned a unique number. One of the committers
@ -74,20 +50,11 @@
For more information, see
<a href="&url.articles;/problem-reports/">Writing FreeBSD Problem Reports</a>.</p>
<p><b>send-pr</b> itself is pretty simple. All it does is send an email
with some special formatting to a particular address. When you run
<b>send-pr</b> you will be put into your editor (probably <b>vi</b> or
<b>emacs</b>) with a template to fill out, and some instructions on how
to fill it out.</p>
<p>Make sure the "Category" is set to "docs" and that the "Class" is set
to one of "change-request". You should include the <tt>.uue</tt> file
you created earlier in the body of the PR.</p>
<p>When you come out of the editor the PR will be sent as an email to the
right place. You will get a notification message shortly afterwards
telling you what number your PR has been given, and this number can
be used to track its progress.</p>
<p>Make sure the "Product" is set to "Documentation" and that the
"Component" is set to either "Documentation" or "Website" as
appropriate. You should attach your files from earlier to the PR.
Please also provide links to the mailing list posts where your changes
were discussed, if appropriate.</p>
<h2>I have made some changes to existing documentation, how do I submit
them?</h2>
@ -131,7 +98,7 @@
</ol>
<p>You can then send <tt>foo.diff</tt> back to the project. Send a PR as
described earlier, but include the <tt>foo.diff</tt> file in the body of the
described earlier, and attach the <tt>foo.diff</tt> file to the
PR.</p>
<p></p><a href="docproj.html">FreeBSD Documentation Project Home</a>