Swift 4.2 日本語化計画　: Swift 4.2

投稿

誰でもが Swift に投稿することを歓迎します。投稿とは、プルリクエストを提出するだけではなく、フォーラムの質問に答え、バグを報告またはトリアージし、Swift 発展プロセスに参加するなどを含む、さまざまな方法で参加できます。

どのように参加したいのかにかかわらず、コミュニティガイドラインを読んで、プロジェクトに参加している人に何が期待されているのかを最初に知ることを願っています。ソースコードで説明しているように、コードを投稿している場合は、リポジトリから Swift をビルドして実行する方法も知っておく必要があります。

質問に答える

コミュニティーをサポートできる最も重要かつ即効性のある方法の 1 つは、フォーラムの質問に答えることです。新人が言語機能を理解するのに役立つものであれ、経験豊富な開発者をトラブルシュートするのであれ、Swift の知識と経験は、他の人を助けるために長い道のりを歩むことができます。

バグを報告する

バグを報告することは、誰にとっても Swift の改善に役立つ素晴らしい方法です。オープンソースの Swift プロジェクトでは Jira を使ってバグを追跡しています。私たちの Jira インスタンスは bugs.swift.org にあります。

バグが Xcode プロジェクトやプレイグラウンド内でのみ再現できる場合、またはバグが Apple NDA に関連している場合は、代わりに Apple のバグ報告に報告してください。

新しい Swift のバグを提出するときは、以下を含めてください：

問題の簡潔な説明。 問題がクラッシュの場合は、スタックトレースを含めて下さい。それ以外の場合は、実際に観察された動作と一緒に、したいと思っていた動作を記述します。

再現可能なテストケース。 テストケースが小さい場合 (たとえば、20 行未満のコード) は、問題の説明フィールドに直接ペースとして下さい。それ以外の場合は、Jira の問題の添付ファイルとしてアップロードしてください。

問題を再現する環境の説明。 Swift ビルド番号、ターゲット OS とプラットフォームに関する情報を含めてください。

Swift は非常に積極的に開発されているため、多くのバグ報告があります。新しい問題を提出する前に、既存の問題を閲覧して、重複していないことを確認してください。

新しい言語機能を要求する問題を提出する前に、Swift 発展プロセスへの参加を参照してください。

バグのトリアージ

バグを報告することは、ソフトウェアを改善する上で重要な部分です。ほぼ同じくらい重要なのは、それらのバグが再現性があり、小さく、ユニークであることを確認し、トリアージすることです。

bug tracker でバグをトリアージするのに役立ついくつかのことがあります。

バグを再現する。 バグを実行可能にするには、再現可能である必要があります。バグを再現できない場合は、その理由を調べてみてください。詳細が必要な場合は、提出者 (submitter) に連絡してください。

バグを減らす。 バグを再現できるようになったら、できるだけコードの量を減らしてバグを減らしてください。Swift コードのほんの数行でバグを再現するサンプルについての推論は、より長いサンプルについての推論よりも簡単です。

重複するバグを排除する。 2 つのバグレポートが同じ根本的な問題を参照している場合は、新しいものを古いものの重複としてマークします。そうすることで他の人がより効果的に働くことができます。

コードの投稿

段階的な開発

Swift プロジェクトは、好ましい開発モデルとして 小規模で段階的な変更 を使用します。時にはこれらの変更は小さなバグ修正です。他の時には、これらの変更は、より大きな目標を達成するための道のりに沿った小さなステップです。これとは対照的に、長期的な開発部門は開発中に声を出さずにコミュニティを離れることができます。長期的な部門に関するいくつかの追加の問題には、以下の物が含まれます：

開発部門と主要の開発部門が同じコードで実行される場合、コンフリクトの結合の解決に多くの時間がかかる可能性があります。
コミュニティの人々は分岐での作業を無視する傾向があります。
非常に大きな変更はコードレビューには難しい。
分岐は、継続的な統合インフラストラクチャによって定期的にテストされるわけではありません。

