dotnet-github-docs

Name: dotnet-github-docs
Author: wshaddix

github.com/wshaddix開発8670 回インストール35 週間前に更新

リポジトリ

dotnet-github-docs について

.NET リポジトリの GitHub ネイティブなドキュメント構成を扱うスキルです。README、コントリビューション案内、Issue・PR テンプレート、リポジトリメタデータ、GitHub Pages のリポジトリ設定を扱います。

主な機能

01README の構成とバッジ
02CONTRIBUTING.md の案内
03YAML の Issue テンプレートと PR テンプレート
04GitHub Pages のリポジトリ設定
05リポジトリメタデータと Mermaid の埋め込み

活用シーン

01.NET リポジトリのドキュメント構成
02Issue とプルリクエストの受付方法の統一
03README のアーキテクチャ図の準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/wshaddix/dotnet-skills --skill dotnet-github-docs

インストール後、Claude Code で/dotnet-github-docsを入力して読み込まれたか確認します。

詳細

dotnet-github-docs

.NET プロジェクト向けの GitHub ネイティブなドキュメントのパターン：NuGet／CI／カバレッジバッジとインストール手順を含む README の構成、フォークから PR を送るワークフローと開発環境のセットアップを記載する CONTRIBUTING.md、課題テンプレート（.NET バージョンと再現手順を含むバグ報告、問題／解決策／代替案を含む機能リクエスト）、テストチェックリストと破壊的変更のセクションを含む PR テンプレート、ドキュメントサイト向けの GitHub Pages 設定、リポジトリのメタデータ（CODEOWNERS、FUNDING.yml、ソーシャルプレビュー、トピック／タグ）、README ファイルへの Mermaid 図の埋め込み。

バージョンの前提： コード例の基準は .NET 8.0 以降です。CI バッジには GitHub Actions を使用します。パッケージバッジには NuGet.org を使用します。

対象範囲： このスキルは、.NET プロジェクト向けの GitHub ネイティブなドキュメント構成とテンプレート、つまりリポジトリのルートと .github/ ディレクトリに置かれるファイルを担当します。GitHub Pages サイトの CI/CD デプロイパイプラインは [skill:dotnet-gha-deploy] が担当します。変更履歴の生成とバージョン管理の規約は [skill:dotnet-release-management] が担当します。ドキュメントツールの選定（Starlight、Docusaurus、DocFX）は [skill:dotnet-documentation-strategy] が担当します。Mermaid 図の構文と .NET 固有の図のパターンは [skill:dotnet-mermaid-diagrams] が担当します。

対象外： GitHub Pages またはドキュメントサイト向けの CI/CD デプロイワークフローについては、[skill:dotnet-gha-deploy] を参照してください。変更履歴の生成とリリースのバージョン管理については、[skill:dotnet-release-management] を参照してください。ドキュメントプラットフォームの選定と設定については、[skill:dotnet-documentation-strategy] を参照してください。Mermaid 図の構文の詳細については、[skill:dotnet-mermaid-diagrams] を参照してください。プロジェクトファイルの構成とソリューションの整理については、[skill:dotnet-project-structure] を参照してください。

相互参照：GitHub Pages のデプロイパイプラインについては [skill:dotnet-gha-deploy]、変更履歴の形式とバージョン管理については [skill:dotnet-release-management]、README で使う .NET 固有の Mermaid 図については [skill:dotnet-mermaid-diagrams]、プロジェクトのメタデータについては [skill:dotnet-project-structure]、ドキュメントプラットフォームの選定については [skill:dotnet-documentation-strategy] を参照してください。

.NET プロジェクト向け README の構成

適切に構成された README は、.NET プロジェクトのコントリビューターや利用者に、必要な情報をすぐに伝えます。

バッジ

README の先頭に、カテゴリごとにまとめてバッジを配置します。

# My.Library

