.NET 설명서 리포지토리에 기여

아티클
08/10/2023

.NET 문서에 기여하는 데 관심을 가져주셔서 감사합니다!

이 문서에서는 .NET 문서 사이트에서 호스팅되는 문서 및 코드 샘플에 참여하는 프로세스를 다룹니다. 기여는 오타 수정만큼 간단하거나 새 문서처럼 복잡할 수 있습니다.

.NET 설명서 사이트는 여러 리포지토리에서 빌드됩니다. 다음은 그 중 일부에 불과합니다.

기여 지침

설명서에 대한 커뮤니티 기여에 감사드립니다. 다음 목록에서는 .NET 설명서에 기여할 때 유의해야 할 몇 가지 지침 규칙을 보여 있습니다.

금지 대규모 끌어오기 요청을 제공합니다. 대신, 많은 시간을 투자하기 전에 방향에 동의할 수 있도록 문제를 저장하고 토론을 시작합니다.
문서에 샘플 코드를 인라인으로 포함하지 마세요.
문서에 포함할 코드와 함께 코드 조각 프로젝트를 사용하세요.
DO는 다음 지침과 음성 및 톤 지침을 따릅니다.
권고템플릿 파일을 작업의 시작점으로 사용합니다.
권고 문서에서 작업하기 전에 포크의 별도 분기를 만듭니다.
GitHub 흐름을 따릅니다.
원하는 경우 기여에 관해 블로그 및 트윗(또는 기타)을 합니다.

이러한 지침을 따르면 모두에게 더 나은 환경을 제공할 것입니다.

기여 프로세스

1단계: 새 콘텐츠를 작성하거나 기존 콘텐츠를 철저히 수정하려는 경우 수행하려는 작업을 설명하는 문제를 엽니다. 문서 폴더 내의 콘텐츠는 목차(TOC)에 반영되는 섹션으로 구성됩니다. 목차에서 항목을 배치할 위치를 정의합니다. 제안에 대한 피드백을 가져옵니다.

또는

기존 문제를 선택하고 해결합니다. 다음과 같은 방법으로, 미해결 문제 목록을 보고 관심 있는 분야의 문제 해결에 자발적으로 참여할 수 있습니다.

잘, 좋은 첫 번째 문제에 대한 좋은 첫 번째 문제 레이블로 필터링합니다.
커뮤니티 기여에 적합한 문제에 대한 도움말 요청 레이블을 필터링합니다. 이 문제는 일반적으로 최소한의 컨텍스트가 필요합니다.
숙련된 기여자는 관심 있는 문제를 해결할 수 있습니다.

참여할 문제를 찾았으면 해당 문제가 미해결 상태인지 확인하기 위한 주석을 추가합니다.

작업 할 작업을 선택한 후 GitHub 계정을 만들고 2단계로 이동합니다.

2단계: 필요에 따라 리포지토리(또는 기여하는 리포지토리)를 포크 /dotnet/docs 하고 변경 내용에 대한 분기를 만듭니다.

작은 변경 내용은 브라우저에서 편집을 참조 하세요.

3단계: 이 새로운 분기를 변경합니다.

새 항목인 경우 이 템플릿 파일을 시작점으로 사용할 수 있습니다. 작성 지침을 포함하고 작성자 정보 등의 각 문서에 필요한 메타데이터도 설명합니다. Microsoft Learn 콘텐츠에 사용되는 Markdown 구문에 대한 자세한 내용은 Markdown 참조를 참조하세요.

1단계에서 문서에 대해 결정된 TOC 위치에 해당하는 폴더로 이동합니다. 해당 폴더에는 해당 섹션에 있는 모든 문서의 Markdown 파일이 포함됩니다. 필요한 경우에 콘텐츠에 대한 파일을 배치할 새 폴더를 만듭니다. 해당 섹션의 기본 문서를 index.md라고 합니다.

이미지 및 기타 정적 리소스를 위해 문서가 포함된 폴더 안에 media라는 하위 폴더를 만듭니다(아직 없는 경우). media 폴더 안에 문서 이름의 하위 폴더를 만듭니다(인덱스 파일 제외). 파일을 배치할 위치에 대한 자세한 내용은 폴더 구조의 예 섹션을 참조하세요.

컴파일되지 않는 구문을 시연하지 않는 한 문서에 코드를 인라인으로 포함하지 마세요. 대신 코드 조각 프로젝트를 사용하고 코드 확장을 사용하여 코드를 포함합니다. 그러면 샘플 코드가 CI 시스템에서 유효성을 검사합니다.

