Sakura: HTML ヘルプ中のバージョン番号に関して考える

[m-tmatma]

HTML ヘルプ中のバージョン番号に関して考える

https://github.com/sakura-editor/sakura/blob/4c58aeb2fda06c5bc966a14233fc99cde351f774/help/sakura/_RESOURCE/HLP000001.html#L18

HTML ヘルプでバージョン番号を決め打ちされているが、
現状の仕様 ではバージョン番号の末尾はビルド番号になっている。 (#324)

[berryzplus]

個人的感想です。

現状) ver 2.3.2.0
代案) ver 2.3.x

ヘルプはアプリの取説にあたるものだと思います。
どんな機能があるか？をユーザが知るための資料です。

バージョンの付け方の話で、minorは機能が増えたら上げる、というのがあった気がします。
2番目の数字が機能追加で上がるとすると、
3番目の数字が上がっても機能は増えないことになります。
これはつまり「3番目の数字をヘルプに書く意味はない」ということです。

アプリのバージョンと合わせるべきだ！に対する代案を出してみました。

[m-tmatma]

https://github.com/sakura-editor/sakura/blob/4c58aeb2fda06c5bc966a14233fc99cde351f774/help/sakura/_RESOURCE/HLP000001.html#L18

の部分に対して、人が手動で更新するのではなく

<center>サクラエディタ Ver <div class="target_version">2.3.2.0</div></center>

というような記述にしておいて、appveyor から、指定の class の <div> の部分を

https://github.com/sakura-editor/sakura/blob/4c58aeb2fda06c5bc966a14233fc99cde351f774/sakura_core/version.h#L13-L15

の値、あるいは EXEのバージョンリソースを元に自動的に書き換えられないか? と思います。

[KENCHjp]

ごめんなさい、いまローカルヘルプとオンラインヘルプって自動同期なんでしたっけ？？？

[KENCHjp]

ヘルプは機能以外も書かれる認識。
バグフィックスとか変更履歴とか。
なので、v2.4.n
なのかなと。

[KENCHjp]

自動更新かどうかで気になったのは、リリース時の段取りで、

リリース時に、プログラムのバージョンをあげますよね。
PRして動確。←ここでヘルプファイルバージョンあがる。
OKであればマージ。
タグ付け。←ここでオンラインヘルプのバージョンあがる？　もしくは手動？

[berryzplus]

あんまし自信あるわけじゃないんですが・・・

バグフィックスとか変更履歴とか。

これを書くのはリリースノートな気がします。
現状のヘルプには変更履歴もあった気がするのでちょっと微妙。
リリースノートないときはヘルプに書くものなんですかね。

[KENCHjp]

リリースノートないときはヘルプに書くものなんですかね。

アプリによるかもしれませんね。
例えば何かの機能の中の選択肢が一つ増えるだけだったりしたら、２こめじゃなくて、３こめのバージョンあげますね私は。
新しい機能追加で、２（マイナーバージョン？）こめあげて、その機能の修正（バグ対応やエンハンス含む）は３こめあげちゃうかも(たとえば、Grepで除外フォルダ/ファイルを指定する機能追加は、メジャーマイナーバージョン上げます？)
どういうときにそもそもどこを上げるかって、一応Issueありますが、いままで厳密でなかっことに起因するのかもしれませんが。

[berryzplus]

例えば何かの機能の中の選択肢が一つ増えるだけだったりしたら、２こめじゃなくて、３こめのバージョンあげますね私は。

Grepダイアログに除外ファイル/除外フォルダを追加する件は3個目が上がる話だと思っています。
使い方が変わるのでできればヘルプを更新したほうがいいと思っています。

そう考えると「取説だから2個目だけを管理すればよい」ってのもやや微妙ですね。

個人的なイメージとして、ヘルプの目次が増える＝2個目が上がる、なのかな？です。

[KENCHjp]

個人的なイメージとして、ヘルプの目次が増える＝2個目が上がる、なのかな？です。

イメージあってます。
バグフィックスや変更履歴はプロジェクト毎のキメですかね。別だしして一か所で管理したい気はしています（変更履歴とかで工数を割きたくないですよねぇ。。。）

[jakenjarvis]

バージョン番号の付け方については、こんなのがあったりします。（このIssueの本題とちょっとズレてる気がしますが参考になれば！）
Semantic Versioning 2.0.0 ( 日本語 )

[berryzplus]

@jakenjarvis さん
ありがとうございます。

semantic versioningについてはたまたま既出でした。https://github.com/sakura-editor/sakura/issues/168#issuecomment-400901947
いまのところ、色んな方法を見て「次リリースは 2.4.0 」だけが決まってる感じです。

issue 分かりづらくて申し訳ないです。

[KageShiron]

結論が出きらないうちに議論が止まってしまってる状況ですね・・・
一部の話を読み落としてるかもしれませんが、個人的には以下のようなのがわかりやすいと思ってます。

• ヘルプには2.4.3みたいにa.b.cまで表記
• バージョン番号の変更はリリース時のみ行う(開発中はビルド番号やコミットハッシュで識別すれば十分)
• 大きな追加や、大きめの破壊的変更でbをインクリメント
• 小さな機能追加や、バグフィックス、ヘルプの誤字修正なども含めて、あらゆる変更でcをインクリメント
• バージョン番号は手動でタグをつけた時に変更される
  
  
  
  • CIによってバージョンが全て書き換えられる
  
  
  • オンラインヘルプの更新や、GitHub Releaseの公開まで自動化
  
  
  • (理想での話なので、実際には手作業や泥臭い手順が残りそうではありますが)
  
  
  • タグの代わりに正式公開版ブランチ見たいのがあってもいいかもしれません
  
  

[KENCHjp]

@KageShiron さん、まとめありがとうございます。
これで、Wiki記載しちゃいましょう。
あっちこっちIssueがちらかってるところは、Wikiへのリンクつけてcloseしましょうかね!

[KENCHjp]

ヘルプいま、

サクラエディタ Ver 2.4.0 (開発版)

ってなってますね。
やっぱりリリース用のブランチ切った方がいいのかなぁ。。。

[takke]

https://github.com/sakura-editor/sakura/pull/814 にてリリース用のブランチを切って HTMLヘルプ中のバージョン番号も修正してみました。

[KENCHjp]

これクローズでいいかしら？

[m-tmatma]

閉じます