%\chapter{Advanced uses of Mercurial Queues}
\chapter{Mercurial Queuesの高度な使い方}
\label{chap:mq-collab}

%While it's easy to pick up straightforward uses of Mercurial Queues,
%use of a little discipline and some of MQ's less frequently used
%capabilities makes it possible to work in complicated development
%environments.

Mercurial Queuesの単純な使い方を取り上げた一方，少々の統制とMQのあまり用
いられない機能を用いることで複雑な開発環境での作業が可能となる．

%In this chapter, I will use as an example a technique I have used to
%manage the development of an Infiniband device driver for the Linux
%kernel.  The driver in question is large (at least as drivers go),
%with 25,000 lines of code spread across 35 source files.  It is
%maintained by a small team of developers.

この章では，Linuxカーネル用Infinibandデバイスドライバの開発を管理するのに
用いたテクニックを例として用いる．このドライバは（ドライバとしては）大規
模で，35のソースファイルにわたる25000行からなる．このソースは小規模な開発
者のチームによって維持管理されている．

%While much of the material in this chapter is specific to Linux, the
%same principles apply to any code base for which you're not the
%primary owner, and upon which you need to do a lot of development.

この章での素材はLinuxに特化しているが，同じ原則はいかなるコードベースに対
しても適用可能で，自分自身で所有していないが，多くの開発を行う必要のある
コードなどにも適用できる．


%\section{The problem of many targets}
\section{ターゲットが複数あるという問題}

%The Linux kernel changes rapidly, and has never been internally
%stable; developers frequently make drastic changes between releases.
%This means that a version of the driver that works well with a
%particular released version of the kernel will not even \emph{compile}
%correctly against, typically, any other version.

Linuxカーネルは急速に変化し，その内部は決して一定ではない．開発者たちは頻
繁にリリース間で劇的な変更を行う．このため，特定のリリースバージョンで良
く動いたドライバが，例えば別のバージョンでは正しくコンパイルすることすら
できなくなるということを意味する．

%To maintain a driver, we have to keep a number of distinct versions of
%Linux in mind.

ドライバを維持するために，開発者はいくつもの別のバージョンのLinuxを想定
しなければならない．
\begin{itemize}
%\item One target is the main Linux kernel development tree.

%  Maintenance of the code is in this case partly shared by other
%  developers in the kernel community, who make ``drive-by''
%  modifications to the driver as they develop and refine kernel
%  subsystems.
\item 一つのターゲットはLinuxカーネルの開発ツリーである．この場合，コード
      の維持管理はカーネルコミュニティの他の開発者（これはカーネルのサブ
      システムを改良するためにドライバを``追い立てる''変更を行う開発者で
      ある）と部分的に共有されている．
%\item We also maintain a number of ``backports'' to older versions of
%  the Linux kernel, to support the needs of customers who are running
%  older Linux distributions that do not incorporate our drivers.  (To
%  \emph{backport} a piece of code is to modify it to work in an older
%  version of its target environment than the version it was developed
%  for.)
\item 開発者は我々のドライバが組み込まれていない古いLinuxディストリビュー
      ションを使っている顧客をサポートするために，古いバージョンのLinuxカー
      ネルへの``バックポート''を抱えている．コードの一部を\emph{バックポー
      ト}することは，ドライバが開発されたバージョンよりも古いバージョン
      の環境で動くようにすることを意味する．
%\item Finally, we make software releases on a schedule that is
%  necessarily not aligned with those used by Linux distributors and
%  kernel developers, so that we can deliver new features to customers
%  without forcing them to upgrade their entire kernels or
%  distributions.
\item 最終的にLinuxディストリビュータやカーネル開発者を待たせることなくス
ケジュール通りにソフトウェアをリリースすることが必要であり，これによって
顧客にカーネルやディストリビューション全体をアップグレードさせることなく
新機能を顧客に届けられる．
\end{itemize}

