どのようにコード貢献をするか

本稿では，Astropyプロジェクトにコードを貢献する流れについて概説した。

もうGITを体験しましたか？以前に貢献したことがありますか。 直接ジャンプする Astropyガイド git それがそうです。

必要な条件

本明細書のステップを実行する前に、あなたは以下のようにしなければなりません。

• 口座の口座 GitHub

• 星源のローカルコピーですこの操作の実行に関する説明には、GitおよびGitHubを設定するために必要な基本知識が含まれていますので、アクセスしてください 開発版を試用する それがそうです。

強く推薦しますが、必要ではありません

安定バージョンも使用するpython環境では、Asterpyの開発バージョンを簡単に使用することができません。これはできることだ — でもそれしかできない 成功 もしあなたが開発バージョンか安定バージョンかを常に覚えていれば、アクティブバージョンです。

Python仮想環境 より良い解決策を提供し、数分で設定を完了することができる。これはあなたが時間をかける価値があります。

あなたの最初の貢献が何であるべきか確信できませんか？ちょっと見てください Astropy issue list そして表示されているものを持って "package-novice" それがそうです。Astropyソースコードに慣れていなければ、これらの問題は最も解決しやすい問題です。ラベルは "effort-low" 解決には数時間かかると予想されていますが "effort-medium" 一回に数日かかるかもしれません。開発者はとても友好的で、あなたの助けが必要なので、恥ずかしくないでください astropy-dev mailing list それがそうです。

新着. git そうですか。

幾らか git 資源

GITを使用したことがない場合や使用経験が限られている場合は、以下のリソースを数分かけて確認してください。

• Interactive tutorial ブラウザで動作する

• Git Basics _、これはもっと長いです git book それがそうです。

実際には少数しか必要ありません git Astropyに貢献するコマンド。もっと広いリストがあります Gitリソース もしあなたがもっと背景資料が欲しいなら。

設定をよくチェックしてください

さらに操作する前に、上記のようにAsterpyが設定されていることを確認してください 開発版を試用する それがそうです。

エンドウィンドウでは，ディレクトリをAstropyクローンを含むディレクトリに変更する.そして、走って git remote 出力は以下のとおりである.

your-github-username
astropy

もしこれがうまくいけば、実行することもできます git fetch --all それがそうです。実行時にエラーがない場合は、インストールが実行されていることを示し、クローン中のすべてのノードの完全リストを持っています。 your-github-username そして astropy それがそうです。

中の名前について git

git デザインされています 分散型. バージョン制御システム。リポジトリの各クローン自体がリポジトリである.これは混乱を招くかもしれません特に名前は master それがそうです。Gitクローンが知っているすべての枝をリストしていれば git branch -a ご覧のように 三つ 様々な支店は master **

* master                              # this is master in your local repo
remotes/your-github-username/master   # master on your fork of Astropy on GitHub
remotes/astropy/master                # the official development branch of Astropy

使用命名案 git ここでも使います。単純な支店名、例えば master ローカルAstropyバージョンのうちの1つを指します。リモコンの1つの枝は astropy そのリモコンにラベルが貼られています astropy/master それがそうです。

Pull要求を処理する際には，このような名前の重複が非常に混乱する可能性があり，特に官側主分岐では， astropy/master あなたの貢献が統合される前に、他の貢献によって発生した変更。したがって、あなたはあなたの主な支店で何もしてはいけません。 master それがそうです。いつも枝で働くのではなく、枝で働く。

基本要素. git 指令

満額の git チュートリアルは本稿の範囲を超えていますが、このリストにはいくつか記述されています git Astropyに貢献する時に遭遇するかもしれないコマンド：

• git fetch Astropyの最新開発バージョンを取得し、このバージョンを使用して変更します。

• git branch Astropyの論理独立コピーを作成して、変更を追跡します。

• git add 追加するために変更または作成されたファイルを一時保存します git それがそうです。

• git commit 一時保存の変更をリポジトリに追加します。

• git push GitHubに提出された変更をコピーします

• git status 修正または作成されたファイルリストを表示する場合は、以下の操作を実行してください。

注釈