これらの問題に対処するために、Swift は段階的な開発スタイルを採用しています。可能な限りいつでも、小さな変更が好まれます。大規模な変更やその他の侵襲的な変更を行なう場合、寄稿者はこの慣行に従うことが必要です。いくつかのヒントを以下に示します。

大規模な変更や侵襲的な変更には、大規模な変更 (例えば、API の一掃や追加など) の前に行なわなければならない 2 次的な変更があります。主要な変更の前に、これらの変更をその作業とは別にコミットします。

可能であれば、関連する残りの作業を、無関係な変更セットに分解します。次に、最初の段階を定義し、変更の開発目標についてコンセンサスを得ます。

セット内の各変更を単独で (例えば、バグを修正するために)、または開発目標に向けて計画された一連の変更の一部にします。これらの関係をコミュニティに説明することは役に立ちます。

大きな変更を行ない、その全体的な効果が不明な場合は、まずその変更について話し合い、開発者のフォーラムを通じてコンセンサスを得てください。次に、変更を行なうための最良の方法について質問して下さい。

メッセージをコミットする

メッセージをコミットする形式を厳密にする必要はありませんが、オープンソースプロジェクト間で共通する以下のガイドラインに従うことをお勧めします。これらのガイドラインに従うことで、レビュープロセス、コミットログの検索、および電子メールの書式設定に役立ちます。高いレベルでは、コミットメッセージの内容は、詳細を掘り下げることなく、変更の論理的根拠を伝える必要があります。たとえば、"ビットが正しく (right) 設定されていない" とすると、レビュー担当者は、どのビットが、なぜ "右(right)" ではないのか不思議に思うでしょう。対照的に、"正しく計算するのは 'Type' 内のビットが'従属タイプです'" ということは、ほとんど全てが変更に反映されています。

以下は、メッセージ自体をコミットするフォーマットに関するいくつかのガイドラインです：

コミット・メッセージを単一行の タイトル と、変更を説明する別の本文に分けてください。
タイトルを簡潔にして、コミットログ内で簡単に読むことができ、コミット電子メールの件名に収まるようにします。
コードの特定の部分に限定された変更では、行の先頭に、例えば "[stdlib] ..." や "[SILGen] ..." などの角括弧で [tag] を含めて下さい。このタグは、電子メールフィルタとコミット後のレビューの検索に役立ちます。
本文がある場合は、タイトルから空の行で区切ります。
完全な推論を含めながら、本文を簡潔にします。変更を理解する必要がない限り、追加のコード例やその他の詳細はバグコメントやメーリングリストに残すべきです。
コミットがバグ追跡システムの問題を修正する場合は、メッセージ内に問題へのリンクを含めて下さい。
テキストの書式設定とスペルについては、ドキュメントやコード内のコメントと同じ規則に従ってください。たとえば、大文字とピリオドを使用します。
コミットが最近コミットされた別の変更の一番上にあるバグフィックスであるか、またはパッチを元に戻すか再適用する場合は、以前に関連するコミットの Git リビジョン番号を含めます。すなわち、"バグ＃を引き起こしたので、abcdef を元に戻します"。

これらのガイドラインに軽微に違反すると、コミュニティは通常、復帰以上のこのポリシーで投稿者を思い出させることを好みます。軽度の訂正と省略は、コミットメーリングリストに返信することで処理できます。

変更の帰属

投稿者が Swift サブプロジェクトに変更を提出すると、その変更が承認された後、コミットアクセス権を持つ他の開発者が著者にコミットすることがあります。そうする際には、投稿の正確な帰属を保持することが重要です。一般的に言えば、Git は自動的に帰属を扱います。

私たちは、ソースコードが "このコードは J.Random Hacker によって書かれた" のようなランダムな帰属で散らばっているのを望まない、と言うのもこれはうるさくて気が散るからだ。ソースコードまたは文書に投稿者名を追加しないでください。

