ドキュメントへの貢献方法

はじめに

このドキュメントでは、ドキュメントに簡単に貢献する方法について説明します。 Tomcat のドキュメント、より具体的にはコネクタのドキュメントについて、誰もが簡単に協力できるように試みます。 これは Windows ユーザーの視点から書かれています。Unix を使用しているユーザーにとっては、これらの手順を適用するのは簡単であるはずです。 必要に応じて、Unix の構文を適宜置き換えてください。

ドキュメントは、xsl スタイルシートを使用した xml を使用して作成されます。 これにより、ドキュメントの内容がスタイルから効果的に分離されるため、貢献者はコンテンツのみを気にする必要があります。 html よりもはるかに簡単です。

すべては非常に簡単です。 必要なものは次のとおりです

  • Ant の最新バージョン
  • Subversion からのコネクタのソースコード
  • 任意の ascii テキストエディタ

ステップバイステップの始め方

これらのツールを入手したら、簡単にセットアップできます。

ステップ 1. Ant の取得

Ant をインストールします。 アドバイスとしては、単純なインストールパスを選択することです。 次に、ANT_HOME の環境変数を設定し、Ant/bin ディレクトリの場所を PATH 変数に追加します。 これを行う方法については、オペレーティングシステムのドキュメントを参照してください。 完了したら、コマンドラインから ant を実行できることを確認します。

Ant は、とりわけドキュメントを構築するために使用され、build.xml というファイルを表示できる必要があります。 このファイルは xdocs ディレクトリにあります。 build.xml ファイルには、ドキュメントのビルドに使用される all という名前のターゲットがあります。

ステップ 2. ソースの取得

tomcat-connectors のソースを git リポジトリから取得します。 git クライアントが必要です。 まだお持ちでない場合は、お好みのクライアントをインストールしてください。

ソースをダウンロードする準備ができました。 リポジトリを置きたい場所にディレクトリを変更します。 簡単にするために、これを GIT_HOME と呼びます。 私のものは C:\build にあります。

次のコマンドを実行して、初めてソースを クローン します。 これは一度だけ実行する必要があります。

C:\build\>git clone https://github.com/apache/tomcat-connectors tomcat-connectors

これで、すべてのダウンロードが表示されます。 マシンにソースが保存されたので、難しい部分は終わりました。 これからは、ソースを更新するには、リポジトリ内の任意のディレクトリに cd し、git pull コマンドを実行するだけです。

ステップ 3. ビルド環境のテスト

コマンドプロンプトウィンドウを開き、ソースをダウンロードしたディレクトリに cd します。 次に、Antbuild.xml ファイルを表示できるように、xdocs ディレクトリに cd します。 次に、コマンドプロンプトから、以下を実行します

C:\build\tomcat-connectors> cd xdocs
C:\build\tomcat-connectors\xdocs> ant all

.

Ant コンパイラのメッセージがすばやくスクロールし、次のメッセージで停止するはずです

[style] Transforming into C:\build\tomcat-connectors\build\docs\news\printer>
[style] Processing C:\build\tomcat-connectors\xdocs\news\20041100.xml 
to
C:\build\tomcat-connectors\build\docs\news/20041100.html
[style] Loading stylesheet C:\build\tomcat-connectors\xdocs\style.xsl
[style] Processing C:\build\tomcat-connectors\xdocs\news\20050101.xml 
to
C:\build\tomcat-connectors\build\docs\news/20050101.html
[style] Processing C:\build\tomcat-connectors\xdocs\news\20060101.xml 
to
C:\build\tomcat-connectors\build\docs\news/20060101.html
[style] Transforming into C:\build\tomcat-connectors\build\docs>
[style] Processing C:\build\tomcat-connectors\xdocs\index.xml 
to
C:\build\tomcat-connectors\build\docs\index.html
[style] Loading stylesheet C:\build\tomcat-connectors\xdocs\style.xsl
 
BUILD SUCCESSFUL
Total time: 10 seconds
C:\build\tomcat-connectors>

xdocs ディレクトリ構造にあるすべての xml ファイルが html に変換され、GIT_HOME\tomcat-connectors\build\docs ディレクトリにコピーされました。 ブラウザで html ファイルの 1 つを開き、どのように表示されるかを確認します。

ステップ 4. 編集プロセス

更新を行うときは、2 つのウィンドウを使用すると簡単です。 1 つを build ウィンドウと呼びます。 これを GIT_HOME\tomcat-connectors\xdocs ディレクトリに保持し、このウィンドウでは次の 2 つのコマンドのみを実行します最初に実行するのは

ant clean
次に実行するのは
ant all

2 番目のウィンドウを edit ウィンドウと呼び、編集、差分、git pull を行っている GIT_HOME\tomcat-connectors\xdocs ディレクトリに保持します。

編集を開始する前に、競合を防ぐために常にローカルリポジトリを更新する必要があります。

C:\build\tomcat-connectors> git pull

リポジトリが最新の状態になったので、編集を開始できます。 編集するドキュメント内の何かを見つけます。 何かを見つけたら、ファイルの名前を覚えておいてください。 edit ウィンドウで、同じ名前の xml ソースファイルを見つけて編集します。 完了したら、build ウィンドウに戻り、GIT_HOME\tomcat-connectors\xdocs ディレクトリで以下を実行します

C:\build\tomcat-connectors\xdocs> ant clean

これにより、以前のすべての html ファイルが削除され、更新された資料の領域が準備されます。 次に、変更を組み込んだ新しいドキュメントを作成するには、以下を実行します

C:\build\tomcat-connectors\xdocs> ant all

ブラウザを使用して、先ほど行った編集を表示します。これらは GIT_HOME\tomcat-connectors\build\docs サブツリーにあります。 問題なく、準備ができたら、パッチを作成して送信するだけです。

ステップ 5. パッチの作成と送信

edit ウィンドウから、作業している xml ファイルを含むディレクトリに cd し、git pull コマンドを実行します。 たとえば、index.xml ファイルの差分を作成して patch.txt と呼ぶには、index.xml ファイルを含むディレクトリに cd し、

C:\build\tomcat-connectors\xdocs\>git diff index.xml >  
patch.txt.

これでパッチが完成し、送信する準備ができました。

ドキュメントへのパッチは、バグレポートと同じように処理されます。 パッチは http://issues.apache.org/bugzilla/ に送信し、適切な 1 行の件名を含める必要があります。 バグデータベースを初めて使用する場合は、http://issues.apache.org/bugzilla/bugwritinghelp.html. を読んでください。 ユーザーアカウントを作成する必要があります。 Web サイトで、パッチを Web フォームに貼り付け、パッチの目的を説明することを忘れないでください。 いずれ、コミット権限を持つ誰かがあなたの提案を確認します。

Web サイトの更新

コミッタのみが Web サイト (https://tomcat.dokyumento.jp/connectors-doc/) を更新できます。 実行するには

  • people.apache.org に接続します。
  • umask 002
  • 変更されたファイルを /www/tomcat.apache.org/connectors-doc/ にコピーします。
  • または、チェックアウトされた tomcat/jk/trunk/xdocs リポジトリから ant を使用します
    ant -Dbuild.dir=/www/tomcat.apache.org -Ddist.name=connectors-doc
  • 変更は数秒以内に tomcat.apache.org に同期されます。

ガイドとリソース