코드 조각의 경우 문서를 포함하는 폴더 내에 조각이라는 하위 폴더를 만듭니다(아직 없는 경우). 조각 폴더 내에서 문서 이름으로 하위 폴더를 만듭니다. 대부분의 경우 주요 .NET 언어인 C#, F# 및 Visual Basic 등 세 가지 모두의 코드 조각이 있습니다. 이 경우 세 프로젝트 각각에 대해 csharp, fsharp, vb라는 하위 폴더를 만듭니다. docs/csharp, docs/fsharp 또는 docs/visual-basic 폴더 아래에 각 문서에 대한 코드 조각을 만드는 경우 해당 코드 조각은 한 언어로만 작성되므로 언어 하위 폴더를 생략할 수 있습니다. 파일을 배치할 위치에 대한 자세한 내용은 폴더 구조의 예 섹션을 참조하세요.

코드 조각은 문서에 설명된 개념을 예시하는 요약된 작은 예제입니다. 다운로드 및 탐색을 위한 큰 프로그램은 dotnet/samples 리포지토리에 있어야 합니다. 전체 샘플은 샘플에 참여의 섹션을 참조하세요.

4단계: 분기에서 기본 분기 끌어오기 요청(PR)을 제출합니다.

Important

지금은 주석 자동화 기능을 .NET 리포지토리에서 사용할 수 없습니다. .NET 문서 팀의 구성원이 PR을 검토하고 병합합니다.

여러 문제가 같은 PR 수정과 관련되지 않은 한, 각 PR은 일반적으로 한 번에 하나의 문제를 해결해야 합니다. PR은 하나 이상의 파일을 수정할 수 있습니다. 여러 파일에서 여러 개의 수정 사항을 처리하는 경우 별도의 PR을 사용하는 것이 좋습니다.

PR에서 기존 문제를 해결하는 경우 PR 설명에 Fixes #Issue_Number 키워드를 추가합니다. 이렇게 하면 PR이 병합될 때 문제가 자동으로 닫힙니다. 자세한 내용은 Linking a pull request to an issue using a keyword(키워드를 사용하여 문제에 끌어오기 요청 연결)를 참조하세요.

.NET 팀은 PR를 검토하고, 승인을 받는 데 필요한 다른 업데이트/변경 내용이 있을 경우 알려 줍니다.

5단계: 팀에서 설명한 대로 분기에 필요한 모든 업데이트를 수행합니다.

유지 관리자는 피드백이 적용되고 변경 내용이 승인되면 PR을 기본 분기에 병합합니다.

정기적으로 기본 분기의 모든 커밋을 라이브 분기로 푸시하면 .NET 설명서에서 라이브로 기여한 내용을 확인할 수 있습니다. 일반적으로 업무 주간 동안 매일 게시합니다.

폴더 구조의 예

docs
  /about
  /core
    /porting
      porting-overview.md
      /media
        /porting-overview
          portability_report.png
        /shared ...
      /snippets
        /porting-overview
          /csharp
            porting.csproj
            porting-overview.cs
            Program.cs
          /fsharp
            porting.fsproj
            porting-overview.fs
            Program.fs
          /vb
            porting.vbproj
            porting-overview.vb
            Program.vb
        /shared
          /csharp ...
          /fsharp ...
          /vb ...

참고 항목

조각 아래의 언어 폴더는 하나의 언어로만 사용되는 언어 가이드 영역에 필요하지 않습니다. 예를 들어 C# 가이드에서는 모든 코드 조각이 C#이라고 가정합니다.

위의 구조에는 이미지 1개(portability_report.png) 및 porting-overview.md 문서에 포함된 코드 조각을 포함하는 코드 프로젝트 3개가 포함됩니다.

snippets/shared 폴더는 이전 예의 porting 폴더와 같이 같은 부모 폴더 내의 여러 문서에 걸쳐 있을 수 있는 코드 조각에 사용됩니다. 여러 문서에서 참조되지만, article-specific 폴더에서 컴파일할 수 없는 XAML 코드와 같이 반드시 그래야 하는 특별한 이유가 있는 경우에만 shared 폴더를 사용하세요.

이전 예의 porting 폴더와 같이 문서가 같은 부모 폴더에 있는 경우 문서 간에 미디어를 공유할 수도 있습니다. 가능하면 이 shared 폴더는 사용하지 않아야 하고, 타당한 경우에만 사용해야 합니다. 예를 들어 표시되는 앱에 대한 일반적인 로드 중 화면을 공유하거나 여러 문서에서 재사용되는 Visual Studio 대화 상자를 공유하는 것은 타당할 수 있습니다.

