Confluence
Atlassian
AUG

Confluence TIPS; pull requestを(強引に)実現してみた

More than 1 year has passed since last update.


はじめに

弊社にConfluenceが導入されてから数年が経ちましたが、使い込むほど便利さがよく分かる優秀なツールです。やりたい事はほぼConfluenceやアドオンの機能だけで解決するので非常に助かっております。

しかし、そんな便利なConfluenceにも、ひとつだけ欲しい機能がありませんでした。

それが"pull request"です。


なぜpull requestが必要だったのか?

まずは下記スクリーンショットをご覧ください。

駄目な運用例.png

これは、「吾輩は猫である」の一節を用いて、実際に私が遭遇したアンチパターンを再現したものです(実際のページは、この程度が可愛く思えてしまうほど手に負えない状態でした)。

このアンチパターンは、次のルールに沿って手動で運用されていました。


  • stableな内容とunstableな内容を同一ページ内に記述する

  • 次版で変更される箇所を赤色でマーキングする

  • 次版で削除予定の箇所は取消線でマーキングする

  • stableになった内容のマーキングはその都度手動で解除する

この運用ルールには次のような問題点が存在しています。


  • ページ内の装飾として赤色と取消線を使用できない(→ 運用ルールと衝突する)

  • 並行開発を行う場合、開発タスクとマーキングとの間にリレーションが無い

  • ページ履歴に余計な変更が積み上がる(→ 履歴の統合ができない)

  • いつまで経ってもページに編集制限を掛けられない(→ stableにならない)

このような運用を続けたことによって、ドキュメントは仕様の追加や変更に柔軟に対応する事ができず、結果的にドキュメントの保守に無駄な時間を割くという本末転倒で最悪な状況になっていました。

「もしもConfluenceにpull request機能があれば、この地獄のようなドキュメント保守作業から開放されるのに…」

そんな妄想から「疑似pull request」という手法が誕生しました。


「疑似pull request」とは

Gitを用いた開発フローの利便性は、エンジニアであれば誰でもすぐに理解できるはずです。

その利便性をConfluenceでも実現するための運用方法が、この「疑似pull request」になります。

疑似pull requestの運用ルールは次のとおりです。


  • stableのページは必ず編集制限を設定する

  • ページを編集したい場合、子ページとして作成したコピーページを編集する

  • 子ページの編集履歴の差分(v.1〜最新間)で変更点を確認

  • レビュー済みの子ページの内容を親ページにマージする

  • マージ後は子ページを削除する

Gitに置き換えると、各ページは次のような関係になります。

用途
Confluence
編集制限
Git
備考

stable
親ページ
あり
master相当

編集用
子ページ
なし
develop相当
親ページのコピー

それでは手順を追って説明していきます。


STEP 1. 編集用ページの作成

stableのページをコピーし、子ページとして保存します。

ドキュメントツリー.png


  • stable:「吾輩は猫である」

  • 編集用:「修正版:吾輩は猫である」


STEP 2. 編集

編集用ページを適宜編集します。

編集用ページのv.1と最新の差分表示することで、いつでも変更点を把握することができます。

変更点.png


STEP 3. レビュー

編集が終わったらレビューを行います。

インラインコメントで指摘事項を記入する事でレビューしていきます。

指摘された箇所は適宜修正しましょう。

レビュー.png


STEP 4. マージ

レビューが終わりましたら、stableページへのマージを行います。

編集用ページの編集フォームから該当箇所をクリップボードへコピーし、stableページの編集フォームにクリップボードの内容をペーストして保存します。

その結果、stableページには不要な履歴が残らず、純粋な差分のみが履歴として記録されます。

マージが済んだ子ページは不要ですので、直ぐに削除しましょう。

統合結果.png


最後に

願わくばConfluence自体若しくはアドオンにpull requestとマージに相当する機能が実装され、このTIPSが過去の遺物として葬り去られる日が一日も早く訪れる事を願っております。

Atlassian様、是非実現をお願いします!