Contributing

Azure Proactive Resiliency Library (APRL) への貢献を検討している方は、適切な場所/ページにたどり着きました 👍

以下の指示、特に前提条件に従って、ライブラリへの貢献を開始してください。

推奨事項を書く

APRLの推奨事項は、Well Architected Reliability Assessmentsの提供を可能にし、加速することを目的としています。APRL の目的は、ベスト プラクティスに関する既存の Azure パブリック ドキュメントやガイダンスを置き換えることではありません。

各レコメンデーションは、お客様にとって実用的なものでなければなりません。お客様はレコメンデーションをバックログに配置でき、それを拾うエンジニアは、行う必要がある変更と、変更を行う必要がある特定のリソースを完全に明確にする必要があります。

各推奨事項には、説明的なタイトル、推奨事項の詳細を含む短いガイダンス セクション、推奨事項に関連する追加情報を提供する公開ドキュメントへのリンク、および推奨事項に準拠していないリソースを特定するためのクエリを含める必要があります。タイトルとガイダンスのセクションだけでも、CSAがリソースを評価するのに十分な情報を提供する必要があります。

推奨事項は、CSAがバックグラウンドの読み取りに多くの時間を費やすことを要求したり、解釈の余地があったり、曖昧であったりしてはなりません。WARA を提供する CSA は、限られた時間内に多数の Azure リソースをレビューしており、すべての Azure サービスの専門家ではないことに注意してください。

例

• 良い推奨事項: サービスに /24 サブネットを使用します
• 悪い推奨事項: サブネットのサイズを適切に設定します

すべてのベストプラクティスがAPRLの推奨に適しているわけではありません。ベストプラクティスが特定のサービス構成に関連し、ARGクエリで確認できる場合は、APRLの推奨事項として適切である可能性があります。ベスト プラクティスが、多くのサービスまたはワークロードの種類に当てはまる一般的なアーキテクチャの概念により整合している場合は、APRL WAF セクションにトピックに対処する推奨事項が既にある可能性が非常に高いです。そうでない場合は、APRL に WAF の推奨事項を追加することを検討してください。どちらも当てはまらない場合、APRLはこのコンテンツに最適な場所ではない可能性があります。

コンテキスト/背景

前提条件と特定のセクションのコントリビューションのガイダンスに飛び込む前に、このライブラリが今後のコントリビューションを支援するためにどのように構築されているかについて、このコンテキスト/背景をよく理解してください。

この site は、静的サイトジェネレータである Hugo を使用して構築されており、ソースコードは APRL GitHub リポジトリ (このサイトのヘッダーにもリンクされています) に保存され、リポジトリを介して GitHub Pages でホストされています。

HugoとGitHubのページを組み合わせた理由は、ページやフォルダがたくさんあるときに使いにくいネイティブのGitHubリポジトリを使用するのではなく、ナビゲートして利用しやすいライブラリを提示できるようにするためです。また、Hugoはモバイル利用者にとっても使いやすいようにサイトを生成します。

でも私にはHugoのスキルがありません

大丈夫です、スキルは本当に必要ありません。Hugoは、マークダウン(’.md’)ファイルを作成できるようにするだけで、残りの作業はサイト生成時に実行されます👍

前提条件

以下のセクションを読み、それに従って、APRLに貢献するための「準備完了状態」にしてください。

“準備完了状態” とは、‘Azure/Azure-Proactive-Resiliency-Library’ リポジトリ のフォークされたコピーがローカル コンピューターに複製され、VS Code で開かれていることを意味します。

開発中にAPRLのローカルコピーを実行してアクセスする

VS Code では、ターミナルを開き、次のコマンドを実行して、次のアドレス ‘http://localhost:1313/Azure-Proactive-Resiliency-Library/’ を使用して、Hugo が提供するローカル Web サーバーから APRL Web サイトのコピーにアクセスできます。

cd docs
hugo server -D

ソフトウェア/アプリケーション

このプロジェクト/リポジトリ/ライブラリに貢献するには、次のものがインストールされている必要があります。

• Git
• Visual Studio Code (VS Code)
  • Extensions:
    • editorconfig.editorconfig, streetsidesoftware.code-spell-checker, ms-vsliveshare.vsliveshare, medo64.render-crlf, vscode-icons-team.vscode-icons
    • VS Code では、VS Code でこのリポジトリまたはそのフォークを開くと、これらをインストールするように自動的に推奨されます。
• Hugo Extended

winget インストールコマンド

「winget」をインストールするには、インストール手順はこちらに従ってください。

winget install --id 'Git.Git'
winget install --id 'Microsoft.VisualStudioCode'
winget install --id 'Hugo.Hugo.Extended'

その他の要件

• A GitHub profile/account
• ‘Azure/Azure-Proactive-Resiliency-Library’ リポジトリ のフォークを GitHub 組織/アカウントに作成し、マシンにローカルに複製する
  • リポジトリをフォークしてクローンする手順は こちら にあります。

役立つリソース

以下は、APRLに貢献する際に役立ついくつかのリソースへのリンクです。

• Ace Documentation Theme (that we use) - Docs
  • Shortcodes - e.g. Code
• Ace Documentation Theme (that we use) - Repo
  • The Example Site, which is the first link above, source code
• Hugo Quick Start
• Hugo Docs
• Markdown Cheat Sheet

何かを貢献する前に行うべき手順(前提条件の後)

リポジトリのフォークが配置されているディレクトリから選択したターミナルで次のコマンドを実行します。

git checkout main
git pull
git fetch -p
git fetch -p upstream
git pull upstream main
git push

