CONTRIBUTING.md

コントリビューションガイド

基本的には「本リポジトリのコンセプト」を守るようにしてください。 コミットする前に、余裕があれば読み返して推敲してください。
その他は時間があれば読んでください。
慎重になりすぎる必要はありません。 気づいた人が後から直しましょう。

コンフリクトを避けるため、Projectsページを利用してタスクを管理しています。 作業予定のタスクは「To Do」に、作業中のタスクは「In Progress」にIssueとして登録し、他の人が作業中のタスクを推めることは避けてください。
作業中のタスクのマージが終わりましたら、「Done」に登録してください。
それぞれのタスクに関する議論は対応するIssue内で行ってください。

本リポジトリのコンセプト

読み手を意識する

本リポジトリでは、プログラミングの経験がない、またはほとんどない人を対象としています。 専門用語や一部の人にしか分からない用語の使用は避け、できるだけ優しい言葉を使ってください。
また、「なぜそうするのか？」「なぜそれでうまくいくのか？」など、「なぜ」を大切にします。

コードを書きながら学べる

コードを書きながら学べるコンテンツを目指します。 文章と同等量のコードを載せるようにしてください。また、積極的にコメント文を使ってください。
質の悪いコードは載せないようにします。 PEP8を遵守してください。

ミニマルに

各項目について詳細すぎる説明はしません。 深く学ぶための優れた書籍は他にたくさんあります。
また、海外製の技術書等でよく見られるようなジョークやコラム、豆知識など、本筋から逸れた記述は極力無くします。マニアックな記述をする必要はありません。

混乱させない

表現を統一し、より良い表現を常に追求します。
独自に作った略語を使わないようにします。 一般的に使われている略語を使う分には問題ありませんが、事前に定義してください。
「※」を使った脚注など、文章を読む流れを妨げる構成は避けてください。 そもそも脚注が必要となるような難しい言葉は使わないでください。 また、詳細すぎる説明になっている可能性も同時に疑ってください。

表現に関するルール

基本的には他の文章と比べて違和感がないようにしていただければ良いです。 細かい部分は個人のセンスに任せます。
テンプレートを用意しています。
VS Codeの拡張機能であるテキスト公正くんを使うことを推奨します。 設定は、VS Codeの拡張機能「テキスト校正くん」の設定方法を参照してください。

です・ます調

文末は基本的に「〜です」「〜ます」としてください。 他にも、「〜ました」や「〜ください」、「～ありません」といった表現が利用できます。

句読点

日本語の文脈では、「。」「、」を基本としてください。
論文等で扱われる「.」「,」を日本語の文脈で使うことは避けてください。堅い印象を読者に与える可能性があります。

全角と半角の使い分け

日本語の文脈では全角を、英語の文脈では半角を使ってください。 半角カナと全角英数、全角スペースは利用しないでください。

括弧の使い分け

日本語の文脈で利用する括弧は、全角カギ括弧「」または全角丸括弧（）のみとしてください。
英語の文脈で利用する括弧は、半角丸括弧 () のみとしてください。

十分な余白を設ける

理解を促進するためのさまざまな効果を得るために、余白は重要です。 効果的に空白行や改行、半角スペースを使ってください。
また、長い文章は読みやすさを低下させます。 1つの段落は2、3行程度とし、適宜改行や小見出し、箇条書きを使ってください。
文章中に半角の英数字や括弧が出現する場合は、見やすさを考慮して適宜半角スペースを入れてください。

相対的な位置の参照方法

文章に対する相対的な位置の指し示す場合は、極力「次の〜」といったように事前に説明してください。 「上記の〜」といった表現を使うことは避けてください。

隠蔽文字の書き方

パスワードやユーザー名など、隠蔽したい文字を書く場合には、不等号 <> で囲んでください。
次に例を示します。

# 設定ファイルなどで記述する例
USER: <user_name>
PASSWORD: <password>

サンプルコードの書き方

シェルの場合、コマンドの入力と出力が明確にわかるように、コマンド入力の先頭に「>」を挿入してください。
出力が長い場合には「...」を用いて省略できます。

> echo "Hello World!"
Hello World!

> cat sample.txt # sample.txtの内容を表示する
hogehoge
...

ファイルの場合、先頭でコメント文を用いてファイル名を明示してください。 この際、通常のコメント文と区別するために、両端に「--」を挿入してください。
ファイルの内容が多い場合には「...」を用いて省略できます。

# -- /path/to/sample.py --

if __name__ == "__main__":

    # Hello World!を表示する
    print("Hello World!")
    ...

コミットに関するルール

基本的には過去のコミットと比べて違和感がないようにしていただければ良いです。

コミットメッセージ

フォーマットは基本的に次のようにします。

[prefix]: [本文]

prefixはこだわりがなければ次の表を参照してください。 Emoji prefixなどを使っていただいても構いません。

prefix	説明
Add:	新規ファイルを作成した / 作成と同時に編集した
Update:	ファイルの内容を編集した / 機能を追加・削除した
Fix:	誤字脱字や体裁などに関する軽微な修正をした
Move:	ファイルを移動した / ファイル名を変更した
Remove:	ファイル自体を削除した

本文は日本語で書いてください。 長くても20文字程度で良いです。
5W1Hなど、厳密すぎる必要はありません。 体裁はとくに指定しません。

コミットの粒度

機能のまとまりごとにコミットしてください。
異なる種類のコミットが混在しないようにしてください。初めにコミットメッセージ考え、それを起点に対象のファイルをステージングすることで上手くいくはずです。