FreeBSD Documentation Project: Submitting documentation
I have written some documentation. How do I submit it?
First, thank you for taking the time to do this.
You should make your documentation available for review. If you can, put it on an FTP site or a website.
Then post a message to the FreeBSD-doc mailing list, with a brief outline of the documentation and the pointer to its location, and solicit feedback.
If, for some reason, you cannot put the documentation up for FTP or on a web site somewhere you can send it directly to the FreeBSD-doc mailing list. If you do this, please only send plain-text documents.
You should probably cc: this request for comments to other appropriate mailing lists. For example, something that relates to how to use CVSup to keep your source tree up to date would be of interest to the subscribers of the FreeBSD-current and FreeBSD-stable mailing lists.
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.
To do this, wrap it up into a tar file. If your documentation consists of three files, one, two, and three, and you want it all to go into doc.tar, do
% tar cf doc.tar one two three
which does just that. Then compress the tar file,
% gzip -9 doc.tar
which will produce doc.tar.gz.
Finally, encode the file so that it will not be mangled by any email programs.
% uuencode doc.tar.gz doc.tar.gz > doc.uue
You should then let the Documentation Project know about it. The correct way to do this is to use a command called send-pr, which should be installed on your machine. The WWW problem report form may also be used.
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 can then assign the PR to themselves, and liaise with you on committing the new documentation. For more information, see Writing FreeBSD Problem Reports.
send-pr itself is pretty simple. All it does is send an email with some special formatting to a particular address. When you run send-pr you will be put into your editor (probably vi or emacs) with a template to fill out, and some instructions on how to fill it out.
Make sure the "Category" is set to "docs" and that the "Class" is set to one of "change-request". You should include the .uue file you created earlier in the body of the PR.
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.
I have made some changes to existing documentation, how do I submit them?
Again, thank you for taking the time to do this.
First off, you need to produce a special file called a diff. This diff shows just the changes that you have made. This makes it easier for the person doing the committing to see what you have changed, and means you do not need to spend lots of time explaining what you have changed (although you should still explain why you think the change should be made).
To make a 'diff', you should;
Make a copy of the file you are going to change. If you are changing foo.xml, do
% cp foo.xml foo.xml.oldThen, make your changes to foo.xml
% vi foo.xml ... tap tap tap ... ... test the changes, read them for typos and so on ...Make the diff. The command to do this is
% diff -u foo.xml.old foo.xml > foo.diffThis looks at the difference between the two files, and writes them to the file foo.diff.
You can then send foo.diff back to the project. Send a PR as described earlier, but include the foo.diff file in the body of the PR.
FreeBSD Documentation Project Home