Important

포함된 조각 대부분이 기록을 위해 dotnet/docs 리포지토리의 /samples 폴더 아래에 저장됩니다. 문서에 중대한 변경 내용을 적용하는 경우 해당 코드 조각을 새 구조로 이동해야 합니다. 그러나 작은 변경 내용을 위한 코드 조각 이동에 대해서는 걱정할 필요가 없습니다.

샘플에 기여

콘텐츠를 지원하는 코드는 다음과 같이 구분합니다.

샘플: 독자가 샘플을 다운로드하고 실행할 수 있습니다. 모든 샘플은 전체 애플리케이션 또는 라이브러리여야 합니다. 샘플에서 라이브러리를 만드는 경우 독자가 코드를 실행할 수 있도록 하는 단위 테스트 또는 애플리케이션을 포함해야 합니다. 종종 둘 이상의 기술, 기능 또는 도구 키트를 사용합니다. 각 샘플의 readme.md 파일은 문서를 참조하므로 각 샘플에서 다루는 개념에 대해 자세히 읽을 수 있습니다.
코드 조각: 더 작은 개념이나 작업을 설명합니다. 컴파일되지만 전체 애플리케이션은 아닙니다. 올바르게 실행되어야 하지만 일반적인 시나리오의 예제 애플리케이션은 아닙니다. 대신 단일 개념이나 기능을 설명하기 위해 가능한 한 작게 설계됩니다. 단일 코드 화면을 초과하면 안됩니다.

샘플은 dotnet/samples 리포지토리에 저장됩니다. samples 폴더 구조가 docs 폴더 구조와 일치하는 모델을 만들기 위해 노력하고 있습니다. 따르는 표준은 다음과 같습니다.

최상위 폴더는 docs 리포지토리의 최상위 폴더와 일치합니다. 예를 들어 docs 리포지토리에는 machine-learning/tutorials 폴더가 있으며, 기계 학습 자습서의 샘플은 samples/machine-learning/tutorials 폴더에 있습니다.

또한 core 및 standard 폴더 아래의 모든 샘플은 .NET Core에서 지원하는 모든 플랫폼에서 빌드 및 실행되어야 합니다. CI 빌드 시스템에서 이 표준을 준수하는지 확인합니다. 최상위 framework 폴더에는 Windows에서만 빌드되고 유효성이 검사되는 샘플이 들어 있습니다.

샘플 프로젝트는 지정된 샘플에 대해 가능한 가장 광범위한 플랫폼에서 빌드하고 실행해야 합니다. 실제로, 가능한 경우 .NET Core 기반 콘솔 애플리케이션을 빌드하는 것을 의미합니다. 웹 또는 UI 프레임워크와 관련된 샘플은 필요에 따라 해당 도구를 추가해야 합니다. 예를 들어 웹 애플리케이션, 모바일 앱, WPF 또는 WinForms 앱 등이 있습니다.

모든 코드에 대한 CI 시스템을 갖추기 위해 노력하고 있습니다. 샘플을 업데이트할 때 각 업데이트가 빌드 가능한 프로젝트의 일부인지 확인합니다. 이상적으로 샘플의 정확성에 대한 테스트도 추가합니다.

만드는 전체 샘플마다 readme.md 파일이 포함되어야 합니다. 이 파일에는 샘플에 대한 간단한 설명(한두 개 단락)이 포함되어야 합니다. readme.md는 이 샘플을 탐색하여 배울 수 있는 점을 독자에게 설명해야 합니다. readme.md 파일에는 .NET 문서 사이트의 라이브 문서에 대한 링크도 포함되어야 합니다. 리포지토리의 지정된 파일이 해당 사이트에 매핑되는 위치를 확인하려면 리포지토리 경로의 /docs를 https://learn.microsoft.com/dotnet로 바꿉니다.

항목에는 샘플에 대한 링크도 포함됩니다. GitHub의 샘플 폴더에 바로 연결됩니다.

새 샘플 작성

샘플은 다운로드를 위한 전체 프로그램 및 라이브러리입니다. 샘플의 범위는 작을 수 있지만, 사용자가 직접 살펴보고 실험해 볼 수 있는 방법으로 개념을 예시합니다. 예제에 대한 지침에 따라 독자는 다운로드하고 살펴볼 수 있습니다. 각 지침의 예제로 PLINQ(병렬 LINQ) 샘플을 검토합니다.

