diff options
| -rw-r--r-- | docs/ja/_summary.md | 2 | ||||
| -rw-r--r-- | docs/ja/breaking_changes.md | 120 | ||||
| -rw-r--r-- | docs/ja/breaking_changes_instructions.md | 51 |
3 files changed, 172 insertions, 1 deletions
diff --git a/docs/ja/_summary.md b/docs/ja/_summary.md index e6423c6c26..987df23d76 100644 --- a/docs/ja/_summary.md +++ b/docs/ja/_summary.md @@ -106,7 +106,7 @@ * [Velocikey](ja/feature_velocikey.md) * QMK の開発 - * 破壊的な変更 + * 互換性を破る変更/Breaking changes * [概要](ja/breaking_changes.md) * [プルリクエストにフラグが付けられた](ja/breaking_changes_instructions.md) * 履歴 diff --git a/docs/ja/breaking_changes.md b/docs/ja/breaking_changes.md new file mode 100644 index 0000000000..936d0a4722 --- /dev/null +++ b/docs/ja/breaking_changes.md @@ -0,0 +1,120 @@ +# Breaking changes/互換性を破る変更 + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: 0.9.0:docs/breaking_changes.md + git diff 0.9.0 HEAD -- docs/breaking_changes.md | cat +--> + +このドキュメントは QMK の互換性を破る変更(Breaking change) のプロセスについて説明します。 +互換性を破る変更とは、互換性がなかったり潜在的な危険が生じるように QMK の動作を変える変更を指します。 +ユーザが QMK ツリーを更新しても自分のキーマップが壊れない事を確信できるように、これらの変更を制限します。(訳注：以後、原文のまま Breaking change を用語として使用します。) + +Breaking change ピリオドとは、危険な変更、または予想外の変更を QMK へ行なう PR をマージする時のことです。 +付随するテスト期間があるため、問題が起きることはまれか、有りえないと確信しています。 + +## 過去の Breaking change には何が含まれますか？ + +* [2020年5月30日](ja/ChangeLog/20200530.md) +* [2020年2月29日](ja/ChangeLog/20200229.md) +* [2019年8月30日](ja/ChangeLog/20190830.md) + +## 次の Breaking change はいつですか？ + +次の Breaking change は2020年8月29日に予定されています。 + +### 重要な日付 + +* [x] 2020年 5月30日 - `develop` が作成されました。毎週リベースされます。 +* [ ] 2020年 8月 1日 - `develop` は新しいPRを取り込みません。 +* [ ] 2020年 8月 1日 - テスターの募集。 +* [ ] 2020年 8月27日 - `master`がロックされ、PR はマージされません。 +* [ ] 2020年 8月29日 - `develop` を `master` にマージします。 +* [ ] 2020年 8月29日 - `master` のロックが解除されます。PR を再びマージすることができます。 + +## どのような変更が含まれますか？ + +最新の Breaking change 候補を見るには、[`breaking_change` ラベル](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr)を参照してください。 +現在から `develop` が閉じられるまでの間に新しい変更が追加される可能性があり、そのラベルが適用された PR はマージされることは保証されていません。 + +このラウンドに、あなたの Breaking change を含めたい場合は、`breaking_change` ラベルを持つ PR を作成し、`develop` が閉じる前に承認してもらう必要があります。 +`develop` が閉じた後は、新しい Breaking change は受け付けられません。 + +受け入れの基準: + +* PR が完了し、マージの準備ができている +* PR が ChangeLog を持つ + +# チェックリスト + +ここでは、Breaking change プロセスを実行する時に使用する様々なプロセスについて説明します。 + +## `master` から `develop` をリベースします + +これは `develop` が開いている間、毎週金曜日に実行されます。 + +プロセス: + +``` +cd qmk_firmware +git checkout master +git pull --ff-only +git checkout develop +git rebase master +git push --force +``` + +## `develop` ブランチの作成 + +以前の `develop` ブランチがマージされた直後に、これが発生します。 + +* `qmk_firmware` git commands + * [ ] `git checkout master` + * [ ] `git pull --ff-only` + * [ ] `git checkout -b develop` + * [ ] Edit `readme.md` + * [ ] これがテストブランチであることを上部に大きな通知で追加します。 + * [ ] このドキュメントへのリンクを含めます + * [ ] `git commit -m 'Branch point for <DATE> Breaking Change'` + * [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>` + * [ ] `git tag <next_version>` # ブレーキング ポイント タグがバージョンの増分を混乱させないようにします + * [ ] `git push origin develop` + * [ ] `git push --tags` + +## マージの 4 週間前 + +* `develop` は新しい PR に対して閉じられ、現在の PR の修正のみがマージされる可能性があります。 +* テスターの呼び出しを投稿します + * [ ] Discord + * [ ] GitHub PR + * [ ] https://reddit.com/r/olkb + +## マージの 1 週間前 + +* master が < 2 日前> から <マージの日> まで閉じられることを発表します + * [ ] Discord + * [ ] GitHub PR + * [ ] https://reddit.com/r/olkb + +## マージの 2 日前 + +* master が 2 日間閉じられることを発表します + * [ ] Discord + * [ ] GitHub PR + * [ ] https://reddit.com/r/olkb + +## マージの日 + +* `qmk_firmware` git commands + * [ ] `git checkout develop` + * [ ] `git pull --ff-only` + * [ ] `git rebase origin/master` + * [ ] Edit `readme.md` + * [ ] `develop` についてのメモを削除 + * [ ] ChangeLog を 1 つのファイルにまとめます。 + * [ ] `git commit -m 'Merge point for <DATE> Breaking Change'` + * [ ] `git push origin develop` +* GitHub Actions + * [ ] `develop`の PR を作成します + * [ ] travis がクリーンに戻ったことを確認します + * [ ] `develop` PR をマージします diff --git a/docs/ja/breaking_changes_instructions.md b/docs/ja/breaking_changes_instructions.md new file mode 100644 index 0000000000..69d17d73c5 --- /dev/null +++ b/docs/ja/breaking_changes_instructions.md @@ -0,0 +1,51 @@ +# breaking changes/互換性を破る変更: プルリクエストにフラグが付けられた + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: 0.9.0:docs/breaking_changes_instructions.md + git diff 0.9.0 HEAD -- docs/breaking_changes_instructions.md | cat +--> + +QMK のメンバーがあなたのプルリクエストに返信し、あなたの提出したものは Breaking change (互換性を破る変更) であると述べている場合があります。メンバーの判断では、あなたが提案した変更は QMK やその利用者にとってより大きな影響を持つと考えられます。 + +プルリクエストにフラグが立てられる原因となるものには、以下のようなものがあります: + +- **ユーザーのキーマップに対する編集** + ユーザーが自分のキーマップを QMK に提出した後、しばらくしてさらに更新してプルリクエストを開いたところ、それが `qmk/qmk_firmware` リポジトリで編集されていたためにマージできなかったことに気づくことがあるかもしれません。すべてのユーザーが Git や GitHub を使いこなせるわけではないので、ユーザー自身で問題を修正できないことに気づくかもしれません。 +- **期待される動作の変更** + QMK の動作を変更すると、既存の QMK 機能への変更を組み込んだ新しいファームウェアをフラッシュした場合、ユーザはハードウェアまたは QMK が壊れていると考え、希望する動作を復元する手段がないことに気付くことがあります。 +- **ユーザーのアクションを必要とする変更** + 変更には、ツールチェインを更新したり、Git で何らかのアクションを取るなど、ユーザーがアクションを行う必要がある場合もあります。 +- **精査が必要な変更** + 時には、投稿がプロジェクトとしての QMK に影響を与えることもあります。これは、著作権やライセンスの問題、コーディング規約、大規模な機能のオーバーホール、コミュニティによるより広範なテストを必要とする「リスクの高い」変更、あるいは全く別のものである可能性があります。 +- **エンドユーザーとのコミュニケーションを必要とする変更** + これには、将来の非推奨化への警告、時代遅れの慣習、その他伝えなければならないが上記のカテゴリのどれかに当てはまらないものが含まれます。 + +## 何をすればいいのか? + +提出したものが Breaking change だと判断された場合、手続きをスムーズに進めるためにできることがいくつかあります。 + +### PR を分割することを検討する + +あなたがコアコードを投稿していて、それが Breaking change プロセスを経る必要がある唯一の理由が、あなたの変更に合わせてキーマップを更新していることである場合、古いキーマップが機能し続けるような方法であなたの機能を投稿できるかどうかを検討してください。 +そののち、Breaking change プロセスを経て古いコードを削除する別の PR を提出してください。 + +### ChangeLog エントリの提供 + +Breaking change プロセスを経て提出する際には、変更ログのエントリを含めることを我々は要請します。 +エントリーは、あなたのプルリクエストが行う変更の短い要約としてください – [ここの各セクションは changelog として開始されました](ja/ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc - @noroadsleft")。 + +変更ログは `docs/ChangeLog/YYYYMMDD/PR####.md` に置いてください。 +ここで、`YYYYMMDD` は QMK の breaking change ブランチ – 通常は `develop` という名称 – が `master` ブランチにマージされる日付、`####` はプルリクエストの番号です。 + +ユーザー側でのアクションを必要とする場合、あなたの変更ログは、どのようなアクションを取らなければならないかをユーザーに指示するか、そのようなアクションを指示する場所にリンクする必要があります。 + +### 変更点を文書化する + +提出物の目的を理解し、それが必要とする可能性のある意味合いやアクションを理解することで、レビュープロセスをより簡単にすることができます。この目的のためには変更履歴で十分かもしれませんが、より広範囲の変更を行う場合には、変更履歴には不向きな詳細レベルが必要になるかもしれません。 + +あなたのプルリクエストにコメントしたり、質問やコメント、変更要求に対応したりすることは、非常にありがたいことです。 + +### 助けを求める + +あなたの提出物にフラグが立ったことで、あなたはびっくりしてしまったかもしれません。もし、あなた自身が脅されたり、圧倒されたりしていると感じたら、私たちに知らせてください。プルリクエストにコメントするか、[Discord で QMK チームに連絡を取ってください](https://discord.gg/Uq7gcHh)。 |