良好なgitグラフィックスインタフェースは，そのいくつかのステップをより容易にする.いくつかの選択肢が紹介されています Git GUIの取得(オプション) それがそうです。

何か間違いがあったら

git エラーから回復する様々な方法が提供される。もし最終的に git 間違いを犯しましたので、迷わず助けを求めてください。以下の位置から復元された追加リソースをご案内します git 間違いは git choose-your-own-adventure それがそうです。

Astropyガイド git

• あなたのを使わないで master 支店は何でもします。考慮する 主な枝を削除しています それがそうです。

• 新しい枝を作りました 機能分岐 各グループの分離可能な変更について：“1つのタスク，1つのノード” (ipython git workflow ）。

• 新しい生活を始める 機能分岐 最新のAstpy開発バージョンから(以下に説明する).

• 変更の目的で、例えば分岐に名前をつけます。 bugfix-for-issue-14 あるいは…。 refactor-database-code それがそうです。

• 頻繁に提出され、常に提出メッセージが含まれている。毎回提出されることは論理的変更のセットを代表しなければならない。

• ネットで尋ねる astropy-dev mailing list もしあなたが立ち往生したら。

• 以下の位置から統合して変更しない astropy/master 機能分岐に追加します。開発バージョンの変更に私たちのコードを変更する必要があれば、可能です 基数を調整するが，要求された場合にのみ それがそうです。

他にもいくつかあります git 本稿で用いた命名約束：

• リモコンの名前を変更する origin 至る your-github-username それがそうです。

• 主なAstropyリポジトリのリモコンとして命名されました astropy 本文書の以前のバージョンでは upstream それがそうです。

仕事の流れ

概念上、以下は、Astropyに貢献する際に従う手順です。

1. 最新のAstropyを取得する

2. 新しい要素分岐を作成する ；あなたはこの分岐で変更されます。

3. あなたの支店の設置

4. 注目する ワークフローを編集する 編集/文書/テストコードの作成/編集-頻繁に、少量提出します。

5. ChangeLogエントリの追加

6. 変更をGitHubにコピーする

7. GitHubからの 変更の審査を要求します Astropyのメンテナンス担当者にあなたが検討しなければならない貢献があることを知ってもらいます。

8. 必要に応じて修正して推送する 引き出し要求に対するコメントに応答します。これらの変更をGitHubにプッシュすると、自動的に引き出し要求が更新されます。

このような働き方は，作業の良い組織を保持するのに役立ち，可読性の歴史を持つ.これは逆にプロジェクト維持者(あなたかもしれない)があなたが何をしたのか、なぜそうしたのかを容易に見ることができるようにする。

Astropy問題を以下の手順で修復する作業例は Astropyにコードを提供するのは良い例です それがそうです。

以下に関連するいくつかの付加的なテーマ git Vt.は中だ 他にもやりたいことがあるかもしれません それがそうです。

主な枝を削除しています

これは変に聞こえるかもしれませんが、自分のを削除します master 枝はどの枝にいるのかの混乱を減らすのを助けることができる。参照してください deleting master on github もっと細かいことを知っています。

最新のAstropyを取得する

開発バージョン(すなわちAstropy)を時々取得しなければなりません astropy/master )GitHubからの変更：

git fetch astropy --tags

これは、あなたが持っていないすべてのコミットを引き落とし、リモート·ブランチを最新のコミットを指すように設定します。例えば，主幹とは枝のことである astropy/master 前回の検査後に提出されたら astropy/master あなたが取り戻しを終えた後に変化します。

新しい要素分岐を作成する

新しい支店をつくる

あなたがコードをいくつか変更する準備ができている時、あなたは新しい分岐を始めなければならない。関連編集集合のためのノードを一般に“要素ノード”と呼ぶ.

関連する変更のグループごとに新しいブランチを作成することで、あなたのブランチを見ている人があなたが何をしているのかを容易に見ることができます。

ノードのために情報の豊富な名前を選択して、私たち他のノードとの変更が何のためなのかを想起させます。支店名、例えば add-ability-to-fly あるいは…。 buxfix-for-issue-42 支店の目的を明確に説明する。