샘플은 빌드 가능한 프로젝트의 일부여야 합니다. 가능한 경우 프로젝트는 .NET Core에서 지원하는 모든 플랫폼에 빌드되어야 합니다. 이에 대한 예외는 플랫폼별 기능 또는 플랫폼별 도구를 보여주는 샘플입니다.
샘플이 일관성을 유지하려면 런타임 코딩 스타일을 준수해야 합니다.

또한 새 개체를 인스턴스화할 필요가 없는 것을 시연할 때 인스턴스 메서드보다 static 메서드를 사용하는 것이 좋습니다.
샘플에는 적절한 예외 처리가 포함되어야 합니다. 샘플의 컨텍스트에서 throw될 수 있는 모든 예외를 처리해야 합니다. 예를 들어 사용자 입력을 검색하기 위해 Console.ReadLine 메서드를 호출하는 샘플은 메서드에 대한 인수로 문자열을 전달할 때 적절한 예외 처리를 사용해야 합니다. 마찬가지로 샘플에서 메서드 호출이 실패할 것으로 예상되는 경우 결과 예외를 처리해야 합니다. 예외 또는 SystemException과 같은 기본 클래스 예외가 아닌 메서드가 throw한 특정 예외를 항상 처리합니다.

샘플을 만들려면:

문제를 제출하거나 작업 중인 기존 보고서에 주석을 추가합니다.
샘플에 설명된 개념을 설명하는 항목을 작성합니다(예: docs/standard/linq/where-clause.md).
샘플을 작성합니다(예: WhereClause-Sample1.cs).

샘플을 호출하는 주 진입점이 있는 Program.cs를 만듭니다. 이미 있는 경우에는 샘플에 호출을 추가합니다.

public class Program
{
    public void Main(string[] args)
    {
        WhereClause1.QuerySyntaxExample();

        // Add the method syntax as an example.
        WhereClause1.MethodSyntaxExample();
    }
}

.NET SDK와 함께 설치할 수 있는 .NET CLI를 사용하여 모든 .NET 코드 조각 또는 샘플을 빌드합니다. 샘플을 빌드하고 실행하려면:

샘플 폴더로 이동하여 오류를 확인하기 위해 빌드합니다.
```
dotnet build
```
다음과 같이 샘플을 실행합니다.
```
dotnet run
```
샘플의 루트 디렉터리에 readme.md를 추가합니다.

여기에는 코드에 대한 간략한 설명이 포함되어야 하며 샘플을 참조하는 문서를 참조해야 합니다. readme.md의 맨 위에는 샘플 브라우저에 필요한 메타데이터가 있어야 합니다. 헤더 블록에는 다음 필드가 포함되어야 합니다.
```
---
name: "really cool sample"
description: "Learn everything about this really cool sample."
page_type: sample
languages:
  - csharp
  - fsharp
  - vbnet
products:
  - dotnet-core
  - dotnet
  - dotnet-standard
  - aspnet
  - aspnet-core
  - ef-core
---
```
- languages 컬렉션에는 샘플에 사용할 수 있는 언어만 포함되어야 합니다.
- products 컬렉션에는 샘플과 관련된 제품만 포함되어야 합니다.

명시된 경우를 제외하고 모든 샘플은 .NET에서 지원하는 플랫폼의 명령줄에서 빌드됩니다. Visual Studio와 관련된 샘플이 몇 가지 있으며 Visual Studio 2017 이상이 필요합니다. 또한 일부 샘플은 플랫폼별 기능을 나타내며 특정 플랫폼이 필요합니다. 다른 샘플 및 코드 조각에는 .NET Framework가 필요하고, Windows 플랫폼에서 실행되며, 대상 Framework 버전용 Developer Pack이 필요합니다.

C# 대화형 환경

문서에 포함된 모든 코드 조각은 언어 태그를 사용하여 원본 언어를 나타냅니다. C#의 짧은 코드 조각은 csharp-interactive 언어 태그를 사용하여 브라우저에서 실행되는 C# 코드 조각을 지정할 수 있습니다. (인라인 코드 조각은 csharp-interactive 태그를 사용하고, 원본에서 포함된 코드 조각의 경우 code-csharp-interactive 태그를 사용합니다.) 이러한 코드 조각은 문서에 코드 창과 출력 창을 표시합니다. 출력 창은 사용자가 코드 조각을 실행한 후 대화형 코드를 실행할 때의 모든 출력을 표시합니다.