%\subsection{Tempting approaches that don't work well}
\subsection{やってしまいがちな間違った方法}

%There are two ``standard'' ways to maintain a piece of software that
%has to target many different environments.

さまざまな環境をターゲットにしたソフトウェアを管理する2つの標準的な方法
がある．

%The first is to maintain a number of branches, each intended for a
%single target.  The trouble with this approach is that you must
%maintain iron discipline in the flow of changes between repositories.
%A new feature or bug fix must start life in a ``pristine'' repository,
%then percolate out to every backport repository.  Backport changes are
%more limited in the branches they should propagate to; a backport
%change that is applied to a branch where it doesn't belong will
%probably stop the driver from compiling.

第1の方法は，単一のターゲット向けの複数のブランチを維持することである．こ
の方法の問題点は，リポジトリ間での変更の流れについて厳格な規律を維持しな
ければならないことである．新機能やバグ修正は，きれいな状態のリポジトリで
開始し，バックポートリポジトリに浸透する必要がある．バックポート変更は波
及すべきブランチ内に限定されていなければならない．必要のないブランチへの
バックポートの波及はおそらくドライバをコンパイル不能にしてしまうだろう．

%The second is to maintain a single source tree filled with conditional
%statements that turn chunks of code on or off depending on the
%intended target.  Because these ``ifdefs'' are not allowed in the
%Linux kernel tree, a manual or automatic process must be followed to
%strip them out and yield a clean tree.  A code base maintained in this
%fashion rapidly becomes a rat's nest of conditional blocks that are
%difficult to understand and maintain.

第2の方法は，チャンクやコードを，目的とするターゲット毎にon/offする条件文
を追加した単一のソースツリーを維持する方法である．これらの``ifdef''は
linuxカーネルツリーでは許されていないため，手動または自動でこれらのコード
を除去し，クリーンなツリーを作るプロセスが必要になる．このようなやり方で
管理されたコードベースはすぐに条件節の巣窟と化し、理解や管理の妨げとなる。

%Neither of these approaches is well suited to a situation where you
%don't ``own'' the canonical copy of a source tree.  In the case of a

%Linux driver that is distributed with the standard kernel, Linus's
%tree contains the copy of the code that will be treated by the world
%as canonical.  The upstream version of ``my'' driver can be modified
%by people I don't know, without me even finding out about it until
%after the changes show up in Linus's tree.

あなたが正式なソースツリーを所有しているのでなければ、これらのやり方のど
ちらもそぐわないだろう。標準のlinuxカーネルに同梱されているドライバの場
合，Linusのツリーは世界中で正式なコードとして扱われるコピーを含んでいる．
``私''のドライバの上流版は，知らない人によって変更され得るし，自分の変更
がLinusのツリーに入ったあとでさえも変更され得る．

%These approaches have the added weakness of making it difficult to
%generate well-formed patches to submit upstream.

これらのアプローチは，うまく書かれたパッチを上流へ提出することを困難にし
てしまう．

%In principle, Mercurial Queues seems like a good candidate to manage a
%development scenario such as the above.  While this is indeed the
%case, MQ contains a few added features that make the job more
%pleasant.

Mercurial Queuesは上記のような開発シナリオを管理するよい候補の一つである
といえる．このような場合のためにMQには作業をより快適にするいくつかの機能
がある．

%\section{Conditionally applying patches with guards}
\section{ガードを使ったパッチの条件的な適用}

%Perhaps the best way to maintain sanity with so many targets is to be
%able to choose specific patches to apply for a given situation.  MQ
%provides a feature called ``guards'' (which originates with quilt's
%\texttt{guards} command) that does just this.  To start off, let's
%create a simple repository for experimenting in.
%\interaction{mq.guards.init}
%This gives us a tiny repository that contains two patches that don't
%have any dependencies on each other, because they touch different files.

多くのターゲットを対象としながら正常に保つ一番良い方法は，状況に応じて特
定のパッチを選べるようにすることである．MQはこの目的のためにquiltの
\texttt{guards}コマンドに類似した``guards''と呼ばれる機能を提供している．
開始に当たって，実験のために単純なリポジトリを作成する．
\interaction{mq.guards.init}小さなリポジトリを作り，別々のファイルを操作
する互いに依存性のない2つのパッチを置く．

%The idea behind conditional application is that you can ``tag'' a
%patch with a \emph{guard}, which is simply a text string of your
%choosing, then tell MQ to select specific guards to use when applying
%patches.  MQ will then either apply, or skip over, a guarded patch,
%depending on the guards that you have selected.

条件付きでパッチの適用を制御する方法では，\emph{guard}によってパッチに付
けられた``タグ''を活用する．タグは自由に選んだ単純なテキストで，MQがパッ
チを適用するときに用いる特定のガードを指定する．MQはガードパッチの適用ま
たはスキップを，指定されたガードによって決定する．

%A patch can have an arbitrary number of guards;
%each one is \emph{positive} (``apply this patch if this guard is
%selected'') or \emph{negative} (``skip this patch if this guard is
%selected'').  A patch with no guards is always applied.

パッチは任意の数のガードを持つことができる．各々のガード
は，\emph{positive}（このガードが選択されているときにこのパッチを適用）ま
たは\emph{negative}（このガードが選択されているときにこのパッチをスキッ
プ）である．ガードを持たないパッチは常に適用される．

%\section{Controlling the guards on a patch}
\section{パッチ内のガードを操作する}

%The \hgxcmd{mq}{qguard} command lets you determine which guards should
%apply to a patch, or display the guards that are already in effect.
%Without any arguments, it displays the guards on the current topmost
%patch.
%\interaction{mq.guards.qguard}
%To set a positive guard on a patch, prefix the name of the guard with
%a ``\texttt{+}''.
%\interaction{mq.guards.qguard.pos}
%To set a negative guard on a patch, prefix the name of the guard with
%a ``\texttt{-}''.
%\interaction{mq.guards.qguard.neg}

\hgxcmd{mq}{qguard}コマンドでどのガードがパッチに適用されるかを指定した
り，すでに有効になっているガードを表示させることができる．引数なしでこの
コマンドを使うと，現在の最上位のパッチのガードを表示する．
\interaction{mq.guards.qguard}
パッチにポジティブガードを設定するには，ガード名の前に``\texttt{+}''をつ
ける．
\interaction{mq.guards.qguard.pos}
パッチにネガティブガードを設定するには，ガード名の前に``\texttt{-}''をつ
ける．
\interaction{mq.guards.qguard.neg}

%\begin{note}
%  The \hgxcmd{mq}{qguard} command \emph{sets} the guards on a patch; it
%  doesn't \emph{modify} them.  What this means is that if you run
%  \hgcmdargs{qguard}{+a +b} on a patch, then \hgcmdargs{qguard}{+c} on
%  the same patch, the \emph{only} guard that will be set on it
%  afterwards is \texttt{+c}.
%\end{note}

\begin{note}
 \hgxcmd{mq}{qguard} コマンドはパッチにガードを\emph{設定する}がパッチ自
 体を\emph{変更しない}点に注意されたい．パッチに対して
 \hgcmdargs{qguard}{+a +b}を実行し，同じパッチに\hgcmdargs{qguard}{+c}を
 実行すると，このパッチへのガードは\texttt{+c}のみになる．
\end{note}

%Mercurial stores guards in the \sfilename{series} file; the form in
%which they are stored is easy both to understand and to edit by hand.
%(In other words, you don't have to use the \hgxcmd{mq}{qguard} command if
%you don't want to; it's okay to simply edit the \sfilename{series}
%file.)
%\interaction{mq.guards.series}

Mercurialはガードを\sfilename{series}ファイルに保存する．書式は理解しや
すく，手で変更するのも簡単である．（つまり，\hgxcmd{mq}{qguard}コマンド
を使いたくなければ，直接\sfilename{series}を編集して済ますこともできる．）
\interaction{mq.guards.series}

%\section{Selecting the guards to use}
\section{使用するガードを選ぶ}

%The \hgxcmd{mq}{qselect} command determines which guards are active at a
%given time.  The effect of this is to determine which patches MQ will
%apply the next time you run \hgxcmd{mq}{qpush}.  It has no other effect; in
%particular, it doesn't do anything to patches that are already
%applied.

\hgxcmd{mq}{qselect}コマンドを実行することで，その時点でアクティブなガー
ドを指定することができる．このコマンドによって，次に\hgxcmd{mq}{qpush}が
実行されたときにどのパッチがMQによって適用されるかが指定される．それ以外
の効果はなく，特にすでに適用されているパッチに対しては何も行わない．

%With no arguments, the \hgxcmd{mq}{qselect} command lists the guards
%currently in effect, one per line of output.  Each argument is treated
%as the name of a guard to apply.
%\interaction{mq.guards.qselect.foo}
%In case you're interested, the currently selected guards are stored in
%the \sfilename{guards} file.
%\interaction{mq.guards.qselect.cat}
%We can see the effect the selected guards have when we run
%\hgxcmd{mq}{qpush}.
%\interaction{mq.guards.qselect.qpush}

引数なしで\hgxcmd{mq}{qselect}コマンドを実行すると，現在有効なガードのリ
ストを1行に1つずつ表示する．各々の引数は適用されるガードの名前として解釈
される．
\interaction{mq.guards.qselect.foo}
現在選択されているガードに興味がある場合，これは\sfilename{guards}ファイ
ルに保存されている．
\interaction{mq.guards.qselect.cat}
選択されたガードの効果は\hgxcmd{mq}{qpush}の実行時に見ることができる．
\interaction{mq.guards.qselect.qpush}

%A guard cannot start with a ``\texttt{+}'' or ``\texttt{-}''
%character.  The name of a guard must not contain white space, but most
%othter characters are acceptable.  If you try to use a guard with an
%invalid name, MQ will complain:
%\interaction{mq.guards.qselect.error}
%Changing the selected guards changes the patches that are applied.
%\interaction{mq.guards.qselect.quux}
%You can see in the example below that negative guards take precedence
%over positive guards.
%\interaction{mq.guards.qselect.foobar}

ガードを``\texttt{+}''や``\texttt{-}''の文字で始めることはできない．ガー
ド名は空白を含んではならないが，その他の殆んどの文字を含むことができる．
もし使用不可の文字を含む場合は、MQが警告を表示する。
\interaction{mq.guards.qselect.error}
選択されたガードを変更することは、適用されるパッチの変更を意味する。
\interaction{mq.guards.qselect.quux}
下の例でネガティブガードがポジティブガードよりも優先度を持つことがわかる。
\interaction{mq.guards.qselect.foobar}

%\section{MQ's rules for applying patches}
\section{MQのパッチ適用ルール}

%The rules that MQ uses when deciding whether to apply a patch
%are as follows.
MQが適用するパッチを決定する規則は下記のとおりである。
%\begin{itemize}
%\item A patch that has no guards is always applied.
%\item If the patch has any negative guard that matches any currently
%  selected guard, the patch is skipped.
%\item If the patch has any positive guard that matches any currently
%  selected guard, the patch is applied.
%\item If the patch has positive or negative guards, but none matches
%  any currently selected guard, the patch is skipped.
%\end{itemize}
\begin{itemize}
\item ガードのないパッチは常に適用する
\item パッチに現在選択されているガードにマッチするネガティブガードがあれ
      ば、そのパッチをスキップする
\item パッチに現在選択されているガードにマッチするポジティブガードがあれ
      ば、そのパッチを適用する
\item パッチがポジティブ・ネガティブいずれかのガードを持つが、現在選択さ
      れているガードとマッチするものがなければ、そのパッチをスキップする
\end{itemize}

%\section{Trimming the work environment}
\section{作業環境を縮小する}

%In working on the device driver I mentioned earlier, I don't apply the
%patches to a normal Linux kernel tree.  Instead, I use a repository
%that contains only a snapshot of the source files and headers that are
%relevant to Infiniband development.  This repository is~1\% the size
%of a kernel repository, so it's easier to work with.

以前言及したデバイスドライバでの作業では、Linuxカーネルツリーにパッチを適
用していなかった．その代わり，Infinibandドライバの開発に関連したソースと
ヘッダファイルだけを持つリポジトリを用いた．このリポジトリはカーネルリポ
ジトリの~1\%ほどのサイズで，作業が容易である．

%I then choose a ``base'' version on top of which the patches are
%applied.  This is a snapshot of the Linux kernel tree as of a revision
%of my choosing.  When I take the snapshot, I record the changeset ID
%from the kernel repository in the commit message.  Since the snapshot
%preserves the ``shape'' and content of the relevant parts of the
%kernel tree, I can apply my patches on top of either my tiny
%repository or a normal kernel tree.

ここでパッチを適用するための``base''バージョンを選ぶ．これは任意に選んだ
Linuxカーネルツリーのスナップショットで，作成する際，カーネルリポジトリの
チェンジセットIDをコミットメッセージに記録しておく．スナップショットはカー
ネルツリーの関連する部分の原型を保っているため，自分のパッチを開発用の個
別のリポジトリに適用するのと同様に通常のカーネルツリーに適用することがで
きる．

%Normally, the base tree atop which the patches apply should be a
%snapshot of a very recent upstream tree.  This best facilitates the
%development of patches that can easily be submitted upstream with few
%or no modifications.

通常，パッチが適用されるベースツリーは上流のツリーのごく最近のスナップ
ショットであるべきだ．こうすることで，開発したパッチを修正することなく，
あるいはごく僅かな修正のみで，上流へ提出することが可能になる．

%\section{Dividing up the \sfilename{series} file}
\section{\sfilename{series}ファイルを分割する}

%I categorise the patches in the \sfilename{series} file into a number
%of logical groups.  Each section of like patches begins with a block
%of comments that describes the purpose of the patches that follow.

筆者は\sfilename{series}ファイルのパッチをいくつかの論理的なグループにカ
テゴライズしている．パッチのそれぞれのセクションはあとに続くパッチが何で
あるか説明するコメントブロックで始まっている．

%The sequence of patch groups that I maintain follows.  The ordering of
%these groups is important; I'll describe why after I introduce the
%groups.
その後にメンテナンスしているパッチグループが連なる．グループを整理するこ
とは重要である．まずグループについて説明した後，この理由に触れる．

\begin{itemize}
%\item The ``accepted'' group.  Patches that the development team has
%  submitted to the maintainer of the Infiniband subsystem, and which
%  he has accepted, but which are not present in the snapshot that the
%  tiny repository is based on.  These are ``read only'' patches,
%  present only to transform the tree into a similar state as it is in
%  the upstream maintainer's repository.
\item ``accepted''グループ．開発チームがInfinibandサブシステムのメンテナ
      に提出し，受理されたが，小リポジトリのベースとなっているスナップ
      ショットにはまだ取り込まれていないもの．これらはツリーを上流メンテ
      ナのリポジトリと同様の状態にするために存在する``読み出しのみ''のパッ
      チである．
%\item The ``rework'' group.  Patches that I have submitted, but that
%  the upstream maintainer has requested modifications to before he
%  will accept them.
\item ``rework''グループ．提出したが上流メンテナが受理に先だって変更を要
      求したもの．
%\item The ``pending'' group.  Patches that I have not yet submitted to
%  the upstream maintainer, but which we have finished working on.
%  These will be ``read only'' for a while.  If the upstream maintainer
%  accepts them upon submission, I'll move them to the end of the
%  ``accepted'' group.  If he requests that I modify any, I'll move
%  them to the beginning of the ``rework'' group.
\item ``pending''グループ．上流メンテナにはまだ提出していないが，手元で
      の作業は完了したもの．これらはしばらくの間``read only''になってお
      り，上流のメンテナへ提出して受理された時は``accepted''グループへ移
      動される．メンテナが変更を要求した場合は``rework''グループへ移動さ
      れる．
%\item The ``in progress'' group.  Patches that are actively being
%  developed, and should not be submitted anywhere yet.
\item ``in progress''グループ．このグループには，アクティブに開発さ
      れており，まだどこへも提出されるべきではないパッチが含まれる．
%\item The ``backport'' group.  Patches that adapt the source tree to
%  older versions of the kernel tree.
\item ``backport''グループ．ソースを古いバージョンのカーネルツリーへ適合
      させるパッチからなる．
%\item The ``do not ship'' group.  Patches that for some reason should
%  never be submitted upstream.  For example, one such patch might
%  change embedded driver identification strings to make it easier to
%  distinguish, in the field, between an out-of-tree version of the
%  driver and a version shipped by a distribution vendor.
\item ``do not ship''グループ．なんらかの理由によって決して上流へ提出され
      るべきでないパッチからなる．例えば，ツリー外のドライバとベンダによっ
      て配布されているドライバを識別しやすくするためにドライバの識別文字
      列を変更するようなパッチが該当する．
\end{itemize}

%Now to return to the reasons for ordering groups of patches in this
%way.  We would like the lowest patches in the stack to be as stable as
%possible, so that we will not need to rework higher patches due to
%changes in context.  Putting patches that will never be changed first
%in the \sfilename{series} file serves this purpose.

パッチをこのような方法で整理する理由の説明へ戻ろう．一般に，パッチスタッ
クの底にあるパッチはなるべく安定であって欲しいと思うものだ．そうであれ
ば，パッチのコンテキストで変更による再作業をせずに済む．
\sfilename{series}に最初に追加するパッチは決して変更されないものにすると
よい．

%We would also like the patches that we know we'll need to modify to be
%applied on top of a source tree that resembles the upstream tree as
%closely as possible.  This is why we keep accepted patches around for
%a while.

また，適用のために変更しなければならないパッチについては，できるだけ上流
のツリーに近いソースツリーに適用できるようになっていて欲しいと考える．こ
れが受理されたパッチをしばらくの間保持している理由である．

%The ``backport'' and ``do not ship'' patches float at the end of the
%\sfilename{series} file.  The backport patches must be applied on top
%of all other patches, and the ``do not ship'' patches might as well
%stay out of harm's way.

``backport''と``do not ship''パッチは\sfilename{series}ファイルの末尾に置
かれる．``backport''パッチは他のパッチすべての上から適用されなければなら
ないし，``do not ship''パッチは安全なところに置かれていなければならない．

%\section{Maintaining the patch series}
\section{パッチシリーズを管理する}

%In my work, I use a number of guards to control which patches are to
%be applied.

この作業では，どのパッチが適用されるか制御するためにいくつかのガードを用
いている．

\begin{itemize}
%\item ``Accepted'' patches are guarded with \texttt{accepted}.  I
%  enable this guard most of the time.  When I'm applying the patches
%  on top of a tree where the patches are already present, I can turn
%  this patch off, and the patches that follow it will apply cleanly.

\item ``Accepted''パッチは\texttt{accepted}によってガードされている．筆者
はこのガードをほぼいつも有効にしている．すでにパッチが存在しているツリー
の上に新たなパッチを適用する時は，このパッチをオフにして，後続のパッチが
クリーンに適用されるようにすることができる．

%\item Patches that are ``finished'', but not yet submitted, have no
%  guards.  If I'm applying the patch stack to a copy of the upstream
%  tree, I don't need to enable any guards in order to get a reasonably
%  safe source tree.

\item 完成されているものの，まだ提出されていないパッチはガードを持たな
      い．このパッチスタックを上流ツリーのコピーに適用する場合，ガードを
      全く使わずに十分安全なソースツリーを得ることができる．

%\item Those patches that need reworking before being resubmitted are
%  guarded with \texttt{rework}.

 \item 再提出のために作業が必要なパッチには\texttt{rework}ガードを用いる．

%\item For those patches that are still under development, I use
%  \texttt{devel}.

 \item 開発中のパッチには\texttt{devel}ガードを用いている．

%\item A backport patch may have several guards, one for each version
%  of the kernel to which it applies.  For example, a patch that
%  backports a piece of code to~2.6.9 will have a~\texttt{2.6.9} guard.

 \item バックポートパッチはパッチが適用されるカーネルのバージョンそれぞれ
      に対してガードを持つことがある．例えば，あるコードを~2.6.9にバック
      ポートするパッチは~\texttt{2.6.9}というガードを持つ．
\end{itemize}
%This variety of guards gives me considerable flexibility in
%determining what kind of source tree I want to end up with.  For most
%situations, the selection of appropriate guards is automated during
%the build process, but I can manually tune the guards to use for less
%common circumstances.

多くのガードを用いることによって，柔軟に作業対象のソースツリーを選ぶこと
ができる．ビルド処理中に正しいガードを自動的に選択できることがほとんどだ
が，特殊な状況のために手で選ぶことも可能である．

%\subsection{The art of writing backport patches}
\subsection{バックポートパッチを書く技術}

%Using MQ, writing a backport patch is a simple process.  All such a
%patch has to do is modify a piece of code that uses a kernel feature
%not present in the older version of the kernel, so that the driver
%continues to work correctly under that older version.

MQを使ってバックポートパッチを書くのは単純な作業である．そのようなパッチ
がすべきことは，古いバージョンのカーネルに備わっていない機能を使うコード
を変更し，古いバージョンのカーネルでも正しく機能し続けるようにすることだ
けである．

%A useful goal when writing a good backport patch is to make your code
%look as if it was written for the older version of the kernel you're
%targeting.  The less obtrusive the patch, the easier it will be to
%understand and maintain.  If you're writing a collection of backport
%patches to avoid the ``rat's nest'' effect of lots of
%\texttt{\#ifdef}s (hunks of source code that are only used
%conditionally) in your code, don't introduce version-dependent
%\texttt{\#ifdef}s into the patches.  Instead, write several patches,
%each of which makes unconditional changes, and control their
%application using guards.

よいバックポートパッチとは，そのパッチによってあたかもコードがターゲット
の古いバージョンのカーネルに向けて書かれたような状態になるものである．
無理のないパッチは理解しやすく，メンテナンスも容易である．
バックポートパッチをいくつも書いているならば，コード内の大量の
\texttt{\#ifdef}で条件的コンパイルされるコードによる混乱を避けるべきであ
る．そのためにバージョンに依存した\texttt{\#ifdef}ではなく，ガードによっ
て制御される条件コンパイルによらない変更を加えるべきである．

%There are two reasons to divide backport patches into a distinct
%group, away from the ``regular'' patches whose effects they modify.
%The first is that intermingling the two makes it more difficult to use
%a tool like the \hgext{patchbomb} extension to automate the process of
%submitting the patches to an upstream maintainer.  The second is that
%a backport patch could perturb the context in which a subsequent
%regular patch is applied, making it impossible to apply the regular
%patch cleanly \emph{without} the earlier backport patch already being
%applied.

バックポートパッチを通常の変更を加えるパッチと別のグループに分割する理由
が2つある．第一の理由は，2つを混ぜ合わせることで，上流のメンテナへパッチ
を提出するために\hgext{patchbomb}エクステンションのようなツールを使うのが
難しくなることである．第二の理由は，バックポートパッチは，後続の通常パッ
チの適用されるコンテキストを乱すことがあり，そのような場合，通常パッチは
バックポートパッチなしに正しく適用することが不可能になってしまう．

%\section{Useful tips for developing with MQ}
\section{MQによる開発のtips}

%\subsection{Organising patches in directories}
\subsection{ディレクトリ内でパッチを管理する}

%If you're working on a substantial project with MQ, it's not difficult
%to accumulate a large number of patches.  For example, I have one
%patch repository that contains over 250 patches.

MQを用いて比較的大規模なプロジェクトで作業している場合，大量のパッチが蓄
積することが少なくない．例えば筆者のところには，250以上のパッチを含むパッ
チリポジトリがある．

%If you can group these patches into separate logical categories, you
%can if you like store them in different directories; MQ has no
%problems with patch names that contain path separators.

もしこれらのパッチを論理的なカテゴリに分割することができ，別々のディレク
トリに収容したいと考えるならば，パッチ名にパスセパレータを含めてもMQは問
題なく取り扱うことができる．

%\subsection{Viewing the history of a patch}
\subsection{パッチのヒストリを見る}
\label{mq-collab:tips:interdiff}

%If you're developing a set of patches over a long time, it's a good
%idea to maintain them in a repository, as discussed in
%section~\ref{sec:mq:repo}.  If you do so, you'll quickly discover that
%using the \hgcmd{diff} command to look at the history of changes to a
%patch is unworkable.  This is in part because you're looking at the
%second derivative of the real code (a diff of a diff), but also
%because MQ adds noise to the process by modifying time stamps and
%directory names when it updates a patch.

長い期間にわたって多くのパッチを作ってきたのなら，~\ref{sec:mq:repo}節で
議論してきたようにそれらをリポジトリで管理するのは良い考えである．そうし
た場合，すぐに\hgcmd{diff}コマンドではパッチのヒストリを見ることに使えな
いことに気づくだろう．これは実際のコードの二次的な派生物（diffのdiff）を
見ていることと，MQがパッチを更新する時にタイムスタンプとディレクトリ名を
変更することで，プロセスにノイズを加えているためでである．

%However, you can use the \hgext{extdiff} extension, which is bundled
%with Mercurial, to turn a diff of two versions of a patch into
%something readable.  To do this, you will need a third-party package
%called \package{patchutils}~\cite{web:patchutils}.  This provides a
%command named \command{interdiff}, which shows the differences between
%two diffs as a diff.  Used on two versions of the same diff, it
%generates a diff that represents the diff from the first to the second
%version.

しかしMercurialに同梱されている\hgext{extdiff}エクステンションを使い，2つ
のバージョンのパッチ間で意味のある差分を取ることができる．このために
\package{patchutils}~\cite{web:patchutils}を使う必要がある．このパッケー
ジは2つのdiffファイル間の差分をdiffとして表示する\command{interdiff}とい
うコマンドを提供している．同じdiffの異なるバージョン間で使用すれば，前後
のdiffの間のdiffを生成する．

%You can enable the \hgext{extdiff} extension in the usual way, by
%adding a line to the \rcsection{extensions} section of your \hgrc.
\hgrc ファイルの \rcsection{extensions} セクションに次の行を追加する通常の
方法で\hgext{extdiff}を有効にできる．
\begin{codesample2}
  [extensions]
  extdiff =
\end{codesample2}
%The \command{interdiff} command expects to be passed the names of two
%files, but the \hgext{extdiff} extension passes the program it runs a
%pair of directories, each of which can contain an arbitrary number of
%files.  We thus need a small program that will run \command{interdiff}
%on each pair of files in these two directories.  This program is
%available as \sfilename{hg-interdiff} in the \dirname{examples}
%directory of the source code repository that accompanies this book.
%\excode{hg-interdiff}

\command{interdiff}コマンドは2つのファイル名を渡されることを想定している
が，\hgext{extdiff}拡張は，2つのディレクトリを引数として取るコマンドを起
動する．従ってこれらの2つのディレクトリの各々のファイルに対して
\command{interdiff}を起動する小さなプログラムが必要になる．この本のソース
コードリポジトリディレクトリ内の\dirname{examples}ディレクトリにある
\sfilename{hg-interdiff}というプログラムがそれだ．
\excode{hg-interdiff}

%With the \sfilename{hg-interdiff} program in your shell's search path,
%you can run it as follows, from inside an MQ patch directory:
シェルサーチパスの中に\sfilename{hg-interdiff}があれば， MQパッチディレク
トリの中から次のように起動できる．

\begin{codesample2}
  hg extdiff -p hg-interdiff -r A:B my-change.patch
\end{codesample2}
%Since you'll probably want to use this long-winded command a lot, you
%can get \hgext{hgext} to make it available as a normal Mercurial
%command, again by editing your \hgrc.
この長いコマンドは頻繁に使うことになるだろう．そこで \hgrc を編集
し，\hgext{hgext}で通常のMercurialコマンドのように使えるようにする．
\begin{codesample2}
  [extdiff]
  cmd.interdiff = hg-interdiff
\end{codesample2}
%This directs \hgext{hgext} to make an \texttt{interdiff} command
%available, so you can now shorten the previous invocation of
%\hgxcmd{extdiff}{extdiff} to something a little more wieldy.
これは\hgext{hgext}に\texttt{interdiff}コマンドが利用可能であることを指
示するため，以前の\hgxcmd{extdiff}{extdiff}の起動を若干簡単にできる．
\begin{codesample2}
  hg interdiff -r A:B my-change.patch
\end{codesample2}

\begin{note}
%  The \command{interdiff} command works well only if the underlying
%  files against which versions of a patch are generated remain the
%  same.  If you create a patch, modify the underlying files, and then
%  regenerate the patch, \command{interdiff} may not produce useful
%  output.

\command{interdiff}コマンドは，パッチのバージョンが生成された元のファイル
が同一に保たれている場合に限って正しく動く．パッチを作成してから元のファ
イルを変更し，パッチを再生成した場合は\command{interdiff}は有用な差分を出
力しないかもしれない．

\end{note}

%The \hgext{extdiff} extension is useful for more than merely improving
%the presentation of MQ~patches.  To read more about it, go to
%section~\ref{sec:hgext:extdiff}.

\hgext{extdiff}エクステンションはMQパッチの表現を改善する以上のことをす
る．このエクステンションについて更に知りたい時は\ref{sec:hgext:extdiff}セ
クションを参照されたい．

%%% Local Variables:
%%% mode: yatex
%%% TeX-master: "00book"
%%% End:
