docs: add a restoration guide for old-version documentation#3043
Merged
Conversation
Per the version policy, descriptions specific to a Ruby version may be deleted once the following version reaches EOL, so doctree HEAD (and manual/ converted from it) no longer carries much pre-3.0-specific text (e.g. mentions of 1.8.7 under refm/api/src: 232 at tag 20150229, 214 at the 2016-08-28 archive generation, 5 at HEAD today). Record where to restore each old version from before refm/ is removed: - reproduction of the published archives: the doctree commits matching the 'generated on' dates recorded by rurema/generated-documents' import commits (html for 1.8.7-2.7.0; db-2.4.0..2.7.0 are preserved in-repo, db-2.3.0 and older are not) - fullest content per version: the EOL-time tags (20150229..20200331), the last snapshots guaranteed to predate the deletion window; for 2.0.0-2.3.0 the published archives were generated before that window opened, while for 1.8.7/1.9.3 the tags predate the archives Also note the rebuild caveats (era bitclust may be required; the salvage-aware rrd2md --scope can convert old snapshots to Markdown but needs roundtrip verification against era notation). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概要
refm/ 削除（Stage B）の前提整理です。バージョン対応方針により「次の版が EOL になった時点」から旧版固有の記述は削除可能なため、HEAD の refm（とそこから変換した manual/）には旧版固有の記述の多くが既に残っていません（実測: refm/api/src の「1.8.7」言及は タグ 20150229 で 232 → 1.8.7 アーカイブ生成時点 2016-08-28 で 214 → 現 HEAD で 5)。
旧版ドキュメントの復元に使う「時点」を調査し、対応表として
docs/OldVersionArchives.mdに記録します。内容
公開アーカイブの再現: rurema/generated-documents の Import コミットに残る生成日から、当時の doctree コミットを対応付け:
db は 2.4.0〜2.7.0 のみ generated-documents に保存済み（2.3.0 以前は無し)。
最も完全な状態の復元: EOL 時に打たれたタグ = 削除解禁直前のスナップショット（1.8.7→
20150229、1.9.3→20160229、2.0.0→20170331、2.1.0→20180331、2.2.0→20190331、2.3.0→20200331)。2.0.0〜2.3.0 は公開アーカイブの生成が削除解禁前なのでアーカイブ≒完全、1.8.7/1.9.3 はタグの方が公開アーカイブより情報が多い可能性があります。復元時の注意も記載: 旧時点ソースは当時の bitclust が必要になりうる（HEAD の refm でも 1.8.7 は cgi/util.rd 破損でビルド不能)、md 化するなら salvage 対応済み rrd2md の
--scope+ roundtrip 検証。docs/ のみの変更なので CI は走りません。
🤖 Generated with Claude Code