常に以下の位置から分岐を作成する astropy/master したがって、あなたの変更は、最新バージョンのAstropyに基づきます：

# Update the mirror of trunk
git fetch astropy --tags

# Make new feature branch starting at astropy/master
git branch my-new-feature astropy/master
git checkout my-new-feature

GitHubへの支店の接続

このときあなたは新しい枝を作成してサインしましたが git GitHubの分岐に接続されなければならないとは知らなかった。ご提案の変更を管理するためには、GitHub上のAstropy保守者が接続する必要があります。

地元の支店をGitHubに接続するためには git push この新しい枝はGitHubの買い戻しまであります --set-upstream オプション：：

git push --set-upstream your-github-username my-new-feature

これからgitは知っています my-new-feature 与 your-github-username/my-new-feature あなたのAstropyのGitHub枝にあります。

あなたはまだ必要です git push GitHubに対するあなたの定期的な変更。本節での設定は，この点を容易にする.

あなたの支店の設置

理想的には、修復のためにPython仮想環境を設定する必要があります。この操作をどのように実行するかについての説明は、参照してください。 Python仮想環境 それがそうです。これにより、ホームディレクトリが壊れないようにすることができます astropy 実装し，エラーからの回復は非常に容易である.

この環境を活性化すると、インストールが必要なバージョン astropy あなたがやっているのは。そのためには、以下の操作を実行してください。

pip install -e .

構築の詳細については、ご参照ください astropy ソースファイルでは、ご参照ください Astropyとそのサブパッケージの構築 それがそうです。

ワークフローを編集する

概念上、あなたは次のように言います。

1. 1つ以上のファイルを変更し、および/または新しいファイルを追加します。

2. あなたの変更が既存のコードを破壊していないかチェックします。

3. 文書をコードに追加し，必要に応じてAstropy文書に追加する.

4. 理想的には、あなたの変更が文書を破壊しないようにしなければなりません。

5. あなたに貢献するコードを追加するテスト。

6. 変更を中に提出します git

7. 必要に応じて繰り返す。

もっと詳しく言えば

1. 1つまたは複数のファイルをいくつか変更します。星座についていくべきです コードガイド. それがそうです。論理変更の各グループは一度の提出とみなされなければならない。例えば、Astropyの既知のエラーを修復しており、修復を実現する際に異なるエラーに気づいた場合、新しいエラーの修復は、異なる変更のセットとして実現されてください。

2. あなたの変更をテストすることはできません 回帰分析 すなわち、Astropyテストを実行することにより、あなたの変更は既存のコードを破壊しません。以下のコマンドを使用してIPythonからすべてのAstropyテストを実行することができます。

   import astropy
   astropy.test()
   

   変更がAstropyの一部、例えば時間のみに関連している場合、以下のテストのみを実行することができます。

   import astropy
   astropy.test(package='time')
   

   テストは、ソフトウェア·ルート·ディレクトリ内でコマンドラインから実行されてもよく、例えば、：

   pytest
   

   1つのパケット(例えばTime)でのみテストを実行するためには、以下の動作を実行することができます。

   pytest -P time
   

   運行テストの詳細については、ご参照ください テストガイド. それがそうです。

3. コードに適切な文書文字列が含まれていることを確認してください。 Numpydoc format それがそうです。適切であれば，新たな機能を追加する際には，中の該当文書を更新すべきである. docs 詳細は参照 文書を作成する それがそうです。