[![NuGet](https://img.shields.io/nuget/v/My.Library.svg)](https://www.nuget.org/packages/My.Library)
[![NuGet Downloads](https://img.shields.io/nuget/dt/My.Library.svg)](https://www.nuget.org/packages/My.Library)
[![Build Status](https://github.com/mycompany/my-library/actions/workflows/ci.yml/badge.svg)](https://github.com/mycompany/my-library/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/mycompany/my-library/branch/main/graph/badge.svg)](https://codecov.io/gh/mycompany/my-library)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

.NET プロジェクト向けのバッジカテゴリ：

バッジ	ソース	備考
NuGet バージョン	shields.io + nuget.org	アセンブリ名ではなく、パッケージ ID を使用します
NuGet ダウンロード数	shields.io + nuget.org	利用状況を示します。ダウンロード総数には `dt` を使用します
ビルド状況	GitHub Actions	CI ワークフローへのリンクを設定します
コードカバレッジ	Codecov / Coveralls	CI との統合が必要です
ライセンス	shields.io	リポジトリのライセンスと一致させます
.NET バージョン	shields.io	任意です。サポートする最小の TFM を示します

推奨する README のセクション

# My.Library

[badges here]

Short one-paragraph description of what the library does and why it exists.

## Installation

```shell
dotnet add package My.Library
```

Or via PackageReference in your `.csproj`:

```xml
<PackageReference Include="My.Library" Version="1.0.0" />
```

## Quick Start

```csharp
using My.Library;

var service = new WidgetService();
var widget = await service.CreateWidgetAsync("example");
Console.WriteLine(widget.Id);
```

## Features

- Feature 1: brief description
- Feature 2: brief description
- Feature 3: brief description

## Documentation

Full documentation is available at [https://mycompany.github.io/my-library](https://mycompany.github.io/my-library).

## Architecture

[Mermaid architecture diagram -- see [skill:dotnet-mermaid-diagrams] for patterns]

## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a history of changes. For changelog format conventions, see [skill:dotnet-release-management].

README のアーキテクチャ図

視覚的に把握できるよう、Mermaid のアーキテクチャ図を README に直接埋め込みます。GitHub は Mermaid のフェンス付きコードブロックを標準でレンダリングします。

## Architecture

```mermaid
graph TB
    subgraph Client
        App["Consumer App"]
    end
    subgraph Library["My.Library"]
        API["Public API Surface"]
        Core["Core Engine"]
        Cache["In-Memory Cache"]
    end
    App --> API
    API --> Core
    Core --> Cache
```

C4 スタイルのアーキテクチャ、API フローのシーケンス図、ドメインモデルのクラス図など、.NET 固有の図のパターンについては、[skill:dotnet-mermaid-diagrams] を参照してください。

CONTRIBUTING.md のパターン

フォークから PR を送るワークフロー

# Contributing to My.Library

Thank you for your interest in contributing! This document provides guidelines
and instructions for contributing.

## Getting Started

1. Fork the repository
2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/my-library.git`
3. Create a feature branch: `git checkout -b feature/my-feature`
4. Make your changes
5. Submit a pull request

## Development Setup

### Prerequisites

- [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) or later
- An IDE: [Visual Studio 2022](https://visualstudio.microsoft.com/), [VS Code](https://code.visualstudio.com/) with C# Dev Kit, or [JetBrains Rider](https://www.jetbrains.com/rider/)

### Building

```shell
dotnet restore
dotnet build

テストの実行

dotnet test

カバレッジを取得してテストを実行するには：

dotnet test --collect:"XPlat Code Coverage"

コーディング規約

.NET のコーディング規約に従います
コミット前に dotnet format を使用してコードスタイルを適用します
すべてのパブリック API に XML ドキュメントコメントを付けます
新機能にはユニットテストを含めます

プルリクエストの手順

変更した公開 API のドキュメントを更新します
変更内容をカバーするテストを追加または更新します
すべてのテストが成功することを確認します：dotnet test
警告なしでコードがコンパイルされることを確認します：dotnet build -warnaserror
変更内容を [Unreleased] セクションの下にある CHANGELOG.md に記載します
メンテナーが PR をレビューします

問題の報告

バグにはバグ報告テンプレートを使用します
機能強化には機能リクエストテンプレートを使用します


---

## Issue Templates

### Bug Report Template

```yaml
# .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug Report
description: Report a bug in the library
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thank you for reporting a bug. Please fill out the information below
        to help us diagnose and fix the issue.

  - type: textarea
    id: description
    attributes:
      label: Description
      description: A clear and concise description of the bug.
    validations:
      required: true

  - type: textarea
    id: repro-steps
    attributes:
      label: Steps to Reproduce
      description: Steps to reproduce the behavior.
      value: |
        1. Install package version X
        2. Call method Y with parameters Z
        3. Observe error
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: Expected Behavior
      description: What you expected to happen.
    validations:
      required: true

  - type: textarea
    id: actual
    attributes:
      label: Actual Behavior
      description: What actually happened. Include any error messages or stack traces.
    validations:
      required: true

  - type: input
    id: dotnet-version
    attributes:
      label: .NET Version
      description: "Output of `dotnet --version`"
      placeholder: "8.0.100"
    validations:
      required: true

  - type: dropdown
    id: os
    attributes:
      label: Operating System
      options:
        - Windows
        - macOS
        - Linux
    validations:
      required: true

  - type: textarea
    id: additional
    attributes:
      label: Additional Context
      description: Any other context about the problem (project type, related packages, etc.)

機能リクエストテンプレート

# .github/ISSUE_TEMPLATE/feature_request.yml
name: Feature Request
description: Suggest a new feature or enhancement
title: "[Feature]: "
labels: ["enhancement"]
body:
  - type: textarea
    id: problem
    attributes:
      label: Problem Statement
      description: Describe the problem this feature would solve.
      placeholder: "I'm always frustrated when..."
    validations:
      required: true

  - type: textarea
    id: solution
    attributes:
      label: Proposed Solution
      description: Describe the solution you'd like to see.
    validations:
      required: true

  - type: textarea
    id: alternatives
    attributes:
      label: Alternatives Considered
      description: Describe any alternative solutions or features you've considered.

  - type: textarea
    id: api-surface
    attributes:
      label: API Surface (if applicable)
      description: |
        If you have a proposed API design, include it here.
      render: csharp

質問／ディスカッションテンプレート

# .github/ISSUE_TEMPLATE/question.yml
name: Question
description: Ask a question about using the library
title: "[Question]: "
labels: ["question"]
body:
  - type: textarea
    id: question
    attributes:
      label: Question
      description: What would you like to know?
    validations:
      required: true

  - type: textarea
    id: context
    attributes:
      label: Context
      description: |
        Provide context about what you're trying to accomplish.
        Include code snippets if relevant.
      render: csharp

Issue テンプレートの設定

# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: Discussions
    url: https://github.com/mycompany/my-library/discussions
    about: Use discussions for general questions and community support
  - name: Stack Overflow
    url: https://stackoverflow.com/questions/tagged/my-library
    about: Search for existing answers on Stack Overflow

PR テンプレート

プルリクエストテンプレート



## Description



## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Documentation update
- [ ] Refactoring (no functional changes)
- [ ] Performance improvement

## Testing Checklist

- [ ] Unit tests added/updated
- [ ] Integration tests added/updated (if applicable)
- [ ] All existing tests pass (`dotnet test`)
- [ ] Code compiles without warnings (`dotnet build -warnaserror`)

## Breaking Changes



N/A

## Related Issues



## Additional Notes

GitHub Pages の設定

GitHub Pages では、Starlight、Docusaurus、または DocFX で生成したドキュメントサイトをホストできます。このセクションではリポジトリの設定を説明します。CI デプロイパイプラインの設定については、[skill:dotnet-gha-deploy] を参照してください。

リポジトリの設定

Settings > Pages に移動します
Source で GitHub Actions を選択します（従来のブランチベースのデプロイは選択しないでください）
.github/workflows/ のデプロイワークフローが、ビルドと公開の手順を処理します

ドキュメントサイトのディレクトリ構成

ドキュメントのソースファイルは、リポジトリのルートにある docs/ ディレクトリに配置します：

my-library/
  src/
    MyLibrary/
      MyLibrary.csproj
  docs/
    astro.config.mjs          # For Starlight
    # OR docusaurus.config.js  # For Docusaurus
    # OR docfx.json            # For DocFX
  .github/
    workflows/
      deploy-docs.yml          # Deployment workflow -- see [skill:dotnet-gha-deploy]
  README.md
  CONTRIBUTING.md

カスタムドメイン

GitHub Pages のカスタムドメインを設定します：

ドキュメントサイトの静的ファイル用ディレクトリに CNAME ファイルを追加します（例：Starlight では docs/public/CNAME、Docusaurus では docs/static/CNAME）
Settings > Pages > Custom domain でドメインを設定します
Enforce HTTPS を有効にします

CNAME ファイルの内容：

docs.mylibrary.dev

ドキュメントプラットフォームの選定と設定については、[skill:dotnet-documentation-strategy] を参照してください。デプロイワークフローの YAML については、[skill:dotnet-gha-deploy] を参照してください。

リポジトリのメタデータ

CODEOWNERS

自動レビュー担当者割り当てのために、コードの所有権を定義します：

# .github/CODEOWNERS

# Default owner for everything
* @mycompany/core-team

# Documentation
/docs/ @mycompany/docs-team
*.md @mycompany/docs-team

# Source code by area
/src/MyLibrary.Core/ @mycompany/core-team
/src/MyLibrary.Data/ @mycompany/data-team

# Build and CI
/.github/ @mycompany/devops-team
/build/ @mycompany/devops-team
*.props @mycompany/core-team
*.targets @mycompany/core-team

# NuGet configuration
nuget.config @mycompany/core-team
Directory.Packages.props @mycompany/core-team

FUNDING.yml

GitHub Sponsors などの資金援助リンクを設定します：

# .github/FUNDING.yml
github: [maintainer-username]
open_collective: my-library
custom: ["https://www.buymeacoffee.com/maintainer"]

ソーシャルプレビュー

Settings > General > Social preview に移動します
1280x640 の画像（アスペクト比 2:1）をアップロードします
プロジェクト名、ロゴ、簡潔なタグライン、.NET バージョンのバッジを含めます
一貫性のあるブランドカラーを使用します

トピックとタグ

見つけやすくするために、リポジトリのトピックを追加します：

dotnet、csharp、nuget -- エコシステムのタグ
library、sdk、framework -- プロジェクトの種類
aspnetcore、efcore、blazor -- 技術固有のタグ
説明的なタグ：serialization、logging、dependency-injection など

Settings > General > Topics またはメインページのリポジトリの説明欄からトピックを設定します。

リポジトリの説明

リポジトリの説明は簡潔にします（350 文字未満）。次の内容を含めます：

プロジェクトの機能
主な差別化要素または主な用途
該当する場合は対象となる .NET バージョン

例：「ソースジェネレーター対応と AOT 互換性を備えた、.NET 8 以降向けの高性能 JSON シリアライザーライブラリ。」

エージェントに関する注意点

Markdown テンプレート（.md）ではなく、必ず YAML ベースの課題テンプレート（.yml）を使用してください -- YAML テンプレートでは、検証機能、ドロップダウン、必須項目を備えた構造化フォームフィールドを利用できます。Markdown テンプレートは従来の形式で、入力検証機能はありません。
.github/ISSUE_TEMPLATE/ ディレクトリには config.yml を必ず配置してください -- これがない場合、「空の課題」オプションがデフォルトで表示されます。blank_issues_enabled: false を設定して、ユーザーが必ずテンプレートを使用するようにしてください。
バッジの URL には正しい NuGet パッケージ ID を使用してください -- shields.io ではパッケージ ID の大文字と小文字が区別されます。NuGet.org に登録されている正確な ID（例：newtonsoft.json ではなく Newtonsoft.Json）を使用してください。
CODEOWNERS のパターンは .gitignore の構文に従います -- ルート相対パスには /src/ を使用してください。先頭に / がない場合、ツリー内のどこにあるパスにも一致します。
GitHub Pages のソースは「GitHub Actions」に設定してください -- 従来の「ブランチからデプロイ」モードでは、カスタムビルド手順をサポートしていません。GitHub Actions ソースを使うと、ビルドとデプロイがワークフローに委ねられます。ワークフローの YAML については、[skill:dotnet-gha-deploy] を参照してください。
このスキルでは CI/CD デプロイ用の YAML を生成しないでください -- GitHub Pages のデプロイワークフローは [skill:dotnet-gha-deploy] の対象です。このスキルの対象は、リポジトリの構成とテンプレートの内容のみです。
変更履歴の内容は生成しないでください -- 変更履歴の形式、バージョン管理方針、リリースノートは [skill:dotnet-release-management] の対象です。README では CHANGELOG.md を参照しますが、ここではその形式を定義しないでください。
PR テンプレートのファイル名は、正確に pull_request_template.md としてください -- GitHub が認識するのは、この正確なファイル名のみです（大文字と小文字は区別されません）。ルート、docs/、または .github/ ディレクトリに配置できます。課題テンプレートとの一貫性を保つため、.github/ への配置を推奨します。
バグ報告テンプレートに .NET Version を含めてください -- バグを再現するには .NET のバージョンが重要です。想定する形式には dotnet --version の出力を使用してください。プラットフォームによって動作が異なることが多いため、OS はドロップダウン形式にしてください。
README の Mermaid 図は GitHub 上でネイティブにレンダリングされます -- 特別な設定は必要ありません。mermaid 言語識別子を指定した標準的なフェンス付きコードブロックを使用してください。アーキテクチャセクションに埋め込む .NET 固有の図のパターンについては、[skill:dotnet-mermaid-diagrams] を参照してください。

Markdown 対応

ログインしてコメント

基本情報

作者: wshaddix
リポジトリ: wshaddix/dotnet-skills
カテゴリ: 開発
インストール数: 70
GitHub スター: 86

問題を報告