さらに、変更をプロジェクトに提出していない場合や、提出する権限がある場合でなければ (例えば、協力して会社が変更の提供を承認した場合など) は、他の人が作成した変更をコミットしないでください。作者はまず、プルリクエストを通じて変更を関連プロジェクトに提出するか、開発リストに電子メールするか、バグトラッカー項目を追加する必要があります。誰かがあなたに個人的に変更を送った場合、最初に適切なリストに提出するように勧めて下さい。

コードテンプレート

コミュニティガイドラインに記載したように、Swift.org のコードのライセンスと著作権保護は、すべてのソースコードファイルの先頭に表示されます。ごくまれに、新しいソースファイルを含む変更を投稿した場合は、ヘッダーが適切に記入されていることを確認してください。

Swift ソースファイルの場合、コードヘッダーは以下のようになります。

// subfolder/Filename.swift - Very brief description
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2018 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
// -----------------------------------------------------------------------------
///
/// This file contains stuff that I am describing here in the header and will
/// be sure to keep up to date.
///
// -----------------------------------------------------------------------------

C または C++ ソースまたはヘッダーファイルの場合、コードヘッダーは以下のようになります。

//===-- subfolder/Filename.h - Very brief description -----------*- C++ -*-===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2018 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//
///
///\file
/// This file contains stuff that I am describing here in the header and will
/// be sure to keep up to date.
///
//===----------------------------------------------------------------------===//