これを行うと、アップストリーム リポジトリから最新の変更が取得され、次のコマンドを実行して ‘main’ から新しいブランチを作成する準備が整います。

git checkout main
git checkout -b <YOUR-DESIRED-BRANCH-NAME-HERE>

サービスの推奨事項ページの作成

実行される可能性が高い一般的なタスクは、推奨事項やサポート クエリなどを提供する新しいサービス (仮想マシンなど) を追加することです。

このタスクでは、Hugoのアーキタイプ機能を使用して、変更して使用できる多くのテンプレートコンテンツを含む新しいサービス用のディレクトリ全体を作成できます。これは、次のコマンド ‘hugo new –kind service-bundle services//<service-name’ を使用して呼び出すことができます。

「service-bundle」というディレクトリアーキタイプのソースコードをリポジトリのこちらで見ることができます。

Steps to follow:

1. In your terminal of choice run the following:
   Copy

   cd docs/
   hugo new --kind service-bundle services/compute/virtual-machines
   

2. You will now see a new folder in content/services/compute called virtual-machines
   Copy

   ├───content
   │   ├───contributing
   │   └───services
   │       ├───ai-ml
   │       ├───compute
   │       │   └───virtual-machines
   │       │       └───code
   │       │           ├───cm-1
   │       │           └───cm-2
   

3. Inside the virtual-machines folder you will see the following files pre-staged
   Copy

   │       │   └───virtual-machines
   │       │       │   _index.md
   │       │       │
   │       │       └───code
   │       │           ├───cm-1
   │       │           │       cm-1.kql
   │       │           │
   │       │           │
   │       │           └───cm-2
   │       │                   cm-2.kql
   

4. Open _index.md in VS Code and make relevant changes
   • You can copy the recommendations labelled CM-1 or CM-2 multiple times to create more recommendations
5. Update Azure Resource Graph queries in the code folder within virtual-machines
   • You will see there is a folder, e.g. cm-1, cm-2, per recommendation to help with file structure organization
6. Ensure you use the correct Azure resource abbreviations provided within our Cloud Adoption Framework (CAF) documentation here. For example, use vm for Virtual Machines.
7. Save, commit and push your changes to your branch and repo
8. Create a create a Pull Request into the main branch of the upstream repo
9. Get it merged

レコメンデーションの自動化標準

サービスのレコメンデーションを作成するときは、以下の基準に従ってください。

レコメンデーションカテゴリ

各レコメンデーションには、以下の一覧から **1 つだけ ** カテゴリが関連付けられている必要があります。

Azure Resource Graph (ARG) クエリ

1. すべての ARG クエリには、クエリの上部に 2 つのコメント (1 つは “Azure Resource Graph クエリ” を示すコメント、もう 1 つは返されたクエリ結果の説明を提供するコメント) が必要です。例えば：

   // Azure Resource Graph Query
   // Provides a list of Azure Container Registry resources that do not have soft delete enabled
   

2. ARG クエリが開発中の場合、クエリには「// under-development」という 1 行が必要です。

3. ARG内で提供されるデータの制限によりレコメンデーションクエリを返すことができない場合、クエリには「// cannot-be-validated-with-arg」という1行が必要です。

4. クエリは、APRL の推奨事項に準拠していないリソースのみを返す必要があります。たとえば、Azure Container Registries の論理的な削除を有効にすることが推奨される場合、関連付けられているクエリは、論理的な削除が有効になっていない Azure Container Registry リソースのみを返す必要があります。

5. ARGクエリフォルダにファイルタイプの拡張子が「.fix」のファイルがある場合、これは現在のクエリが期待どおりに機能しないことを意味し、これをクエリを修正するための開始点として使用することを検討してください。クエリが期待どおりに動作していることを確認したら、接尾辞が ‘.fix’ のファイルを削除してください。

6. 返される ARG クエリ列名には、次のもののみを含める必要があります。

サービスの推奨事項ページの更新

これは、おそらく実行される最も一般的なタスクです。

必要なのは、既存のマークダウン (’.md’) ファイルを直接編集し、変更を保存し、コミットし、ステージングして、ブランチとリポジトリにプッシュすることだけです。次に、pull requestをアップストリームリポジトリの ‘main’ブランチに作成すれば完了です👍

サービスカテゴリの作成

このタスクでは、Hugoのアーキタイプ機能を使用して、変更して使用できる多くのテンプレートコンテンツを含む新しいサービス用のディレクトリ全体を作成できます。これは、次のコマンド ‘hugo new –kind category-bundle services/’ を使用して呼び出すことができます。

「category-bundle」というディレクトリアーキタイプのソースコードをリポジトリのこちらで見ることができます。

Steps to follow:

1. In your terminal of choice run the following:
   Copy

   cd docs/
   hugo new --kind category-bundle services/aaa
   

2. You will now see a new folder in content/services called aaa
   Copy

   ├───content
   │   │   _index.md
   │   │
   │   ├───contributing
   │   │       _index.md
   │   │
   │   └───services
   │       │   _index.md
   │       │
   │       ├───aaa
   │       │       _index.md
   

3. Inside the aaa folder you will see the following file _index.md pre-staged
   Copy

   ├───aaa
   │       │       _index.md
   

4. Open _index.md in VS Code and make relevant changes
5. Save, commit and push your changes to your branch and repo
6. Create a create a Pull Request into the main branch of the upstream repo
7. Get it merged

重要なヒント

1.Webサイトのローカルバージョンには、作成したコンテンツを反映していない不整合が表示される場合があります。 - これが発生した場合は、CTRL+Cを押してHugoローカルWebサーバを強制終了し、‘docs/‘ディレクトリから’hugo server -D’を実行してHugoWebサーバを再起動します