FreeBSD The Power to Serve

FreeBSD ドキュメンテーションプロジェクト: ドキュメントの寄稿

ドキュメンテーションを書きました。どうやって寄稿すれば良いの?

はじめに、 ドキュメンテーションを書く作業に時間を割いてくださったことを感謝します。

レビューのために、ドキュメンテーションを公開する必要があります。 もし可能なら、ドキュメンテーションをどこかのウェブサイトにアップロードしてください。

それから、FreeBSD-doc メーリングリストへドキュメンテーションの概要と公開場所、 コメントの送り先を記したメッセージを投稿してください。

理由があってドキュメントをウェブサイトにおけないときは、 FreeBSD-doc メーリングリストに直接送って頂いても構いません。 その時はプレインテキストでだけお願いします。

そのメッセージを他の適切なメーリングリストに cc: した方がよい場合も多いでしょう。 例えば、そのドキュメンテーションが、 ソースツリーを最新の状態に保つための Subversion の使用法について言及しているなら、 その内容は FreeBSD-stable メーリングリストの講読者にとっても興味あるものでしょう。 cc: は、多くて他の一つのメーリングリストを入れるにとどめてください。

ドキュメンテーションに目が通され、 読者からの提案を組み入れる機会を得たなら、 ドキュメンテーションを寄稿する準備ができたと言えます。

ドキュメンテーションを寄稿する場合、障害報告として提出してください。 障害報告については、 https://www.FreeBSD.org/ja/support/bugreports/ で説明されています。

このコマンドを使うのは、 あなたが寄稿したことを後から確認することができるからです。 PR (Problem Report) を送ると、それぞれに固有な番号が割り当てられます。 その後、Commiter の誰かがその PR を担当し、 新しいドキュメンテーションの commit に関してあなたに連絡することになります。 詳しくは、 FreeBSD 問題報告の書き方を参照してください。

"Product" で "Documentation" を選択し、 "Component" を報告する内容に合わせて "Documentation" もしくは "Website" を選択してください。 PR には、ファイルを添付してください。 もしその変更についてメーリングリストで議論をしていたのであれば、 その投稿へのリンクを加えてください。

既存のドキュメンテーションに変更を加えました。 どうやって寄稿すれば良いの?

繰り返しになりますが、お時間を割いてくださったことを感謝します。

まず最初に、diff と呼ばれる特殊なファイルを生成する必要があります。 この diff は、あなたが施した変更点を正確にあらわしています。 Diff を使えば、commit を行う人は変更点を容易に知ることができ、 したがって、どこを変更したのか説明するのに時間を浪費しなくてすみます (もちろん、 なぜその変更をした方がよいと考えるのかについては説明する必要があるのですが)。

'diff' をつくるには、

  1. 変更するファイルのコピーを作ってください。 もし foo.xml を変更する場合はこうです。

    % cp foo.xml foo.xml.old

  2. それから、foo.xml を変更します。

    % vi foo.xml
... えーと、ここをこうして、こう変えて ...

... 変更点を点検して、誤字がないか確認して、むにゃむにゃむにゃ ...

  3. diff をつくります。それ用のコマンドは以下のようになります。

    % diff -u foo.xml.old foo.xml > foo.diff

    二つのファイルの相違点を調べ、それらを foo.diff へ書き出します。

プロジェクトへ foo.diff を送ります。 上述したように foo.diff ファイルを PR に添付して送ります。

参考文献