区切り線は、コードスタイルのガイドラインを遵守するのに役立つように、正確に 80 文字であるべきです。一番下のセクションには、生成されたドキュメントのために意図されたオプションの説明が含まれています (これらの行は // ではなく /// で始まります)。説明がない場合、この領域はスキップできます。

コードのレビュー

Swift プロジェクトは、ソフトウェア品質を向上させるためにコードレビューに大きく依存しています。

すべての重要な変更は、すべての開発者により行われ、リポジトリにコミットする前に確認されなければなりません。小さな変更 (または開発者がコンポーネントを所有する変更) は、コミットされた後にレビューすることができます。
コードのレビューは GitHub で (プルリクエストやコミットに関するコメントを通じて) 実行され、関連するプロジェクトのコミットメーリングリストに反映されます。
コード変更を担当する開発者は、必要なレビュー関連の変更をすべて行う責任も負います。

コードのレビューは反復的なプロセスであり、変更がコミットされる準備が整うまで続きます。変更がレビューのために送信された後、提出される前に明示的な承認が必要です。デッドラインを設定して、沈黙での承認やパッチに対する積極的な反対を要求しないでください。

場合によっては、コードのレビューに望むより、特に大きな機能の場合時間がかかることがあります。パッチのレビュー時間を短縮するためのいくつかの方法があります：

他の人の変更をレビューする。 あなたが手伝ってくれれば、みんなあなたのために同じことをやりたいです。善意はわれわれの通貨です。
変更を複数の小さな変更に分割します。 あなたの変更が小さいほど、誰かがそれをすばやく見る確率が高くなります。
変更を ping します。 緊急の場合は、この変更を取得し、数日おきに ping することが重要である理由を記入してください。それが緊急でない場合、一般的な礼儀の ping 率は1週間です。他の専門の開発者から貴重な時間を求めていることを覚えておいてください。

誰でも変更をレビューしフィードバックを与えることはできますが、リポジトリへのコミットアクセス権を持つ人々のみが承認できます。

テスト

開発者は、修正されたバグや追加された新機能のテストケースを作成し、その変更と共にそれらについて投稿 (貢献) する必要があります。

すべての機能と回帰のテストケースは、適切なテストディレクトリ (たとえば、swift/test ディレクトリ) に追加されます。
実際の機能に最も近い抽象レベルでテストケースを記述します。たとえば、Swift 言語機能の場合は Swift で、それが SIL 最適化の場合は、SIL で記述します。
可能な限りテストケースを減らします。特に回帰テストの場合。失敗したプログラム全体を swift/test に入れることは、すべての開発者のテストが遅くなるため、受け入れられません。短くしてください。

品質

人々は Swift に依存してプロダクションソフトウェアを作成しています。これは、Swift のバグが何千もの開発者の製品の何百万というバグを引き起こす可能性があることを意味します。このため、Swift プロジェクトは質の高い基準を維持しています。主な開発拠点にコミットする前に、変更が満たすべき最低限の品質基準は以下のとおりです。

コードは、少なくとも 1 つのプラットフォームでエラーまたは警告なしにコンパイルできなければなりません。
バグの修正や新機能には、将来の回帰を特定するためのテストケースが含まれてなければならず、また、テストケースが実際的でない理由を正当化する必要もあります。
コードは適切なテストスイート (例えば、Swift コンパイラの Swift/test および Swift/validation-test テストスイートなど) に合格しなければなりません。

さらに、コミットする人は、将来発生する可能性のある問題に対処する責任があります。この責任は、以下の目的で変更を更新する必要があることを意味します。

コードがすべての一次プラットフォームで正常にコンパイルされるようにする
他のテストスイートで見つかった正確さの低下を修正する
主要なパフォーマンス低下を修正する
ダウンストリームの Swift ツールでのパフォーマンスや正確さの低下を修正する
Swift を使用する顧客コードでもたらされるパフォーマンスや正確さの低下を修正する
変更の結果としてバグトラッカーに表示されるバグに対処する

これらの問題は提出前に処理することをお勧めしますが、すべての提出についてこれをすべてテストすることはできません。当社の継続的統合 (CI) インフラストラクチャは、通常、これらの問題を認識します。低下を検索するために、翌日まで CI インフラストラクチャを監視することをお勧めします。CI インフラストラクチャは、あなた自身を含むコミットのグループが失敗を引き起こした場合に、あなたに直接電子メールを送ります。これらのメッセージを確認して、あなたの責任であるかどうかを確認し、もしそうであれば、破損を修正することが期待されます。

これらの品質基準に明確に違反しているコミットは、特に変更によって他の開発者が進展を妨げる場合に、元に戻すことができます。開発者は、問題が修正された後で変更を再開 (recommit) することを歓迎します。

コミットアクセス

高品質の変更を提出した実績がある投稿者にコミットアクセス権が与えられます。コミットアクセスを希望する場合は、使用したい GitHub ユーザ名と変更なしで受け入れた 5 つの軽微でないプルリクエストのリストを電子メールでコードオーナーのリストに送ってください。

コミットアクセスが一度許可されると、Swift.org プロジェクトをホストするすべての GitHub リポジトリにコミットできます。コミットアクセスが機能していることを確認するには、テストコミットを行って下さい (たとえば、コメントを変更するか空白行を追加するなど)。コミットアクセスを持つユーザーには、以下のポリシーが適用されます。

あなたは Swift のすべての部分に対して承認後コミットを与えられます。承認を受けるには、プルリクエストを作成します。リクエストが承認されたら、自分で統合することができます。

最初に承認を得ることなく、明らかな変更をコミットすることができます。コミュニティは、あなたが良い判断をすることを期待しています。例としては明らかに壊れたパッチを修正し、コードコメントやその他の小さな変更を修正することです。

あなたが投稿した Swift の部分に、またはあなたが責任を持っている Swift の部分に承認なしで変更する事にコミットできます。そのようなコミットは、ビルドを壊してはいけません。これは "信頼するが検証する" ポリシーであり、この性質のコミットはコミット後にレビューされます。

これらのポリシーに複数の違反や重大な違反があると、コミットアクセスが取り消される可能性があります。コミットアクセスであっても、変更内容は引き続きコードのレビューの対象となります。もちろん、他の人の変更を見直すことも奨励されます。

外部ライブラリ依存関係の追加

Swift プロジェクト (コンパイラ、コアライブラリなど) の 1 つが、特定のプラットフォーム上での機能を提供するライブラリを使用するのが適切な場合があります。ライブラリの依存関係を追加すると、Swift プロジェクトの移植性に影響を与え、法律上の問題も含まれる可能性があります。

原則として、すべての新しいライブラリ依存関係は、プロジェクトリーダーが明示的に承認しなければなりません。

Swift 発展プロセスへの参加

良いアイデアを持っていれば誰でも、将来の言語の特徴や方向性を形作るのに役立ちます。問題に対する最善の解決策を得るために、私たちはパブリックフォーラムでアイデアを繰り返し議論します。提案が洗練されて承認されると、それはリリースの目標になり、Swift の次のバージョンの機能として追跡されます。

このプロセスをサポートするため、Swift Evolution repository は、今後のメジャーリリースおよびマイナーリリース (コアチームが定義したもの) の目標と Swift の変更への提案を収集します。Swift 発展プロセス文書では、アイデアがいかに提案され、議論され、レビューされ、また今後のリリースとして最終的に承認されているかについて詳しく説明しています。

現在および今後の提案のレビューについては、Swift 発展レビューのスケジュールを参照してください。

LLVM と Swift

Swift は LLVM Compiler Infrastructure 上でビルドされています。Swift は、コード生成と最適化 (他の物に比べとりわけ) のため LLVM コア、C と Objective-C との相互運用性のための Clang、デバッグのための LLDB と REPL を使用しています。

Swift は、GitHub の LLVM Core、Clang、LLDB ソースリポジトリのクローンをそれぞれ swift-llvm、swift-clang、swift-lldb として維持しています。これらのリポジトリは、上流の LLVM 開発を追跡し、Swift の追加の変更を含んでいます。上流の LLVM リポジトリは、Swift 固有のリポジトリに頻繁に結合されます。上流の LLVM と Swift クローンの違いを最小限に抑えるために、Swift に特に必要とされる変更のみにしようという試みがなされています。

LLVM の変更はどこで行われますか？

Swift は、実行可能な最も上流のリポジトリに変更を加える方針に従います。Swift のバージョンの LLVM、Clang、または LLDB の Swift への投稿は、Swift　特有のものでない限り、上流の LLVM リポジトリに直接移動する必要があります。たとえば、Swift タイプの LLDB のデータフォーマッタへの改善は Swift LLDB リポジトリに属しますが、LLVM 最適化へのバグ修正は Swift で生成された LLVM IR で動作する場合にのみ観察されているものであっても、上流の LLVM に属します。

上流の LLVM リポジトリへのコミットは、対応する Swift リポジトリ (swift-llvm および swift-clang リポジトリの upstream-with-swift、swift-lldb リポジトリの upstream) の適切な上流分岐に自動的に結合されます。Swift コンパイラと LLDB のワークフローは少し異なります。

Swift コンパイラでは、swift-llvm、swift-clang、および swift-lldb の upstream-with-swift 分岐には、最新の上流 LLVM ソースと、Swift 固有の変更と追加が含まれています。(ほとんどの Swift 開発が発生する) stable 分岐は、定期的に upstream-with-swift から再分岐されます。その間に、重要なコミットは、llvm.org から upstream-with-swift に、そして stable に用心深く選別されるべきです。

Swift と LLVM 開発者ポリシー

Swift の LLVM または Clang クローンへの投稿は、LLVM　開発者ポリシーに準拠しており、適切なライセンスおよびコーディング基準に従う必要があります。LLVM コードに関する問題は、LLVM バグデータベースを使用して追跡されます。LLDB の場合、llvm.org のコメントヘッダーを持つファイルへの変更は、llvm.org の上流の LLDB に移動しなければならず、LLVM 開発者ポリシーと LLDB コーディング規約に従わなければなりません。LLDB の Swift 固有の部分 (つまり、Swift.org のコメントヘッダーを持つ部分) への投稿は Swift ライセンスを使用しますが、LLDB のコーディング規則に従います。

Swift 4.2 日本語化計画 : Swift 4.2

投稿