C# 대화형 환경은 코드 조각 사용 방식을 변경합니다. 방문자는 코드 조각을 실행하여 결과를 볼 수 있습니다. 코드 조각 또는 해당 텍스트에 출력에 대한 정보가 포함되어야 하는지를 결정하는 데 많은 요소가 도움이 됩니다.

코드 조각을 실행하지 않고 예상 출력을 표시할 경우

초보자용 문서는 독자가 작업 출력을 예상 답변과 비교할 수 있도록 출력을 제공해야 합니다.
출력이 항목에 필수적인 코드 조각은 해당 출력을 표시해야 합니다. 예를 들어 서식 있는 텍스트의 문서는 코드 조각을 실행하지 않고 텍스트 서식을 표시해야 합니다.
코드 조각과 예상 출력이 모두 짧을 경우 출력을 표시하는 것이 좋습니다. 그러면 시간이 약간 절약됩니다.
현재 문화권 또는 고정 문화권이 출력에 미치는 영향을 설명하는 문서에서는 예상 출력에 대해 설명해야 합니다. 대화형 REPL(read–eval–print loop)은 Linux 기반 호스트에서 실행됩니다. 기본 문화권 및 고정 문화권은 운영 체제 및 머신마다 다른 출력을 생성합니다. 문서에서 Windows, Linux 및 Mac 시스템의 출력에 대해 설명해야 합니다.

코드 조각에서 예상 출력을 제외할 경우

코드 조각이 큰 출력을 생성하는 문서는 주석에 출력을 포함하지 않아야 합니다. 코드 조각이 실행되면 코드가 숨겨집니다.
코드 조각이 항목을 보여 주는 문서이지만, 출력이 해당 항목을 이해하는 데 필수적인 것은 아닙니다. 예를 들어 LINQ 쿼리를 실행하여 쿼리 구문을 설명한 이후에 출력 컬렉션에 모든 항목을 표시하는 코드입니다.

참고 항목

일부 항목은 현재 여기에 지정된 지침을 따르지 않을 수 있습니다. 사이트 전체에서 일관성을 달성하기 위해 노력하고 있습니다. 특정 목표에 대해 현재 추적 중인 열린 문제 목록을 확인하세요.

영어가 아닌 콘텐츠에 기여

MT(기계 번역) 콘텐츠에 대한 기여는 현재 허용되지 않습니다. MT 콘텐츠의 품질을 개선하기 위해 인공신경망 MT 엔진으로 전환했습니다. 인공신경망 MT 엔진을 학습하는 데 사용되는 HT(사람 번역) 콘텐츠 기여를 허용하고 권장합니다. 따라서 시간이 지남에 따라 HT 콘텐츠 기여는 HT 및 MT의 품질을 모두 개선합니다. MT 토픽에는 토픽의 일부가 MT일 수 있음을 나타내는 고지 사항이 있으며, 편집을 사용할 수 없으므로 편집 단추가 표시되지 않습니다.

참고 항목

지역화된 대부분 설명서는 GitHub를 통해 피드백을 편집하거나 제공하는 기능을 제공하지 않습니다. 지역화된 콘텐츠에 대한 피드백을 제공하려면 양식을 사용합니다 https://aka.ms/provide-feedback .

기여자 라이선스 계약

PR을 병합하기 전에 .NET Foundation CLA(기여 라이선스 계약)에 서명해야 합니다. .NET Foundation의 프로젝트에 대한 일회성 요구 사항입니다. Wikipedia에서 CLA(기여 라이선스 계약)에 대해 참고할 수 있습니다.

계약: .NET Foundation CLA(기여자 사용권 계약)

계약서에 미리 서명할 필요가 없습니다. PR을 일반적인 방식으로 복제하고, 포크하고, 제출할 수 있습니다. PR이 만들어지면 CLA 봇에 의해 분류됩니다. 변경 내용이 작은 경우(예:오타를 수정한 경우) PR에 cla-not-required로 레이블이 지정됩니다. 그렇지 않으면 cla-required로 분류됩니다. CLA에 서명하면 현재 및 이후의 모든 끌어오기 요청에 cla-signed 레이블이 지정됩니다.

다음을 통해 공유

.NET 설명서 리포지토리에 기여

기여 지침

기여 프로세스

폴더 구조의 예

샘플에 기여

새 샘플 작성

C# 대화형 환경

코드 조각을 실행하지 않고 예상 출력을 표시할 경우

코드 조각에서 예상 출력을 제외할 경우

영어가 아닌 콘텐츠에 기여

기여자 라이선스 계약

피드백

추가 리소스