4. Shinxがインストールされている場合、以下のように文書の構築および外観が正しいかどうかをチェックすることもできます。 astropy 目次：：

   cd docs
   make html
   

   最後の行はただ説明すべきだ build succeeded どんな警告も言及されてはいけない。(詳細については、参照 文書を作成する ()

5. 適切であれば、新しいコードのテストを追加します。いくつかの変更(例えば、文書の変更)はテストを必要としない。詳しい説明については、訪問してください テストを書く しかし、テストや使用を作成していない場合 pytest テストフレームワークは、テストを追加することなく変更を提出しますが、Pull要求ではまだテストを作成していないと言われています。作成テストの例を示しました 立ち止まって考えてみてください：もっと多くのテストや他の変化はありますか？ それがそうです。

6. 以下のツールを使用して変更を一時保存します git add 以下のコマンドを使用して提出します git commit それがそうです。実際のAstropy問題の修復に基づく一例は Astropyにコードを提供するのは良い例です それがそうです。

   注釈

   あなたのを git 提出メッセージは短く、記述性を有する。修復質問が提出された場合、以下のように、提出メッセージの2行目または後の行に提出メッセージ中の質問番号を含めてください。 Closes #123 それがそうです。このようにすることは、プル型要求が受け入れられたときに問題を自動的にオフにするだろう。

7. いくつかの修正は複数の提出を必要とする；質問があれば、変更を複数の大きな提出を一度に完了するのではなく、いくつかの小さな提出に分解することができる。必要に応じて上記の手順を繰り返す！

ChangeLogエントリの追加

ファイルにエントリを追加する CHANGES.rst あなたがした変化を簡単に説明します。エントリの末尾には引き出し要求番号も含まれている。中の変更の例示的なエントリ PR 1845 ，is：：

- ``astropy.wcs.Wcs.printwcs`` will no longer warn that ``cdelt`` is
  being ignored when none was present in the FITS file. [#1845]

新しい引き出し要求を開いているなら、まだその番号を知らないかもしれませんが、追加することができます。 その後 あなたが牽引要請をします。ChangeLogエントリをどこに置くか分からない場合、少なくとも保守員があなたの広報をチェックし、マイルストーンに割り当てるまで待たなければなりません。

ChangeLogエントリを作成する際には、単逆引用符を用いてAPI参照リンクの作成を試みないでください。これは、ChangeLog(その現在のフォーマットで)がプロジェクト履歴のために実行され、今日あなたがしたAPI参照がAstropyの将来のバージョンで無効になる可能性があるからである。しかし，二重反転番号を用いてモジュール/クラス/関数/パラメータ名などを等間隔にレンダリングすることを提案する.

変更をGitHubにコピーする

あなたがFeatureノードを作成する方法のため、この段階は簡単です。ただ：

git push

変更の審査を要求します

A お願いをする. GitHubには、あなたがした変更を別のリポジトリに統合することを要求する要求があります。

あなたが誰かにあなたのコードをレビューして、Astropyに統合することを考慮する準備をしている時：

1. AstropyノードのURLに転送してください例えば https://github.com/your-user-name/astropy それがそうです。

2. “Switch Branks”(スイッチ分岐)プルダウンメニューを使用して、変更された分岐を選択します。

   

3. ‘Pull Request’(プル要求)ボタンをクリックします：

   

   変更セットのタイトルと、あなたがした操作のいくつかの説明を入力します。複雑な変更や不満なコードなど、特に何かに注意したい場合は、ここに詳細を追加してください。

   あなたの要請がまだ統合の準備ができていないと思う場合は、あなたのPull要求メッセージで説明すればいいです。これはまだ予備コードの検討を始める良い方法だ。

   あなたはまた進行中のプルアップ要請を開くことを選択することができる。そうした場合は、“Create Pull Request”をクリックするのではなく、その横の小さな矢印をクリックして、“Create Draft Pull Request”を選択してください。これは保守員に、あなたの仕事はまだ全面的な審査を行う準備ができていないし、合併することもできないことを知らせるだろう。また、もしあなたの提出がまだCIテストを行う準備ができていなければ、まだ使用すべきです。 [ci skip] あるいは…。 [skip ci] 指示は提出メッセージに追加される。

必要に応じて修正して推送する

Pull要求を検討する際に変更を要求する場合があります。これらの変更は、ローカルコピーで行われ、ローカルrepoに提出され、GitHubにプッシュされます。GitHubはあなたの引き出し要求を自動的に更新します。

合併提出は作成しない

プル型要求に関連する分岐が遅れている場合 master GitHubの分岐https：//github.com/Astcopy/Astcopyは、そのWebインタフェースで競合を追いかけたり解決したりすることを選択する場合がありますが、このオプションは使用しないでください。Webインタフェースの使用は、“統合提出”が発行マネージャにメンテナンスオーバヘッドおよび不要な分岐構造の複雑さをもたらすため、お客様の提出履歴に“統合提出”を作成することは好ましくありません。使わないで git pull 司令部もそうではない。

代わりに地元の会計では fetch そして1つは rebase 必要に応じて衝突を解決します参照してください 基数を調整するが，要求された場合にのみ そして 基準をどのように調整するか より多くの情報を得ることができます

基数を調整するが，要求された場合にのみ

Astropyのメンテナンス担当者が要求する場合があります 基数を再設定する あるいは…。 ぺしゃんこになった マスタAstropyに統合された引取要求を審査する過程で 師匠 貯蔵庫です。

いつ要請するか決めます スカッシュ. あるいは…。 塁を変える. 単独の保守員に残されていますこれは，リポジトリ履歴に保存されている可視コミット数を減らすため，あるいは同時にAstropyにおけるコード変更により要求される可能性がある.持続統合テストを実行するためには、基数を再設定する必要がある場合があります。両方とも書き換えに関するものだ git 履歴、これは提出ハッシュが変更されることを意味し、それが要求されたときにのみそうすべき理由である。

概念上、基礎を再構築することは、あなたの変更を公式Astropyの開発ノードの最新バージョンに適用することを意味し、それがあなたの最初のノードのバージョンのようになります。各個々のコミットは依然として見られるが、新しいメタデータ/コミットハッシュを有する。プッシュ提出は、メタデータ/コミットハッシュを変更し、別個に提出された個々の可視性も除去し、新しい提出メッセージおよび提出メッセージは、より早く提出されたテキストリストのみを含むであろう。

他の分野に比べて、再確定ベースアドレスの方がミスしやすい。 git したがって、開始前に、動作するバックアップコピーとして分岐を作成します：

git branch tmp my-new-feature # make temporary branch--will be deleted later

履歴を変更した後、例えば使用する git rebase 普通のものです git push 阻止されています git push --force 必要になるでしょう

基準をどのように調整するか

舞台裏では git あなたがした変更および分岐を削除し、Astropyの開発ノードに対して他の人が行った変更を行い、開発ノードから分岐を再作成し、変更を分岐に適用しています。

実際の基数調整は通常容易である.

git fetch astropy master # get the latest development astropy
git rebase astropy/master my-new-feature

あなたはもっと多くの人に会う可能性があります 衝突する. ここであなたがした変化が他の人がした変化と衝突する場所は他のどこよりも良いのですもしあなたが助けが必要なら、助けを求めてください。以下の動作をどのように実行するかについての説明を提供する resolve merge conflicts after a Git rebase それがそうです。

どのように押しますか

通常私たちは スカッシュ. かなりの試行錯誤がある場合、最終的なパッチはまだ小さい場合、またはファイル(特にバイナリファイルまたはリポジトリに保持されてはならないファイル)を追加して削除するか、または履歴中の提出回数が実行されているジョブと比較して比例しない場合(例えば、30回の提出が最終的な10行変更を徐々に詳細化する)。概念的には，これは機能ノードから最終的な差異を導出し，1つの新しい枝を起動し，そのパッチのみを適用することに等しい.

私たちの多くは、rebaseを使用することが実際に最も圧迫されやすいことを発見した。具体的には、以下のコマンドを使用して、既存のブランチにおいてアドレスを再ベースおよび圧縮することができます。

git fetch astropy
git rebase -i astropy/master

最後のコマンドは、すべての提出を含むエディタを開き、複数の提出をまとめて、それらを再命名することができます。有用なのは、あなたが編集しているファイルにどのように操作するかについての説明があります。

どのように推進するか

使用後 git rebase 他の人がこれらの変更を見て、Pull要求を更新できるように、変更をGitHubにプッシュする必要があります。簡単なものを使う git push 変更された履歴によってブロックされ、以下のコマンドを使用して手動で上書きされる必要があります。

git push --force

何か問題があったら、迷わずに聞いてください。変更基数のより詳細な概念的な議論については、参照されたい 幹線に基づいて基礎を再構築する それがそうです。

GitHubへの修正と新しいGIT履歴のプッシュに成功した後、作成された可能性のある任意のバックアップ分岐を削除することができます：

git branch -D tmp