From a860da891497afc536d6248fad35dff5fb782472 Mon Sep 17 00:00:00 2001 From: umi <57262844+umi-umi@users.noreply.github.com> Date: Tue, 17 Dec 2019 14:01:46 +0900 Subject: [PATCH] [Docs] add japanese translation (basic part) (#7461) * add basic part * update cli * update cli * correct links to ja document * update files based on comments * update for a postpositional particle * update for a punctuation * update files based on comments * update files based on comments * update files based on comments * update files based on comments * update files based on comments * update files based on comments * update files based on comments Co-Authored-By: shela Co-Authored-By: Takeshi ISHII <2170248+mtei@users.noreply.github.com> --- docs/ja/cli.md | 227 ++++++++++++++++++++++++ docs/ja/cli_configuration.md | 126 +++++++++++++ docs/ja/contributing.md | 173 ++++++++++++++++++ docs/ja/getting_started_getting_help.md | 20 +++ docs/ja/getting_started_github.md | 64 +++++++ docs/ja/getting_started_introduction.md | 65 +++++++ 6 files changed, 675 insertions(+) create mode 100644 docs/ja/cli.md create mode 100644 docs/ja/cli_configuration.md create mode 100644 docs/ja/contributing.md create mode 100644 docs/ja/getting_started_getting_help.md create mode 100644 docs/ja/getting_started_github.md create mode 100644 docs/ja/getting_started_introduction.md diff --git a/docs/ja/cli.md b/docs/ja/cli.md new file mode 100644 index 000000000..3cc58e1f0 --- /dev/null +++ b/docs/ja/cli.md @@ -0,0 +1,227 @@ +# QMK CLI + + + +このページは QMK CLI のセットアップと使用方法について説明します。 + +# 概要 + +QMK CLI を使用すると QMK キーボードの構築と作業が簡単になります。QMK ファームウェアの取得とコンパイル、キーマップの作成などのようなタスクを簡素化し合理化するためのコマンドを多く提供します。 + +* [グローバル CLI](#global-cli) +* [ローカル CLI](#local-cli) +* [CLI コマンド](#cli-commands) + +# 必要事項 + +CLI は Python 3.5 以上を必要とします。我々は必要事項の数を少なくしようとしていますが、[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) にリストされているパッケージもインストールする必要があります。 + +# グローバル CLI :id=global-cli + +QMK は、QMK ビルド環境のセットアップ、QMK の操作、および `qmk_firmware` の複数のコピーの操作を容易にできるインストール可能な CLI を提供します。これを定期的にインストールおよび更新することをお勧めします。 + +## Homebrew を使ったインストール (macOS、いくつかの Linux) + +[Homebrew](https://brew.sh) をインストールしている場合は、タップして QMK をインストールすることができます: + +``` +brew tap qmk/qmk +brew install qmk +export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します +qmk setup # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします +``` + +## easy_install あるいは pip を使ってインストール + +上のリストにあなたのシステムがない場合は、QMK を手動でインストールすることができます。最初に、python 3.5 (以降)をインストールしていて、pip をインストールしていることを確認してください。次に以下のコマンドを使って QMK をインストールします: + +``` +pip3 install qmk +export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します +qmk setup # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします +``` + +## 他のオペレーティングシステムのためのパッケージ + +より多くのオペレーティングシステム用に `qmk` パッケージを作成および保守する人を探しています。OS 用のパッケージを作成する場合は、以下のガイドラインに従ってください: + +* これらのガイドラインと矛盾する場合は、OS のベストプラクティスに従ってください + * 逸脱する場合は、理由をコメントに文章化してください。 +* virtualenv を使ってインストールしてください +* 環境変数 `QMK_HOME` を設定して、ファームウェアソースを `~/qmk_firmware` 以外のどこかにチェックアウトするようにユーザに指示してください。 + +# ローカル CLI :id=local-cli + +グローバル CLI を使いたくない場合は、`qmk_firmware` に付属のローカル CLI があります。`qmk_firmware/bin/qmk` で見つけることができます。任意のディレクトリから `qmk` コマンドを実行でき、常に `qmk_firmware` のコピー上で動作します。 + +**例**: + +``` +$ ~/qmk_firmware/bin/qmk hello +Ψ Hello, World! +``` + +## ローカル CLI の制限 + +グローバル CLI と比較して、ローカル CLI には幾つかの制限があります: + +* ローカル CLI は `qmk setup` あるいは `qmk clone` をサポートしません。 +* 複数のリポジトリがクローンされている場合でも、ローカル CLI は常に `qmk_firmware` ツリー上で動作します。 +* ローカル CLI は virtualenv で動作しません。そのため依存関係が競合する可能性があります + +# CLI コマンド :id=cli-commands + +## `qmk cformat` + +このコマンドは clang-format を使って C コードを整形します。引数無しで実行して全てのコアコードを整形するか、コマンドラインでファイル名を渡して特定のファイルに対して実行します。 + +**使用法**: + +``` +qmk cformat [file1] [file2] [...] [fileN] +``` + +## `qmk compile` + +このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。 からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルすることができます。 + +**Configurator Exports での使い方**: + +``` +qmk compile +``` + +**キーマップでの使い方**: + +``` +qmk compile -kb -km +``` + +## `qmk flash` + +このコマンドは `qmk compile` に似ていますが、ブートローダを対象にすることもできます。ブートローダはオプションで、デフォルトでは `:flash` に設定されています。 +違うブートローダを指定するには、`-bl ` を使ってください。利用可能なブートローダの詳細については、 +を見てください。 + +**Configurator Exports での使い方**: + +``` +qmk flash -bl +``` + +**キーマップでの使い方**: + +``` +qmk flash -kb -km -bl +``` + +**ブートローダのリスト** + +``` +qmk flash -b +``` + +## `qmk config` + +このコマンドにより QMK の挙動を設定することができます。完全な `qmk config` のドキュメントについては、[CLI 設定](ja/cli_configuration.md)を見てください。 + +**使用法**: + +``` +qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] +``` + +## `qmk docs` + +このコマンドは、ドキュメントを参照または改善するために使うことができるローカル HTTP サーバを起動します。デフォルトのポートは 8936 です。 + +**使用法**: + +``` +qmk docs [-p PORT] +``` + +## `qmk doctor` + +このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。 + +**使用法**: + +``` +qmk doctor +``` + +## `qmk json-keymap` + +QMK Configurator からエクスポートしたものから keymap.c を生成します。 + +**使用法**: + +``` +qmk json-keymap [-o OUTPUT] filename +``` + +## `qmk kle2json` + +このコマンドにより、生の KLE データから QMK Configurator の JSON へ変換することができます。絶対パスあるいは現在のディレクトリ内のファイル名のいずれかを受け取ります。デフォルトでは、`info.json` が既に存在している場合は上書きしません。上書きするには、`-f` あるいは `--force` フラグを使ってください。 + +**使用法**: + +``` +qmk kle2json [-f] +``` + +**例**: + +``` +$ qmk kle2json kle.txt +☒ File info.json already exists, use -f or --force to overwrite. +``` + +``` +$ qmk kle2json -f kle.txt -f +Ψ Wrote out to info.json +``` + +## `qmk list-keyboards` + +このコマンドは現在 `qmk_firmware` で定義されている全てのキーボードをリスト化します。 + +**使用法**: + +``` +qmk list-keyboards +``` + +## `qmk new-keymap` + +このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。 + +**使用法**: + +``` +qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] +``` + +## `qmk pyformat` + +このコマンドは `qmk_firmware` 内の python コードを整形します。 + +**使用法**: + +``` +qmk pyformat +``` + +## `qmk pytest` + +このコマンドは python のテストスィートを実行します。python コードに変更を加えた場合、これの実行が成功することを確認する必要があります。 + +**使用法**: + +``` +qmk pytest +``` diff --git a/docs/ja/cli_configuration.md b/docs/ja/cli_configuration.md new file mode 100644 index 000000000..ce9746479 --- /dev/null +++ b/docs/ja/cli_configuration.md @@ -0,0 +1,126 @@ +# QMK CLI 設定 + + + +このドキュメントは `qmk config` がどのように動作するかを説明します。 + +# はじめに + +QMK CLI の設定はキーバリューシステムです。各キーはピリオドで区切られたサブコマンドと引数名で構成されます。これにより、設定キーと設定された引数の間で簡単かつ直接的な変換が可能になります。 + +## 簡単な例 + +例として、`qmk compile --keyboard clueboard/66/rev4 --keymap default` コマンドを見てみましょう。 + +設定から読み取ることができる2つのコマンドライン引数があります: + +* `compile.keyboard` +* `compile.keymap` + +これらを設定してみましょう: + +``` +$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default +compile.keyboard: None -> clueboard/66/rev4 +compile.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +これで、毎回キーボードとキーマップを設定することなく、`qmk compile` を実行することができます。 + +## ユーザデフォルトの設定 + +複数のコマンド間で設定を共有したい場合があります。例えば、いくつかのコマンドは引数 `--keyboard` を受け取ります。全てのコマンドでこの値を設定する代わりに、その引数を受け取る全てのコマンドで使われるユーザ値を設定することができます。 + +例: + +``` +$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default +user.keyboard: None -> clueboard/66/rev4 +user.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +# CLI ドキュメント (`qmk config`) + +`qmk config` コマンドは基礎となる設定とやり取りするために使われます。引数無しで実行すると、現在の設定を表示します。引数が指定された場合、それらは設定トークンと見なされます。設定トークンは以下の形式の空白を含まない文字列です: + + [.][=] + +## 設定値の設定 + +設定キーに等号 (=) を入れることで、設定値を設定することができます。キーは常に完全な `
.` 形式である必要があります。 + +例: + +``` +$ qmk config default.keymap=default +default.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +## 設定値の読み込み + +設定全体、単一のキー、あるいはセクション全体の設定値を読み取ることができます。1つ以上の値を表示するために複数のキーを指定することができます。 + +### 全体の構成例 + + qmk config + +### セクション全体の例 + + qmk config compile + +### 単一キーの例 + + qmk config compile.keyboard + +### 複数キーの例 + + qmk config user compile.keyboard compile.keymap + +## 設定値の削除 + +設定値を特別な文字列 `None` に設定することで、設定値を削除することができます。 + +例: + +``` +$ qmk config default.keymap=None +default.keymap: default -> None +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +## 複数の操作 + +複数の読み込みおよび書き込み操作を1つのコマンドに組み合わせることができます。それらは順番に実行および表示されます: + +``` +$ qmk config compile default.keymap=default compile.keymap=None +compile.keymap=skully +compile.keyboard=clueboard/66_hotswap/gen1 +default.keymap: None -> default +compile.keymap: skully -> None +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +# ユーザ設定オプション + +| キー | デフォルト値 | 説明 | +|-----|---------------|-------------| +| user.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) | +| user.keymap | None | キーマップ名 (例: `default`) | +| user.name | None | ユーザの github のユーザ名。 | + +# 全ての設定オプション + +| キー | デフォルト値 | 説明 | +|-----|---------------|-------------| +| compile.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) | +| compile.keymap | None | キーマップ名 (例: `default`) | +| hello.name | None | 実行時の挨拶の名前 | +| new_keyboard.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) | +| new_keyboard.keymap | None | キーマップ名 (例: `default`) | diff --git a/docs/ja/contributing.md b/docs/ja/contributing.md new file mode 100644 index 000000000..d1b28b1f5 --- /dev/null +++ b/docs/ja/contributing.md @@ -0,0 +1,173 @@ +# 貢献方法 + + + +👍🎉 まず、これを読み貢献する時間を作ってくれてありがとうございます！🎉👍 + +サードパーティの貢献は、QMK の成長と改善に役立ちます。プルリクエストと貢献プロセスを貢献者とメンテナの両方にとって便利で簡単なものにしたいです。この目的のために、大きな変更をせずにプルリクエストが受け入れられるように貢献者向けのガイドラインをまとめました。 + +* [プロジェクトの概要](#project-overview) +* [コーディング規約](#coding-conventions) +* [一般的なガイドライン](#general-guidelines) +* [行動規範は私にとって何を意味しますか？](#what-does-the-code-of-conduct-mean-for-me) + +## この全てを読みたくはありません！単純に質問があります！ + +QMK について質問したい場合は、[OLKB Subreddit](https://reddit.com/r/olkb) あるいは [Discord](https://discord.gg/Uq7gcHh) ですることができます。 + +以下の事を覚えておいてください: + +* 誰かがあなたの質問に答えるのに数時間掛かるかもしれません。しばらくお待ちください！ +* QMK に関わる全ての人が彼らの時間とエネルギーを提供しています。QMK に関する作業や質問への回答に対する報酬はありません。 +* できるだけ簡単に答えられるように質問してみてください。その方法が分からない場合は、以下に幾つかの良いガイドがあります: + * https://opensource.com/life/16/10/how-ask-technical-questions + * http://www.catb.org/esr/faqs/smart-questions.html + +# プロジェクトの概要 :id=project-overview + +QMK は主に C で書かれており、特定の機能と部品は C++ で書かれています。QMK は、キーボードの中の組み込みプロセッサ、特に AVR ([LUFA](http://www.fourwalledcubicle.com/LUFA.php)) と ARM ([ChibiOS](http://www.chibios.com)) を対象にしています。すでに Arduino プログラミングに精通している場合は、多くの概念と制限がおなじみのものです。QMK に貢献するには Arduino を使用した経験は必要ありません。 + + + +# どこで助けを得られますか？ + +助けが必要であれば、[issue を開く](https://github.com/qmk/qmk_firmware/issues) か [Discord で会話する](https://discord.gg/Uq7gcHh)ことができます。 + +# どうやって貢献することができますか？ + +以前にオープンソースに貢献したことはありませんか？ QMK で貢献がどのように機能するかが疑問ですか？ ここに簡単な説明があります！ + +0. [GitHub](https://github.com) アカウントにサインアップします。 +1. 貢献するためのキーマップをまとめるか、解決に興味がある[問題を見つける](https://github.com/qmk/qmk_firmware/issues)、あるいは追加したい[機能](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)を見つけます。 +2. 問題に関連付けられているリポジトリをあなたの GitHub アカウントにフォークします。これは、`GitHub上のあなたのユーザー名/qmk_firmware` の下にリポジトリのコピーを持つことを意味します。 +3. `git clone https://github.com/GitHub上のあなたのユーザー名/repository-name.git` を使ってローカルマシンにリポジトリをクローンします。 +4. 新しい機能に取り組んでいる場合は、issue を開きこれから行う作業について話し合うことを検討してください。 +5. `git checkout -b branch-name-here` を使って修正用の新しいブランチを作成します。 +6. 解決しようとしている問題、あるいは追加したい機能について適切な変更を加えます。 +7. `git add insert-paths-of-changed-files-here` を使って変更されたファイルの内容を git がプロジェクトの状態を管理するために使用する "snapshot"、インデックスとしても知られている、に追加します。 +8. `git commit -m "Insert a short message of the changes made here"` を使って、説明的なメッセージとともにインデックスの内容を保存します。 +9. `git push origin branch-name-here` を使って GitHub 上のリポジトリに変更をプッシュします。 +10. プルリクエストを [QMK Firmware](https://github.com/qmk/qmk_firmware/pull/new/master) にサブミットします。 +11. 行われた変更の簡単な説明と、変更に関する問題またはバグ番号を使って、プルリクエストにタイトルを付けます。例えば、issue に "Added more log outputting to resolve #4352" のようなタイトルをつけることができます。 +12. プルリクエストの説明では、行った変更、行ったプルリクエストに存在すると思われる問題、およびメンテナに対する質問を説明します。プルリクエストが完ぺきではない場合(プルリクエストが無い場合)でも問題ありません。レビュワーが問題の修正と改善を手伝います。 +13. プルリクエストがメンテナによってレビューされるのを待ちます。 +14. レビューをしているメンテナが変更を推奨する場合は、プルリクエストに変更を加えます。 +15. プルリクエストがマージされた後で成功を祝います！ + +# コーディング規約 :id=coding-conventions + +私たちのスタイルのほとんどは簡単に理解できます。C あるいは Python のいずれかに精通している場合は、ローカルスタイルにそれほど問題はないはずです。 + +* [コーディング規約 - C](ja/coding_conventions_c.md) +* [コーディング規約 - Python](ja/coding_conventions_python.md) + +# 一般的なガイドライン :id=general-guidelines + +QMK には幾つかの異なるタイプの変更があり、それぞれ異なるレベルの厳密さが必要です。どのような種類の変更を行っても、次のガイドラインに留意してください。 + +* PR を論理単位に分割します。例えば、2つの個別の機能をカバーする1つの PR を送信するのではなく、代わりに機能ごとに個別の PR をサブミットします。 +* コミットする前に、`git diff --check` を使って不要な空白を確認します。 +* コードの変更が実際にコンパイルされることを確認してください。 + * キーマップ: `make keyboard:your_new_keymap` がエラーを返さないことを確認してください。 + * キーボード: `make keyboard:all` がエラーを返さないことを確認してください。 + * コア: `make all` がエラーを返さないことを確認してください。 +* コミットメッセージがそれ自体で理解できることを確認してください。最初の行に短い説明(70文字以内)を入れ、2行目は空にし、3行目以降では必要に応じてコミットを詳細に説明する必要があります。例: + +``` +kerpleplork の fronzlebop を調整します + +kerpleplork はエラーコード 23 で連続的に失敗していました。根本的な原因は fronzlebop 設定で、これにより kerpleplork はN回の繰り返しごとにアクティブになります。 + +私が使用できるデバイスの限られた実験では、kerpleplork の混乱を避けるために 7 は十分高い値であることを示していますが、念のため ARM デバイスを持つ人たちからフィードバックを得たいです。 +``` + +!> **重要:** デフォルト以外のキーマップ、ユーザスペースおよびレイアウトのようなユーザコードへのバグ修正あるいは改善に貢献したい場合は、PR にコードの元の提出者にタグをつけてください。Git と GitHub のスキルレベルに関係なく、多くのユーザは知らないうちにコードが変更されることに混乱したりイライラしたりするかもしれません。 + +## ドキュメント + +ドキュメントは QMK への貢献を始める最も簡単な方法の1つです。ドキュメントが間違っているか不完全な場所を見つけ、これらを修正するのは簡単です！私たちもドキュメントを編集する人を非常に必要としています。編集するスキルがあるが、どこにどのように飛び乗ればいいのか分からない場合は、[助けをもとめて](#where-can-i-go-for-help)ください！ + +全てのドキュメントは `qmk_firmware/docs` ディレクトリの中にあります。あるいは web ベースのワークフローを使いたい場合は、http://docs.qmk.fm/ の各ページの上部にある "Suggest An Edit" をクリックすることができます。 + +ドキュメントの中にコードの例を提供する場合は、ドキュメント内の他の場所で使用されている命名規則を順守してください。例えば、一貫性を保つために、`my_layers` あるいは `my_keycodes` として列挙型を標準化します: + +```c +enum my_layers { + _FIRST_LAYER, + _SECOND_LAYER +}; + +enum my_keycodes { + FIRST_LAYER = SAFE_RANGE, + SECOND_LAYER +}; +``` + +### ドキュメントのプレビュー + +開発環境をセットアップした場合は、プルリクエストを開く前に以下のコマンドを `qmk_firmware/` フォルダから実行することで、あなたの変更をプレビューすることができます: + + ./bin/qmk docs + +または、Python 3 のみがインストールされている場合: + + python3 -m http.server 8936 + +その後、ウェブブラウザで、`http://localhost:8936/` を表示します。 + +## キーマップ + +ほとんどの初めての QMK 貢献者は、個人のキーマップから始めます。キーマップの標準はかなりカジュアルなものにしようとしています(キーマップは結局のところ作成者の性格を反映しています)が、他の人があなたのキーマップを簡単に見つけて学ぶことができるように、これらのガイドラインに従うようにお願いします。 + +* [the template](documentation_templates.md) を使って `readme.md` を書きます。 +* 全てのキーマップの PR は squash されるため、コミットがどのように squash されるかを気にする場合は、自分で行う必要があります。 +* キーマップの PR に機能をまとめないでください。最初に機能をサブミットし、次にキーマップのための2つ目の PR をサブミットします。 +* `Makefile` をキーマップフォルダに含めないでください(もう使われていません)。 +* ファイルヘッダの著作権を更新します (`%YOUR_NAME%` を探します) + +## キーボード + +キーボードは QMK の存在理由です。一部のキーボードはコミュニティによって管理されていますが、他のキーボードはそれぞれのキーボードを作成する責任者によって管理されています。`readme.md` を見るとそのキーボードを管理しているのが誰かが分かります。特定のキーボードに関する質問がある場合、[Issue を開いて](https://github.com/qmk/qmk_firmware/issues)質問にメンテナをタグ付けしてください。(訳注: タグ付け は [メンションする](https://help.github.com/ja/github/writing-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) という意味です。) + +また以下のガイドラインに従うことをお願いします: + +* [the template](ja/documentation_templates.md) を使って `readme.md` を書きます。 +* コミットの数を適切に保ってください。そうでなければあなたの PR を squash します。 +* コア機能を新しいキーボードにまとめないでください。最初に機能をサブミットし、次にキーボード用に別の PR をサブミットしてください。 +* `.c`/`.h` ファイルにすぐ上の親フォルダに従って名前を付けます。例えば、`/keyboards///.[ch]` +* `Makefile` をキーボードフォルダに含めないでください(もう使われていません) +* ファイルヘッダの著作権を更新します (`%YOUR_NAME%` を探します) + +## Quantum/TMK コア + +新しい機能をビルドするために多くの作業を行う前に、最適な方法で実装していることを確認する必要があります。[QMK の理解](ja/understanding_qmk.md)を読むことで、QMK の基本的な理解を得ることができます。これはあなたを QMK のプログラムフローのツアーに連れて行きます。ここから、あなたのアイデアを実装するための最良の方法の感覚をつかむために、私たちと話す必要があります。これを行うには主に2つの方法があります: + +* [Discord でのチャット](https://discord.gg/Uq7gcHh) +* [Issue を開く](https://github.com/qmk/qmk_firmware/issues/new) + +機能とバグ修正の PR は全てのキーボードに影響します。また、私たちは QMK の再編も進めています。このため、実装が行われる前に特に重要な変更について議論することが特に重要です。最初に私たちと話をせずに PR を開いた場合、あなたの選択が私たちの計画した方向とうまく合わない場合は幾つかの大きな再作業を行う覚悟をしてください。 + +機能やバグの修正に取り組む時に留意すべき幾つかの事があります。 + +* **デフォルトで無効** - QMK がサポートするほとんどのチップでメモリがかなり制限されており、現在のキーマップが壊れていないことが重要です。ですので、あなたの機能をオフにするのではなく**オン**にするようにしてください。デフォルトでオンにすべき場合、あるいはコードのサイズを小さくする必要がある場合は、相談してください。 +* **サブミットする前にローカルでコンパイル** - これが明白であることを願っていますが、コンパイルする必要があります。私たちの Travis システムは全ての問題をキャッチしますが、結果が返ってくるのを待つ代わりに幾つかのキーボードをローカルでコンパイルする方が一般的に速いです。 +* **リビジョンと異なるチップベースを考慮** - 僅かに異なる設定、さらには異なるチップベースを可能にするリビジョンを持つキーボードが幾つかあります。ARM および AVR でサポートされる機能を作成する、あるいは動作しないプラットフォームでは自動的に無効化するようにしてください。 +* **機能の説明** - 新しいファイルあるいは既存のファイルの一部として、`docs/` の中に文章化します。文章化しないと、他の人はあなたの苦労から利益を得ることができません。 + +また以下のガイドラインに従うことをお願いします: + +* コミットの数を適切に保ってください。そうでなければあなたの PR を squash します。 +* キーボードあるいはキーマップをコアの変更にまとめないでください。コアの変更を最初にサブミットしてください。 +* 機能のための[ユニット テスト](ja/unit_testing.md)を書いてください。 +* 編集しているファイルのスタイルに従ってください。スタイルが明確でないか、スタイルが混在している場合は、上記の[コーディング規約](#coding-conventions)に準拠する必要があります。 + +## リファクタリング + +QMK で物事がどのようにレイアウトされるかについて明確なビジョンを維持するために、私たちはリファクタリングを詳細に計画し、変更をする協力者がいます。リファクタリングのアイデアあるいは提案がある場合は、[issue を開いてください](https://github.com/qmk/qmk_firmware/issues)。QMK を改善する方法についてお話ししたいと思います。 + +# 行動規範は私にとって何を意味しますか？ :id=what-does-the-code-of-conduct-mean-for-me + +私たちの[行動規範](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md)は、身元に関係なくあなたがプロジェクトの全員を敬意と礼儀を持って扱う責任があることを意味します。あなたが行動規範に記載されている不適切な行動やコメントの被害者である場合は、私たちはあなたのためにここにおり、私たちのコードに従って虐待者が適切に懲戒されるように最善を尽くします。 diff --git a/docs/ja/getting_started_getting_help.md b/docs/ja/getting_started_getting_help.md new file mode 100644 index 000000000..83fbdc7bd --- /dev/null +++ b/docs/ja/getting_started_getting_help.md @@ -0,0 +1,20 @@ +# 助けを得る + + + +QMK に関して助けを得るための多くのリソースがあります。 + +## リアルタイム チャット + +メインの [Discord server](https://discord.gg/Uq7gcHh) で QMK の開発者とユーザを見つけることができます。サーバには、ファームウェア、Toolbox、ハードウェアおよび Configurator についてチャットするための特定のチャンネルがあります。 + +## OLKB Subreddit + +公式の QMK フォーラムは [reddit.com](https://reddit.com) の [/r/olkb](https://reddit.com/r/olkb) です。 + +## Github Issues + +[GitHub で issue](https://github.com/qmk/qmk_firmware/issues) を開くことができます。issue が長期的な議論あるいはデバッグを必要とする場合は、特に便利です。 diff --git a/docs/ja/getting_started_github.md b/docs/ja/getting_started_github.md new file mode 100644 index 000000000..e7af36efa --- /dev/null +++ b/docs/ja/getting_started_github.md @@ -0,0 +1,64 @@ +# QMK で Github を使う方法 + + + +Github は慣れていない人には少し注意が必要です - このガイドは、QMK におけるフォーク、クローン、プルリクエストのサブミットの各ステップについて説明します。 + +?> このガイドでは、あなたがコマンドラインでの実行にある程度慣れており、システムに git がインストールされていることを前提にしています。 + +[QMK Github ページ](https://github.com/qmk/qmk_firmware)を開くと、右上に "Fork" というボタンが見えます: + +![Git でのフォーク](http://i.imgur.com/8Toomz4.jpg) + +あなたが組織の一員である場合は、どのアカウントにフォークするかを選択する必要があります。ほとんどの場合、あなたの個人のアカウントにフォークしたいでしょう。フォークが完了したら(しばらく時間が掛かる場合があります)、"Clone or Download" ボタンをクリックします: + +![Git からダウンロード](http://i.imgur.com/N1NYcSz.jpg) + +必ず "HTTPS" を選択し、リンクを選択してコピーします: + +![HTTPS リンク](http://i.imgur.com/eGO0ohO.jpg) + +ここから、`git clone` をコマンドラインに入力し、リンクを貼り付けます: + +``` +user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git +Cloning into 'qmk_firmware'... +remote: Counting objects: 46625, done. +remote: Compressing objects: 100% (2/2), done. +remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623 +Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done. +Resolving deltas: 100% (29362/29362), done. +Checking out files: 100% (2799/2799), done. +``` + +ローカルマシンに QMK のフォークができるので、キーマップの追加、コンパイル、キーボードへの書き込みができます。変更に満足したら、以下のようにそれらをフォークへ追加、コミットおよびプッシュすることができます: + +``` +user@computer:~$ git add . +user@computer:~$ git commit -m "adding my keymap" +[master cccb1608] adding my keymap + 1 file changed, 1 insertion(+) + create mode 100644 keyboards/planck/keymaps/mine/keymap.c +user@computer:~$ git push +Counting objects: 1, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (1/1), done. +Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done. +Total 1 (delta 1), reused 0 (delta 0) +remote: Resolving deltas: 100% (1/1), completed with 1 local objects. +To https://github.com/whoeveryouare/qmk_firmware.git + + 20043e64...7da94ac5 master -> master +``` + +あなたの変更は今では Github 上のフォークにあります - フォーク (`https://github.com//qmk_firmware`)に戻ると、"New Pull Request" ボタンをクリックすることで新しいプルリクエストを作成することができます: + +![New Pull Request](http://i.imgur.com/DxMHpJ8.jpg) + +ここでは、コミットした内容を正確に確認することができます - 全て良いように見える場合は、"Create Pull Request" をクリックすることで最終的に承認することができます: + +![Create Pull Request](http://i.imgur.com/Ojydlaj.jpg) + +サブミットの後で、私たちはあなたの変更について話し、変更を依頼し、最終的にそれを受け入れるでしょう！QMK に貢献してくれてありがとう :) diff --git a/docs/ja/getting_started_introduction.md b/docs/ja/getting_started_introduction.md new file mode 100644 index 000000000..2752ea6a2 --- /dev/null +++ b/docs/ja/getting_started_introduction.md @@ -0,0 +1,65 @@ +# はじめに + + + +このページでは、QMK プロジェクトで作業するために知っておくべき基本的な情報について説明しようと思います。Unix シェルの操作に精通していることを前提としていますが、C について、または make を使ったコンパイルについて精通しているとは想定していません。 + +## 基本的な QMK の構造 + +QMK は [Jun Wako](https://github.com/tmk) の [tmk_keyboard](https://github.com/tmk/tmk_keyboard) プロジェクトのフォークです。変更された元の TMK コードは、`tmk_core` フォルダで見つけることができます。プロジェクトへの QMK の追加は、`quantum` フォルダで見つけることができます。キーボードプロジェクトは `handwired` および `keyboard` フォルダで見つけることができます。 + +### ユーザスペースの構造 + +`users` フォルダ内は各ユーザのためのディレクトリです。これはユーザがキーボード間で使うかもしれないコードを置くためのフォルダです。詳細は[ユーザスペース機能](ja/feature_userspace.md) のドキュメントを見てください。 + +### キーボードプロジェクトの構造 + +`keyboards` フォルダ、そのサブフォルダ `handwired`、ベンダと製品のサブディレクトリ (例えば、`clueboard`) の中には、各キーボードプロジェクトのためのディレクトリ (例えば `qmk_firmware/keyboards/clueboard/2x1800`) があります。その中には、以下の構造があります: + +* `keymaps/`: ビルドできる様々なキーマップ +* `rules.mk`: デフォルトの "make" オプションを設定するファイル。このファイルを直接編集しないでください。代わりにキーマップ固有の `rules.mk` を使ってください。 +* `config.h`: デフォルトのコンパイル時のオプションを設定するファイル。このファイルを直接編集しないでください。代わりにキーマップ固有の `config.h` を使ってください。 +* `info.json`: QMK Configurator のためのレイアウトの設定に使われるファイル。詳細は [Configurator サポート](ja/reference_configurator_support.md)を見てください。 +* `readme.md`: キーボードの簡単な概要 +* `.h`: このファイルは、キーボードのスイッチマトリックスに対してキーボードレイアウトが定義されるファイルです。 +* `.c`: このファイルには、キーボードのためのカスタムコードがあります。 + +プロジェクトの構造についての詳細は、[QMK キーボードガイドライン](ja/hardware_keyboard_guidelines.md)を見てください。 + +### キーマップ構造 + +全てのキーマップフォルダには、以下のファイルがあります。`keymap.c` だけが必須で、残りのファイルが見つからない場合は、デフォルトのオプションが選択されます。 + +* `config.h`: キーマップを設定するためのオプション +* `keymap.c`: 全てのキーマップコード。必須 +* `rules.mk`: 有効になっている QMK の機能 +* `readme.md`: キーマップの説明。他の人が使う方法および機能の説明。imgur のようなサービスに画像をアップロードしてください。 + +# `config.h` ファイル + +3つの `config.h` の場所が考えられます: + +* キーボード (`/keyboards//config.h`) +* ユーザスペース (`/users//config.h`) +* キーマップ (`/keyboards//keymaps//config.h`) + +ビルドシステムは自動的に上の順に config ファイルを取得します。前の `config.h` で設定された設定を上書きしたい場合は、変更したい設定の準備のために最初に定型コードを置く必要があります。 + +``` +#pragma once +``` + +次に、前の `config.h` ファイルの設定を上書きするために、設定を `#undef` し再び `#define` する必要があります。 + +定型コードと設定は、以下のようになります: + +``` +#pragma once + +// ここに上書きします！ +#undef MY_SETTING +#define MY_SETTING 4 +```