Azure
/
azure-sdk-korean
зеркало из https://github.com/Azure/azure-sdk-korean.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Merge branch 'main' into contribution

This commit is contained in:
Ian Y. Choi 2023-07-31 00:00:42 +09:00 коммит произвёл GitHub
Родитель 032b79601c e1926341c0
Коммит 6a65f92146
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
9 изменённых файлов: 241 добавлений и 247 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

10
Gemfile.lock
Просмотреть файл

@ -221,17 +221,15 @@ GEM
rb-fsevent (~> 0.10, >= 0.10.3)
rb-inotify (~> 0.9, >= 0.9.10)
mercenary (0.3.6)
mini_portile2 (2.8.1)
minima (2.5.1)
jekyll (>= 3.5, < 5.0)
jekyll-feed (~> 0.9)
jekyll-seo-tag (~> 2.1)
minitest (5.18.0)
multipart-post (2.1.1)
nokogiri (1.13.8-arm64-darwin)
racc (~> 1.4)
nokogiri (1.13.8-x64-mingw32)
racc (~> 1.4)
nokogiri (1.13.8-x86_64-linux)
nokogiri (1.14.3)
mini_portile2 (~> 2.8.0)
racc (~> 1.4)
octokit (4.21.0)
faraday (>= 0.9)
@ -239,7 +237,7 @@ GEM
pathutil (0.16.2)
forwardable-extended (~> 2.6)
public_suffix (4.0.7)
racc (1.6.0)
racc (1.6.2)
rb-fsevent (0.11.2)
rb-inotify (0.10.1)
ffi (~> 1.0)

10
_data/sidebars/general_sidebar.yml
Просмотреть файл

@ -126,7 +126,7 @@ entries:
folderitems:
- title: Design (영문)
url: /ios_design.html
- title: Implementation (영문)
- title: Implementation
url: /ios_implementation.html
- title: GitHub 저장소
folderitems:
@ -140,11 +140,11 @@ entries:
url: /policies_pipelines.html
- title: 정책
folderitems:
- title: Review Process (영문)
- title: 리뷰 프로세스
url: /policies_reviewprocess.html
- title: Releases (영문)
- title: 릴리즈
url: /policies_releases.html
- title: Release notes (영문)
- title: 릴리즈 노트
url: /policies_releasenotes.html
- title: Support
- title: 지원
url: /policies_support.html

2
_data/topnav.yml
Просмотреть файл

@ -3,8 +3,6 @@ topnav:
items:
- title: SDK 블로그 (영문)
external_url: https://aka.ms/azsdk/blog
- title: Developer Korea 블로그
external_url: https://microsoft.github.io/developerkorea/
topnav_dropdowns:

50
docs/general/compatibility.md
Просмотреть файл

@ -6,46 +6,44 @@ folder: general
sidebar: general_sidebar
---
This section describes guidelines related to compatibility. In particular, it describes high-level compatibility principles, and detailed rules for reasoning about API and behavioral changes introduced as we evolve our libraries.
이 섹션은 호환성과 관련된 가이드라인을 설명합니다. 특히, 라이브러리를 발전시키면서 도입되는 API와 동작 변경에 대한 높은 수준의 호환성 원칙과 상세한 규칙에 대해 다룹니다.
## Compatibility Principles
One of the main general principles of the Azure SDK is that it is **Dependable**, and one of the main aspects of dependability is a high level of compatibility.
## 호환성 원칙
Azure SDK의 주요 일반 원칙 중 하나는 **의존성**이며, 의존성의 주요 측면 중 하나는 높은 수준의 호환성입니다.
In the context of these guideline, compatibility means that software written using one version of our libraries should function correctly when upgraded to a newer version of the same library, as long as it calls the same version of the service REST API as it was calling before the upgrade.
This is to ensure that developers using the Azure SDK can upgrade to new versions of our libraries without immediately being subjected to a large cost of fixing resulting breaks.
This is good for our customers, as it lowers their costs, and it's good for us, as it helps in the adoption of new Azure features, i.e. a win-win.
이러한 지침에서 호환성이란, 한 버전의 라이브러리를 사용하여 작성된 소프트웨어가 더 높은 버전의 같은 라이브러리로 업그레이드되더라도 이전 업그레이드 전과 동일한 서비스 REST API 버전을 호출한다면 올바르게 동작해야 함을 의미합니다.
이를 통해 Azure SDK를 사용하는 개발자들은 새로운 라이브러리 버전으로 업그레이드할 때 큰 비용을 들여 오류를 수정할 필요 없이 업그레이드할 수 있습니다.
또한 이것은 고객에게 비용을 절감해주는 것이며, 새로운 Azure 기능의 채택에 도움이 되므로 상호 이익적인 관계입니다.
Having said that, you can always imagine code, even if contrived, that will break when upgraded to a new version of a library that simply adds functionality, fixes bugs, or runs faster.
Also, there are some incompatible changes that are worth doing, e.g. changes required to fix security bugs.
And so given that absolute compatibility is not possible in practice, we want to be best-in-class, which as a rule of thumb means being on par with base libraries of the corresponding language.
물론, 앞서 언급한 내용에 따르면, 라이브러리의 새 버전으로 업그레이드하더라도 기능을 추가하거나 버그를 수정하거나 실행 속도를 개선하는 등의 변경사항으로 인해 단순히 업그레이드만으로는 항상 호환성이 보장되지는 않을 수 있습니다. 또한 보안 버그를 수정하는 데에는 일부 호환성을 깨는 변경이 필요할 수도 있습니다. 그렇기 때문에 절대적인 호환성을 보장하는 것은 실제로 불가능하며, 대신 우리는 최고 수준의 호환성을 목표로 하고 있습니다. 대략적인 기준으로는 해당 언어의 기본 라이브러리와 동등한 수준의 호환성을 유지하는 것을 지향합니다.
Principle #1: Azure SDK libraries must be as compatible or better than the base libraries of their language. For example, Azure SDK for .NET libraries must be as compatible as the .NET Base Class Libraries.
원칙 #1: Azure SDK 라이브러리는 해당 언어의 기본 라이브러리와 호환성이 동등하거나 더 좋아야 합니다. 예를 들어, .NET용 Azure SDK 라이브러리는 .NET 기본 클래스 라이브러리와 호환성이 동등해야 합니다.
### Azure SDK Compatibility Reviews
Azure SDK guidelines define details of what's considered a compatible change in each language ecosystem. All changes that are not explicitly designated as compatible, need to be reviewed and approved by the Azure SDK Architecture Board.
### Azure SDK 호환성 검토
Azure SDK 가이드라인은 각 언어 생태계에서 호환성을 보장하는 변경 사항에 대한 세부 정보를 정의합니다. 명시적으로 호환성이 지정되지 않은 모든 변경 사항은 Azure SDK 아키텍처 위원회의 검토와 승인을 거쳐야 합니다.
### API Changes
It might seem that additions to the APIs would be non-breaking, and removals would be breaking. Unfortunately, it's not as simple. Languages differ quite significantly in terms of what API changes would result in breaks in the caller. In particular, there are very significant differences between dynamic and static languages. Therefore, you should refer to language specific guidelines for details of what constitutes an acceptable API change.
### API 변경
API에 새로운 기능이 추가되는 경우, 일반적으로 호환성을 깨지 않지만, 기존 기능이 삭제되는 경우에는 호환성을 깨는 요소로 보일 수 있습니다. 그러나 이 문제는 간단하지 않습니다. 언어에 따라 호출자에서 브레이크가 발생하는 API 변경이 상당히 다를 수 있습니다. 특히 동적 언어와 정적 언어 사이에는 매우 큰 차이가 있습니다. 따라서 호환성이 허용되는 API 변경에 대한 자세한 내용은 해당 언어별 가이드라인을 참조해야 합니다.
Behavioral compatibility is more language independent, and so it's described below.
동작 호환성은 언어에 상대적으로 덜 종속적이므로 이에 대한 설명은 아래에서 확인할 수 있습니다.
### Behavioral Changes
TBD
미정
#### Logging Changes
Changes to the output of logs generated by a library are treated separately from other behavioral change, and they are described in this section.
#### Logging 변경
로그 라이브러리에서 생성되는 로그 출력에 대한 변경은 다른 동작 변경과는 별도로 처리됩니다. 아래의 글은 이에 대한 설명입니다.
Many customers build scripts and tools that automatically analyze logs. Just like we don't want software calling our APIs to break when the software is upgraded to new versions of our libraries, we don't want log analysis tools and scripts to break.
많은 고객들이 로그를 자동으로 분석하는 스크립트와 도구를 사용합니다. 따라서 소프트웨어가 우리의 API를 호출할 때 새로운 라이브러리 버전으로 업그레이드되어도 소프트웨어 호출이 깨지지 않도록 주의해야 합니다. 마찬가지로 로그 분석 도구와 스크립트 역시 깨지지 않기를 바랍니다.
Logs can be seen as a sequence of entries, and entries can be seen as a sequence of tokens that can be parsed by tools. Entry tokens can be further divided into schema related tokens (i.e. tokens that don't vary between instances of entries), and data tokens (tokens that can, and often do, vary between instances of entries, e.g. the time when an entry was logged).
로그는 항목들의 시퀀스로 간주될 수 있으며, 각 항목은 도구에 의해 구문 분석될 수 있는 토큰들의 시퀀스로 해석됩니다. 항목 토큰들은 스키마 관련 토큰과 데이터 토큰으로 나뉠 수 있습니다. 스키마 관련 토큰은 항목들의 인스턴스 간에 변하지 않는 토큰들이며, 데이터 토큰은 항목들의 인스턴스 간에 변할 수 있는 토큰들입니다. 예를 들어, 항목에는 로그가 기록된 시간과 같은 정보를 포함할 수 있습니다.
Changes allowed in a new major or minor version of a package (not a patch version):
새로운 주요 또는 부 버전의 패키지에서 허용되는 변경 사항은 다음과 같습니다:
- Additional log entries, e.g. new version logs request details on every retry, while the old version logged only once per retry.
- Additional entry types (entries with a new schema).
- 추가적인 로그 항목들을 포함시키는 것입니다. 예를 들어, 새로운 버전은 각 재시도마다 요청에 대한 세부 정보를 기록할 수 있지만, 이전 버전은 재시도당 한 번만 기록할 수 있습니다.
- 새로운 스키마를 가진 항목 유형을 추가합니다.
All other changes allowed only when:
그러나 다른 모든 변경 사항들은 다음의 경우에만 허용됩니다:
- Approved by the Azure SDK Architecture Board, and
- User must opt into the new behavior by specifying a new API version or a client option.
- Azure SDK 아키텍처 위원회의 승인을 받아야 합니다.
- 사용자는 새로운 동작을 선택하기 위해 새로운 API 버전 또는 클라이언트 옵션을 지정해야 합니다.

19
docs/general/introduction.md
Просмотреть файл

@ -9,7 +9,7 @@ sidebar: general_sidebar
본 공통 가이드라인 문서는 다음과 같은 분들에게 유용합니다:
* 언어별 가이드라인 작성자
* 특정 언어 가이드라인이 있지 않은 클라이언트 라이브러리 디자이너
* 특정 언어 가이드라인이 없는 클라이언트 라이브러리 디자이너
특정 언어 가이드라인이 없는 언어로 작업하는 경우, Azure Developer Experience [Architecture Board]와 더욱 긴밀하게 협력하여 클라이언트 라이브러리가 적절하게 설계되고 개발자 경험이 모범적인지 확인하세요.
@ -25,9 +25,9 @@ Azure SDK는 Azure 서비스에 연결하는 개발자의 생산성을 증대시
### 일관성있게 (Consistent)
* 클라이언트 라이브러리는 언어와, 다른 언어와, 서비스 모두에 대해 일관적이어야 합니다. 충돌이 일어날 것을 생각해 언어의 일관성은 가장 높은 우선순위를 가져야 하며, 다른 언어와의 일관성은 비교적 가장 낮은 우선순위를 가집니다.
* 클라이언트 라이브러리는 같은 언어, 서비스, 다른 언어들끼리도 모두 일관적이어야 합니다. 충돌이 일어날 것을 생각해 언어의 일관성은 가장 높은 우선순위를 가져야 하며, 다른 언어와의 일관성은 비교적 가장 낮은 우선순위를 가집니다.
* 로깅, HTTP 통신, 에러 핸들링과 같은 서비스와 관련없는 개념들도 일관적이어야 합니다. 개발자가 다른 클라이언트 라이브러리 간 이동할 때 이러한 개념들을 다시 학습할 필요가 없게 해야 합니다.
* 클라리언트 라이브러리와 그 서비스 간 용어의 일관성은 진단하는 데 도움을 주는 좋은 것입니다.
* 클라이언트 라이브러리와 그 서비스 간 용어의 일관성은 진단하는 데 도움을 주는 좋은 것입니다.
* 서비스와 클라이언트 라이브러리 간 모든 차이점들은 일시적인 이유가 아니라 기존의 관습적인 사용을 기반으로 합당한 이유가 있어야할 것입니다.
* 각각 언어의 Azure SDK은 한 팀에서 하나의 제품이 나오는 것처럼 느껴져야 합니다.
* 해당 언어 간 동일한 기능이 있어야 합니다. 서비스의 동일한 기능보다 더 중요한 부분입니다.
@ -35,8 +35,8 @@ Azure SDK는 Azure 서비스에 연결하는 개발자의 생산성을 증대시
### 접근하기쉽게 (Approachable)
* 우리는 지원하는 기술의 전문가입니다. 그래서 우리의 고객인 개발자까지 전문적인 지식을 필요로 하지는 않아도 될 것입니다.
* 개발자들이 튜토리얼, 예제, 아티클, API 문서 등 양질의 문서를 찾아볼 수 있게 해야합니다. 그래서 Azure 서비스를 쉽게 성공할 수 있어야 합니다.
* 베스트 프랙티스를 적용할 수 있는 예측 가능한 기본값들을 사용해 쉽게 시작할 수 있어야 합니다. 점진적으로 개념을 소개할 수 있게 생각해보세요.
* 개발자들이 Azure 서비스를 쉽게 성공시킬 수 있는 튜토리얼, 예제, 아티클, API 문서 등 양질의 문서를 찾아볼 수 있게 해야합니다.
* 모범 사례를 구현할 수 있는 예측 가능한 기본값들을 사용해 쉽게 시작할 수 있어야 합니다. 점진적으로 개념을 소개할 수 있게 생각해보세요.
* SDK는 해당 언어와 생태계의 가장 일반적인 매커니즘을 통해 쉽게 얻을 수 있어야 합니다.
* 개발자들이 새로운 서비스 개념을 배우는 데 사로잡힐 수 있게 해야 합니다. 핵심 사용 사례를 발견할 수 있어야 합니다.
@ -45,14 +45,15 @@ Azure SDK는 Azure 서비스에 연결하는 개발자의 생산성을 증대시
* 개발자가 어떻게 돌아가는지 쉽게 이해할 수 있게 해야합니다.
* 어느 상황에서 네트워크 호출이 이루어지는지 인지할 수 있어야 합니다.
* 기본값들을 알 수 있어야 하며 그 의도 또한 명확해야 합니다.
* 노깅, 추적, 예외처리는 기본적이며, 신중해야 합니다.
* 에러 메시지는 간결하고, 서비스과 연관있어야 하고, 이용할 수 있어야 하며 사람이 읽을 수 있게 해야합니다.
* 로깅, 추적, 예외처리는 기본적이며, 신중해야 합니다.
* 에러 메시지는 간결하고, 서비스와 연관있어야 하고, 이용할 수 있어야 하며 사람이 읽을 수 있게 해야합니다.
* 해당 언어의 선호되는 디버거들과의 통합이 쉬워야 합니다.
### 믿음직하게 (Dependable)
* 갑작스러운 변화는 대부분의 새로운 기능보다 사용자 경험에 좋지 않으며 개선사항이 유익합니다.
* 매우 합당한 이유와 리뷰 없이 호환성을 깨버려서는 안됩니다. 의도적으로라도 이를 막아야 합니다.
* 호환성에 영향을 줄 수 있는 디펜던시에 의존해서는 안됩니다.
* 매우 합당한 이유와 리뷰 없이 의도적으로 호환성을 깨버려서는 안됩니다.
* 호환성에 영향을 줄 수 있는 종속성에 의존해서는 안됩니다.
{% include refs.md %}

104
docs/ios/implementation.md
Просмотреть файл

@ -1,34 +1,34 @@
---
title: "iOS Guidelines: Implementation"
title: "iOS 가이드라인: 구현"
keywords: guidelines ios
permalink: ios_implementation.html
folder: ios
sidebar: general_sidebar
---
## API Implementation
## API 구현
This section describes guidelines for implementing Azure SDK client libraries. Please note that some of these guidelines are automatically enforced by code generation tools.
이 섹션에서는 Azure SDK 클라이언트 라이브러리를 구현하기 위한 지침을 설명합니다. 이러한 지침 중 일부는 코드 생성 도구에 의해 자동으로 적용됩니다.
{% include requirement/MUSTNOT id="ios-implementation" %} allow implementation code (that is, code that doesn't form part of the public API) to be mistaken as public API. Implementation code can be made internal or file-private and placed within the same source file as the consuming code.
{% include requirement/MUSTNOT id="ios-implementation" %} 구현 코드(즉, 공개 API의 일부를 구성하지 않은 코드)를 공개 API로 오인하지 않도록 하십시오. 구현 코드는 내부 또는 파일 전용으로 만들 수 있으며 소비 코드와 동일한 소스 파일 내에 배치할 수 있습니다.
### Service Client
### 서비스 클라이언트
> TODO: Add introductory sentence.
#### Service Methods
#### 서비스 메소드
> TODO: Add introductory sentence.
##### Using the HTTP Pipeline
##### HTTP 파이프라인 사용
The Azure SDK team has provided an `AzureCore` library that contains common mechanisms for cross cutting concerns such as configuration and doing HTTP requests.
Azure SDK 팀은 구성이나 HTTP 요청 등의 횡단 관심사(cross cutting concerns)에 관한 일반적인 매커니즘이 포함된 `AzureCore` 라이브러리를 제공하고 있습니다.
{% include requirement/MUST id="ios-requests-use-pipeline" %} use the HTTP pipeline component within `AzureCore` for communicating to service REST endpoints.
{% include requirement/MUST id="ios-requests-use-pipeline" %} endpoints를 서비스하기 위해 `AzureCore` 내의 HTTP 파이프라인 컴포넌트를 사용하십시오.
The HTTP pipeline consists of a HTTP transport that is wrapped by multiple policies. Each policy is a control point during which the pipeline can modify either the request and/or response. We prescribe a default set of policies to standardize how client libraries interact with Azure services. The order in the list is the most sensible order for implementation.
HTTP pipeline은 여러 정책에 의해 래핑된 HTTP transport로 구성되어 있습니다. 각 정책은 파이프라인이 요청 및/또는 응답을 수정할 수 있는 제어 지점입니다. 우리는 클라이언트 라이브러리가 Azure 서비스와 상호 작용하는 방법을 표준화하는 기본 정책 세트를 규정합니다. 리스트의 순서는 구현에 있어 가장 합리적인 순서입니다.
{% include requirement/MUST id="ios-requests-implement-policies" %} include the following policies provided by `AzureCore` when constructing the HTTP pipeline:
{% include requirement/MUST id="ios-requests-implement-policies" %} HTTP 파이프라인을 구성할 때 `AzureCore` 에 의해 제공되는 아래의 정책들을 포함하십시오:
- Telemetry
- Unique Request ID
@ -37,104 +37,104 @@ The HTTP pipeline consists of a HTTP transport that is wrapped by multiple polic
- Response downloader
- Logging
{% include requirement/SHOULD id="ios-requests-use-azurecore-impl" %} use the policy implementations in `AzureCore` whenever possible. Do not try to "write your own" policy unless it is doing something unique to your service. If you need another option to an existing policy, engage with the [Architecture Board] to add the option.
{% include requirement/SHOULD id="ios-requests-use-azurecore-impl" %} 가능한 한 `AzureCore` 의 정책 구현을 사용하십시오. 서비스의 고유한 것이 아니라면 정책을 "직접 작성하려고" 하지 마십시오. 기존 정책에 다른 옵션이 필요한 경우 [Architecture Board] 와 협력하여 옵션을 추가하십시오.
### Supporting Types
### 지원 타입
> TODO: Add introductory sentence.
#### Model Types
#### 모델 타입
> TODO
## SDK Feature Implementation
## SDK 기능 구현
> TODO: Add introductory sentence.
### Configuration
### 구성
When configuring your client library, particular care must be taken to ensure that the consumer of your client library can properly configure the connectivity to your Azure service both globally (along with other client libraries the consumer is using) and specifically with your client library.
클라이언트 라이브러리를 구성할 때 클라이언트 라이브러리의 소비자가 전역적으로(소비자가 사용하는 다른 클라이언트 라이브러리와 함께) 특히 클라이언트 라이브러리와 함께 Azure 서비스에 대한 연결을 적절하게 구성할 수 있도록 특별한 주의를 기울여야 합니다.
#### Client configuration
#### 클라이언트 구성
{% include requirement/MUST id="ios-config-global-config" %} use relevant global configuration settings either by default or when explicitly requested to by the user, for example by passing in a configuration object to a client constructor.
{% include requirement/MUST id="ios-config-global-config" %} 기본적으로 또는 사용자가 명시적으로 요청한 경우(예: 구성 개체를 클라이언트 생성자에 전달) 관련 전역 구성 설정을 사용하세요.
{% include requirement/MUST id="ios-config-for-different-clients" %} allow different clients of the same type to use different configurations.
{% include requirement/MUST id="ios-config-for-different-clients" %} 동일한 유형의 다른 클라이언트는 다른 구성을 사용하도록 하십시오.
{% include requirement/MUST id="ios-config-optout" %} allow consumers of your service clients to opt out of all global configuration settings at once.
{% include requirement/MUST id="ios-config-optout" %} 서비스 클라이언트의 소비자는 모든 글로벌 구성 설정을 한 번에 선택할 수 있도록 하십시오.
{% include requirement/MUST id="ios-config-global-overrides" %} allow all global configuration settings to be overridden by client-provided options. The names of these options should align with any user-facing global configuration keys.
{% include requirement/MUST id="ios-config-global-overrides" %} 모든 글로벌 구성 설정을 클라이언트 제공 옵션에서 재정의할 수 있도록 하십시오. 이러한 옵션의 이름은 어떤 user-facing 글로벌 구성 키와도 일치해야 합니다.
{% include requirement/MUSTNOT id="general-config-behaviour-changes" %} change behavior based on configuration changes that occur after the client is constructed. Hierarchies of clients inherit parent client configuration unless explicitly changed or overridden. Exceptions to this requirement are as follows:
{% include requirement/MUSTNOT id="general-config-behaviour-changes" %} 클라이언트를 구성한 후 발생하는 구성 변경 사항에 따라 동작을 변경하지 마십시오. 클라이언트의 계층은 명시적으로 변경되거나 재정의되지 않는 한 부모 클라이언트 구성을 상속합니다. 이 요구 사항에 대한 예외는 다음과 같습니다:
1. Log level, which must take effect immediately across the Azure SDK.
2. Telemetry on/off, which must take effect immediately across the Azure SDK.
1. 로그 레벨은 Azure SDK에서 즉시 적용해야 합니다.
2. Telemetry on/off는 Azure SDK에서 즉시 적용해야 합니다.
> TODO: Update these guidelines to specify exactly how to do these things in Swift
#### Service-specific configuration
#### 서비스별 구성
For iOS applications, configuration is applied using `Info.plist` and directly mirrors the environment variables within a service written in other languages.
iOS 애플리케이션의 경우 `Info.plist`를 사용하여 구성을 적용하고 다른 언어로 작성된 서비스 내에서 환경 변수를 직접 반영하십시오.
{% include requirement/MUST id="ios-config-plist-key-prefix" %} prefix Azure-specific plist keys with `AZURE_`.
{% include requirement/MUST id="ios-config-plist-key-prefix" %} Azure-specific plist 키인 `AZURE_`를 prefix로 사용하십시오.
{% include requirement/MAY id="ios-config-plist-key-use-client-specific" %} use client library-specific plist keys set in `Info.plist` for portal-configured settings which are provided as parameters to your client library. This generally includes credentials and connection details. For example, Service Bus could support the following environment variables:
{% include requirement/MAY id="ios-config-plist-key-use-client-specific" %} 클라이언트 라이브러리에 매개 변수로 제공되는 포털 구성 설정에는 `Info.plist`에 설정된 클라이언트 라이브러리별 목록 키를 사용할 수 있습니다. 여기에는 일반적으로 자격 증명 및 연결 세부 정보가 포함됩니다. 예를 들어 서비스 버스는 다음 환경 변수를 지원할 수 있습니다:
* `AZURE_SERVICEBUS_CONNECTION_STRING`
* `AZURE_SERVICEBUS_NAMESPACE`
* `AZURE_SERVICEBUS_ISSUER`
* `AZURE_SERVICEBUS_ACCESS_KEY`
Storage could support:
스토리지는 다음과 같이 지원합니다:
* `AZURE_STORAGE_ACCOUNT`
* `AZURE_STORAGE_ACCESS_KEY`
* `AZURE_STORAGE_DNS_SUFFIX`
* `AZURE_STORAGE_CONNECTION_STRING`
{% include requirement/MUST id="ios-config-plist-key-get-approval" %} get approval from the [Architecture Board] for every new plist key. If an environment variable has been approved for the same client library within a different language, a key by the same name is approved for iOS.
{% include requirement/MUST id="ios-config-plist-key-get-approval" %} [Architecture Board]에서 모든 새로운 plist 키에 대한 승인을 얻어야 합니다. 환경 변수가 다른 언어 내에서 동일한 클라이언트 라이브러리에 대해 승인된 경우, 동일한 이름의 키가 iOS에 대해 승인됩니다.
{% include requirement/MUST id="ios-config-plist-key-format" %} use this syntax for `Info.plist` keys specific to a particular Azure service:
{% include requirement/MUST id="ios-config-plist-key-format" %} 특정 Azure 서비스에 고유한 'Info.plist' 키에 대해 다음 구문을 사용하십시오:
* `AZURE_<ServiceName>_<ConfigurationKey>`
where _ServiceName_ is the canonical shortname without spaces, and _ConfigurationKey_ refers to an unnested configuration key for that client library.
여기서 _ServiceName_ 은 공백이 없는 표준 단축 이름이며 _ConfigurationKey_ 는 해당 클라이언트 라이브러리에 포함되지 않은 않은 구성 키를 나타냅니다.
{% include requirement/MUSTNOT id="ios-config-plist-key-posix-compatible" %} use non-alpha-numeric characters in your environment variable names with the exception of underscore. This ensures broad interoperability.
{% include requirement/MUSTNOT id="ios-config-plist-key-posix-compatible" %} 환경 변수 이름에는 밑줄을 제외하고 영숫자가 아닌 문자를 사용하지 마십시오. 이를 통해 광범위한 상호 운용성을 보장합니다.
### Logging
### 로깅
Client libraries must support robust logging mechanisms so that the consumer can adequately diagnose issues with the method calls and quickly determine whether the issue is in the consumer code, client library code, or service.
클라이언트 라이브러리는 강력한 로깅 메커니즘을 지원하여 소비자가 메서드 호출의 문제를 적절하게 진단하고 문제가 소비자 코드, 클라이언트 라이브러리 코드 또는 서비스에 있는지 여부를 신속하게 확인할 수 있어야 합니다.
{% include requirement/MUST id="ios-logging-pluggable-logger" %} support pluggable log handlers. This should be provided by allowing the consumer to specify a `logger` parameter in the client options. The `logger` parameter points to an instance of the `AzureCoreLogger` protocol.
{% include requirement/MUST id="ios-logging-pluggable-logger" %} 착탈식(pluggable) 로그 핸들러를 지원하도록 하십시오. 이는 소비자가 클라이언트 옵션에 `logger` 매개변수를 지정할 수 있도록 제공되어야 합니다. `logger` 매개변수는 `AzureCoreLogger` 프로토콜의 인스턴스를 가리킵니다.
{% include requirement/MUST id="ios-logging-console-logger" %} make it easy for a consumer to enable logging output to the console. This is done by setting the `logger` client option to a new instance of the `AzureCoreOSLogger`.
{% include requirement/MUST id="ios-logging-console-logger" %} 소비자가 콘솔에 대한 로그 출력을 쉽게 활성화할 수 있도록 하십시오. 이 작업은 `logger` 클라이언트 옵션을 `AzureCoreOSLogger`의 새 인스턴스로 설정함으로써 수행됩니다.
{% include requirement/MUST id="ios-logging-levels" %} use one of the following log levels when emitting logs: `Verbose` (details), `Informational` (things happened), `Warning` (might be a problem or not), and `Error`. This are provided by the enum `AzureCoreLogLevels`.
{% include requirement/MUST id="ios-logging-levels" %} 로그를 내보낼 때는 `Verbose`(상세 정보), `Informational`(일이 발생함), `Warning`(문제일 수도 있고 그렇지 않을 수도 있음), `Error`(오류) 중 하나를 사용하십시오. 이것은 열거형 `AzureCoreLogLevels`에 의해 제공됩니다.
{% include requirement/MUST id="ios-logging-failure" %} use the `Error` logging level for failures that the application is unlikely to recover from (out of memory, etc.).
{% include requirement/MUST id="ios-logging-failure" %} 응용 프로그램이 복구할 가능성이 없는 오류(메모리 부족 등)에 대해 `Error` 수준의 로깅을 사용하십시오.
{% include requirement/MUST id="ios-logging-warning" %} use the `Warning` logging level when a function fails to perform its intended task. This generally means that the function will raise an exception. Do not include occurrences of self-healing events (for example, when a request will be automatically retried).
{% include requirement/MUST id="ios-logging-warning" %} 함수가 의도한 작업을 수행하지 못할 경우 `Warning` 로깅 수준을 사용하십시오. 이는 일반적으로 함수가 예외를 발생시킨다는 것을 의미합니다. Self-healing events(예: 요청이 자동으로 재시도되는 경우)의 발생은 포함하지 마십시오.
{% include requirement/MUST id="ios-logging-info" %} use the `Informational` logging level when a function operates normally.
{% include requirement/MUST id="ios-logging-info" %} 기능이 정상적으로 작동할 때 `Informational` 로깅 수준을 사용하십시오.
{% include requirement/MUST id="ios-logging-verbose" %} use the `Verbose` logging level for detailed troubleshooting scenarios. This is primarily intended for developers or system administrators to diagnose specific failures.
{% include requirement/MUST id="ios-logging-verbose" %} 자세한 문제 해결 시나리오에 대해 'Verbose' 로깅 수준을 사용하십시오. 이는 주로 개발자나 시스템 관리자가 특정 장애를 진단하기 위한 것입니다.
The client library can log using the following:
클라이언트 라이브러리는 다음과 같이 로그를 기록할 수 있습니다:
{% highlight swift %}
logger.writeLog(for: "MyClient", withLevel: AzureCoreLogLevels.Verbose, message: "A message")
{% endhighlight %}
{% include requirement/MUSTNOT id="ios-logging-no-sensitive-info" %} send sensitive information in log levels other than `Verbose`. For example, remove account keys when logging headers. Headers and query parameters must be redacted using the `loggingAllowedHeaders` array and `loggingAllowedQueryParams` array specified within the client options
{% include requirement/MUSTNOT id="ios-logging-no-sensitive-info" %} 중요한 정보를 `Verbose`가 아닌 로그 수준으로 보내지 마십시오. 예를 들어, 헤더를 기록할 때는 계정 키를 제거하십시오. 클라이언트 옵션에 지정된 `loggingAllowedHeaders` 배열과 'loggingAllowedQueryParams' 배열을 사용하여 헤더와 쿼리 매개 변수를 수정해야 합니다.
{% include requirement/MUST id="ios-logging-default-allowedlist" %} set reasonable defaults for the `loggingAllowedHeaders` and `loggingAllowedQueryParams` properties in the client options.
{% include requirement/MUST id="ios-logging-default-allowedlist" %} 클라이언트 옵션에서 `loggingAllowedHeaders` 및 `loggingAllowedQueryParams` 속성의 합리적인 기본값을 설정하십시오.
{% include requirement/MUST id="ios-logging-requests" %} log request line, response line, and headers, as `Informational` message.
{% include requirement/MUST id="ios-logging-requests" %} 로그 요청 라인, 응답 라인 및 헤더를 `Informational` 메시지로 기록하십시오.
{% include requirement/MUST id="ios-logging-cancellations" %} log an `Informational` message if a service call is cancelled.
{% include requirement/MUST id="ios-logging-cancellations" %} 서비스 호출이 취소된 경우 `Informational` 메시지를 기록하십시오.
{% include requirement/MUST id="ios-logging-exceptions" %} log exceptions thrown as a `Warning` level message. If the log level set to `Verbose`, append stack trace information to the message.
{% include requirement/MUST id="ios-logging-exceptions" %} 로그 예외가 `Warning` 수준의 메시지로 던져집니다. 로그 수준이 `Verbose`로 설정되어 있으면 메시지에 스택 추적 정보를 추가합니다.
> TODO: Logging (see general guidelines)
> * Provide abstracted logger in AzureCore
@ -144,11 +144,11 @@ logger.writeLog(for: "MyClient", withLevel: AzureCoreLogLevels.Verbose, message:
> TBD:
> * Hook in to HockeyApp
### Distributed tracing
### 분산 트레이스
Distributed tracing is uncommon in a mobile context. If you feel like you need to support distributed tracing, contact the [Azure SDK mobile team](mailto:azuresdkmobileteam@microsoft.com) for advice.
분산 트레이스는 모바일컨텍스트에서는 거의 발생하지 않습니다. 분산 트레이스를 서포트할 필요가 있는 경우는, [Azure SDK 모바일 팀](mailto:azuresdkmobileteam@microsoft.com)에 문의해 주십시오.
### Testing
### 테스팅
> TODO: Document how to write good tests with the existing XCTest framework.
> TODO: Say something about mocking of the requests and how to design for it.

2
docs/policies/adoption.md
Просмотреть файл

@ -24,7 +24,7 @@ sidebar: general_sidebar
## 언어별 가이드라인 변경
언어 고유의 가이드라인(azure/azure-sdk 저장소의 /docs 언어 고유의 폴더 아래에 있는 모든 것을 포함한다)은 일반적으로 일반적인 가이드라인에 따라 결정되며, 일반적인 언어에서 자연스럽게 받아들여지는 설계 및 구현 원칙에도 따라 결정됩니다. 설계 가이드라인은 일반적인 설계 가이드라인의 정신을 충족해야 합니다. 실장 가이드라인은 언어 팀에 의해 관리되며, 언어 설계자는 실장 가이드라인이 해당 언어의 최선을 충족하는지 확인할 책임이 있습니다.
언어별 가이드라인(azure/azure-sdk 저장소의 /docs의 language-specific 폴더에 포함된 모든 내용을 포함)은 일반적인 가이드라인을 따르지만, 선택한 언어의 관용적이고 일반적으로 수용되는 설계 및 구현 원칙에 따라 진행됩니다. 설계 가이드라인은 일반적인 설계 가이드라인의 정신을 준수해야 합니다. 구현 가이드라인은 해당 언어를 담당하는 팀에 의해 관리되며, 언어 설계자는 해당 언어의 모범 사례를 충족하는 구현 가이드라인을 보장하는 책임을 지게 됩니다.
가이드라인은 누구나 PR을 통해 제안할 수 있지만 병합하려면 다음 사항을 충족해야 합니다.

92
docs/policies/repobranching.md
Просмотреть файл

@ -1,27 +1,27 @@
---
title: "Policies: Repository Branching"
title: "정책: 저장소 브랜치 관리"
permalink: policies_repobranching.html
folder: policies
sidebar: general_sidebar
---
The git branching and workflow strategy we will be using is mostly in line with [OneFlow](https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow) with some slight variations called out below.
Git 브랜치 관리와 워크플로우 전략은 대부분 [OneFlow](https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow)와 일치하며, 약간의 차이점은 아래에 명시되어 있습니다.
## Main branch
## 메인 브랜치
`main` is the main default branch that lives forever and should never be force pushed to. The main branch must always be in a working state where CI builds succeed (e.g. build, analyze, and tests passing). All other branches are intentionally short lived and should be removed once they are no longer needed.
`main`은 항상 존재하고, 절대 강제로 푸시하면 안 되는 기본 브랜치입니다. 메인 브랜치는 항상 작동하는 상태를 유지해야 하며, CI(Continuous Integration) 빌드가 성공적으로 수행되어야 합니다 (예: 빌드, 분석, 테스트가 모두 통과). 나머지 모든 브랜치는 의도적으로 짧은 수명을 가지도록 설계되었으며, 더 이상 필요하지 않을 경우 삭제해야 합니다.
While main will always be in a buildable state it will not necessarily always represent the state of the latest official published packages. To figure out the state of the code for a given released package you need to use the tag for that released package. This rule might vary between the different language repos as some languages that allow direct references to source code (i.e. python, js) like to keep the main branch matching the latest published official package and so you may need to refer to specific instructions in the language repos for the rules.
메인 브랜치는 언제나 빌드 가능한 상태를 유지하지만, 항상 최신으로 배포된 공식 패키지의 상태를 반영하는 것은 아닙니다. 특정 배포된 패키지의 코드 상태를 파악하려면 그 패키지에 대한 태그를 참조해야 합니다. 이 규칙은 각각의 프로그래밍 언어 저장소에 따라 다를 수 있습니다. 예를 들어 파이썬이나 자바스크립트처럼 소스 코드를 직접 참조할 수 있는 언어들은 메인 브랜치가 항상 최신으로 배포된 공식 패키지와 동일한 상태를 유지하려는 경향이 있습니다. 그러므로 각 언어 저장소의 구체적인 지침을 참고해야 합니다.
## Work should happen in Forks
## 포크 상태에서 작업하기
In order to help reduce the clutter of branches in the main repo as well as to enable a common workflow for both contributors and community members with different permissions people should create forks of the main repository and work in them. Once work is ready in the fork then a pull request can be submitted back to the main repository.
메인 저장소의 브랜치 혼잡을 줄이고, 다른 권한을 가진 기여자와 커뮤니티 회원들 모두에게 공통의 작업 흐름을 가능하게 하기 위해, 구성원들은 메인 저장소를 포크하여 작업을 진행해야 합니다. 포크에서의 작업이 준비되면 Pull Request를 메인 저장소에 제출할 수 있습니다.
See the next few sections for some simple getting started instructions for using forks but for more detailed documentation from github see [working-with-forks](https://help.github.com/en/articles/working-with-forks).
포크를 사용하는데 대한 간단한 시작 지침을 위한 다음 몇가지 섹션을 참조하십시오. 또한 Github에서 더 자세한 문서를 보려면 [working-with-forks](https://help.github.com/en/articles/working-with-forks)를 참조하십시오.
### Clone forked repo
### 포크된 저장소 복제하기
After you have created your own fork by clicking the fork button on the main repo you can use the following commands to clone and set up your local repo.
메인 저장소에서 포크 버튼을 클릭하여 본인의 포크를 생성한 후에는 아래의 명령어를 사용하여 로컬 저장소를 복제하고 설정할 수 있습니다.
```bash
# clone your forked repo locally which will setup your origin remote
@ -37,11 +37,11 @@ git remote -v
# upstream https://github.com/Azure/azure-sdk-for-<lang>.git (fetch)
# upstream https://github.com/Azure/azure-sdk-for-<lang>.git (push)
```
After you have ran those commands you should be all setup with your local cloned repo, a remote for your forked repo called origin, and a remote for the main repo called upstream.
위의 명령어들을 실행한 후에는 로컬로 복제된 저장소와 origin이라는 이름의 본인이 포크한 저장소를 위한 원격 저장소, 그리고 upstream이라는 이름의 메인 저장소를 위한 원격 저장소가 모두 설정되어 있어야 합니다.
### Sync your local and forked repo with latest changes from the main repo
### 메인 저장소로부터 최신 변경 사항을 로컬 및 포크된 저장소로 동기화
Working in a fork is highly recommended so you should avoid committing changes directly into main and you can use it to sync your various repos. The instructions in this section assume you are using main as your syncing branch.
포크 상태에서 작업하는 것이 강력하게 권장되므로 메인 브랜치에 직접 변경 사항을 커밋하는 것은 지양해야 합니다. 대신 메인 브랜치을 사용하여 구성원들의 다양한 저장소를 동기화하는 것이 가능합니다. 이 섹션의 지침은 메인을 동기화 브랜치로 사용한다는 가정하에 작성되었습니다.
```bash
# switch to your local main
@ -54,9 +54,9 @@ git pull upstream main --ff-only
git push origin main
```
At this point all three of your repos - local, origin, and upstream - should all match and be in sync.
이 시점에서 세 개의 저장소(로컬, origin, upstream)가 모두 일치하고 동기화되어야 합니다.
Note that in order to ensure that we don't accidently get our local or origin main out of sync we use the `--ff-only` (fast-forward only) option which will fail if you have any commits that aren't already in the main repo. If you ever get into this state the easiest thing to do is to force reset your local main branch.
로컬 또는 origin의 메인 브랜치가 실수로 동기화에서 벗어나는 것을 방지하기 위해 `--ff-only`(fast-forward only) 옵션을 사용합니다. 이 옵션은 메인 저장소에 이미 존재하지 않는 커밋이 있는 경우 실패하게 됩니다. 이와 같은 상태에 빠지게 된다면, 가장 간단한 해결 방법은 로컬의 메인 브랜치를 강제로 리셋하는 것입니다.
```bash
# Warning: this will remove any commits you might have in your local main so if
@ -66,9 +66,9 @@ git reset --hard upstream/main
# If you also have your forked main out of sync you might need to use the force option when you push those changes
git push origin main -f
```
### Creating a branch and pushing it to your fork
### 브랜치 생성 및 포크로 푸시하기
After your local main branch is in-sync with the upstream main you can now create a branch and do work.
로컬의 메인 브랜치가 upstream의 메인 브랜치와 동기화된 후, 새로운 브랜치를 생성하고 작업을 진행할 수 있습니다.
```bash
git checkout <branch-name>
@ -79,17 +79,18 @@ git commit
git push origin <branch-name>
```
At this point you should be able to go to the main repository on github and see a link to create a pull request with the changes you pushed.
이 시점에서는 GitHub의 메인 저장소로 이동하여, 푸시한 변경 사항으로 pull request를 생성하는 링크를 확인할 수 있어야 합니다.
_Tip_: 몇몇 사람들은 빠르게 스테이지하고 간단한 메시지와 함께 동시에 커밋하는 것을 선호합니다. 그럴 경우 아래의 명령어를 사용할 수 있습니다.
_Tip_: Some folks like to quickly stage and commit with a simple message at the same time you can use the following command for that.
```bash
git commit -am "Commit message"
```
Note that `-a` means commit all files that have changes so be sure to not have any other modified files in your working directory. The `-m` allows you to pass a commit message at the command line and is useful for quick commits but you might want to use your configured editor for better commit messages when pushing changes you want to be reviewed and merged into the main repo.
`-a`는 변경된 모든 파일을 커밋하라는 의미이므로 작업 디렉토리에 수정된 다른 파일이 없도록 주의해야 합니다. `-m`은 커맨드 라인에서 커밋 메시지를 전달할 수 있게 해주어 빠른 커밋에 유용하지만, 리뷰를 받고 메인 리포지토리에 병합하고자 하는 변경사항을 푸시할 때는 구성된 에디터를 사용하여 더 나은 커밋 메시지를 작성하고자 할 수 있습니다
### Rebase changes on top of latest main
### 최신 메인 브랜치 위에 변경 사항 rebase하기
If you have changes that you have been working on and you need to update them with the latest changes from main, you should do the following commands after you have sync'ed your local main.
작업 중인 변경사항이 있으며 이를 메인 브랜치의 최신 변경사항으로 업데이트하고 싶다면, 로컬의 메인 브랜치를 동기화한 후에 다음 명령어들을 실행합니다.
```bash
git checkout <branch-name>
@ -103,40 +104,41 @@ git rebase main
git push origin <branch-name> -f
```
_Tip_: if you want to squash changes you can add the `-i` to the rebase command for interactive mode to select which commits you want to squash, see [interactive mode](https://www.git-scm.com/docs/git-rebase#_interactive_mode) for information.
_Tip_: 변경 사항을 합치고자 한다면, -i 옵션을 rebase 명령어에 추가하여 대화형 모드로 전환하고 합치고자 하는 커밋을 선택할 수 있습니다. 대화형 모드에 대한 정보는 [interactive mode](https://www.git-scm.com/docs/git-rebase#_interactive_mode)를 참고하십시오.
## Feature branches
## Feature 브랜치
For isolated work people should create branches off main and keep them in their local or forked repository. The name for these branches is up to the individual working on the changes and doesn't need to match the `feature` naming scheme but instead should match what the set of changes people are making. Once the work is ready the changes should be rebased on top of main and a pull request should be submitted to the main repository.
독립적인 작업을 위해 사용자들은 메인 브랜치로부터 브랜치를 생성하고 그것들을 본인의 로컬 또는 포크된 저장소에 유지해야 합니다. 이러한 브랜치의 이름은 `feature` 명명 규칙을 따를 필요는 없고 대신 사람들이 만드는 일련의 변경 사항에 맞춰야 합니다. 작업이 준비되면 변경 사항은 메인 위에 리베이스되어야 하며, 메인 저장소에 pull request가 제출되어야 합니다.
If there are a set of people that need to collaborate on the same set of changes before they can go into main then a feature branch can be pushed to the main repository for sharing. Collaborators can either work together to push changes to that branch or submit pull requests against it until it is ready to go to main. Once the feature work is ready the changes should be rebased on top of main and a pull request submitted to the main branch in the main repository. Once the feature work pull request is complete then the branch should be deleted from the main repository.
메인 브랜치에 합쳐지기 전에 동일한 변경 사항들에 대해 여러 명이 협업해야 하는 경우, 공유를 위해 feature 브랜치를 메인 저장소에 푸시할 수 있습니다. 협업자들은 해당 브랜치에 변경 사항을 함께 푸시하거나, 메인 브랜치로 이동할 준비가 될 때까지 그것에 대한 pull request를 제출할 수 있습니다. 또한, feature 작업이 준비되면 변경 사항은 메인 위에 리베이스되어야 하며, 메인 저장소의 메인 브랜치에 pull request를 제출해야 합니다. 마지막으로 feature 작업에 대한 pull request가 완료되면, 해당 브랜치는 메인 저장소에서 삭제되어야 합니다.
The feature branches pushed to the main repo should be named like `feature/<feature name>`
메인 저장소에 푸시된 feature 브랜치는 `feature/<feature name>`과 같이 명명되어야 합니다.
## Release tagging
## Release 태깅
For each package we release there will be a unique git tag created that contains the name and the version of the package to mark the commit of the code that produced the package. This tag will be used for servicing via hotfix branches as well as debugging the code for a particular version.
각 패키지를 릴리즈할 때마다, 해당 패키지의 이름과 버전을 포함하는 고유한 git 태그가 생성됩니다. 이 태그는 패키지를 생성한 코드의 커밋을 표시하는데 사용됩니다. 이 태그는 Hotfix 브랜치를 통한 서비스 제공 및 특정 버전의 코드 디버깅에 사용됩니다.
Format of the tag should be `<package-name>_<package-version>`
태그의 형식은 `<package-name>_<package-version>`이어야 합니다.
**_Note:_** Our release tags should be considered immutable. Avoid updating or deleting them after they are pushed. If you need to update or delete one for some exceptional case, please contact the engineering system team to discuss options.
**_Note:_** Release 태그는 변경되지 않아야 합니다. 푸시한 후에는 업데이트하거나 삭제하지 않아야 합니다. 예외적인 경우에 태그를 업데이트하거나 삭제해야 하는 경우, 엔지니어링 시스템 팀에 연락하여 가능한 대안에 대해 논의하시기 바랍니다.
## Release branches
## Release 브랜치
There are potentially 3 different types of release branches in the order of preference:
- `main`
- `release/<release name>`
- `feature/<feature name>`
우선 순위에 따라 다음 세 가지 유형의 Release 브랜치가 존재할 수 있습니다:
In general there should not be a need for release branches because most releases will happen directly from main. In some cases there may be a need to lock down the branch to stabilize a package and in these cases we should create a release branch named `release/<release name>` and push it to the main repository. We do this to avoid ever locking down the main branch from taking other work. After any changes have been made and the release build produced the branch should be merged (not rebased) back into main, including the tagged release commit, and then the release branch should be deleted.
- `main`
- `release/<release name>`
- `feature/<feature name>`
There may be other circumstances where we need to release a beta of a package from another branch outside of main or a release branch. In those cases we should use a feature branch in the main repository (note that we should not do stable releases out of feature branches so ensure the version is correctly marked as a beta). The release should be done in the same way, including the creation of the release tag, with the only difference being the release build should point to this feature branch instead of main. When the work is done this feature branch should be merged into main instead of rebased as generally recommended for feature branches. This allows us to preserve the release tags in main after we delete the feature branch.
대부분의 Release가 메인에서 직접 이루어지므로, 일반적으로 Release 브랜치를 별도로 만들 필요는 없습니다. 그러나 경우에 따라 패키지를 안정화시키기 위해 브랜치를 잠그는 작업이 필요할 수 있습니다. 이런 상황에서는 `release/<release name>`라는 이름의 Release 브랜치를 생성하여 메인 저장소에 푸시합니다. 이런 방식을 채택하는 이유는 메인 브랜치가 다른 작업을 처리하는 것을 방해하지 않기 위해서입니다. 모든 변경이 완료되고 Release 빌드가 생성된 후에는, 해당 브랜치는 메인으로 병합(Rebase가 아님)되어야 합니다. 이때 Release 커밋에 달린 태그도 포함되어야 합니다. 이 과정이 완료되면 Release 브랜치는 삭제되어야 합니다.
When doing any releases outside of main extra caution needs to be taken to ensure the version numbers are correct and don't conflict with main or any other branch that might be releasing the same package.
메인 브랜치나 Release 브랜치 외부의 다른 브랜치에서 패키지의 베타 버전을 Release해야 하는 경우도 있을 수 있습니다. 이러한 경우에는 메인 저장소의 Feature 브랜치를 사용해야 합니다 (Feature 브랜치에서 안정된 Release를 진행하지 않아야 하므로, 버전이 베타로 올바르게 표시되었는지 확인해야 합니다). Release는 동일한 방식으로 수행되어야 하며, Release 태그의 생성도 포함되어야 합니다. 유일한 차이점은 Release 빌드가 메인 대신 이 Feature 브랜치를 가리키게 될 것이라는 점입니다. 작업이 완료되면 이 Feature 브랜치는 일반적으로 권장되는 Feature 브랜치에 대한 Rebase 대신 메인에 병합되어야 합니다. 이를 통해 Feature 브랜치를 삭제한 후에도 메인에서 Release 태그를 유지할 수 있습니다.
## Hotfix branches
메인 외부에서 Release를 진행할 경우, 버전 번호가 정확하며 메인 또는 동일한 패키지를 Release하게 될 수 있는 다른 브랜치와 충돌하지 않도록 유의해야 합니다.
Under some circumstances we may need to service a specific version of the code with a hotfix and in these cases we should create a branch with the name `hotfix/<hotfix name>`, where `<hotfix name>` should have at least the name of the package or service and a short description or version number with it. That branch should be created from the git release tag that points at the specific version we want to hotfix and pushed to the main repository.
## Hotfix 브랜치
특정 버전의 코드에 Hotfix를 적용해야 하는 경우가 있을 수 있습니다. 이런 경우에는 `hotfix/<hotfix name>`의 형태로 브랜치 이름을 생성해야 합니다. 여기서 `<hotfix name>`은 최소한 패키지나 서비스의 이름과 간단한 설명 또는 버전 번호를 포함해야 합니다. 이 브랜치는 Hotfix를 적용하고자 하는 특정 버전을 가리키는 git release 태그로부터 생성되어야 하며, 메인 저장소에 푸시되어야 합니다.
```bash
# If you need help finding the exact case-sensitive tag name:
@ -146,10 +148,10 @@ git checkout -b hotfix/<hotfix name> <package-name>_<package-version>
git push upstream hotfix/<hotfix name>
```
After you have the main hotfix branch created you should use your usual workflow (i.e. create another branch or work on the same named branch in your fork) and the changes should be made and the version number incremented based on our [versioning guidance](releases.md#package-versioning) for the package. If the fixes are already made in main or another branch you can cherry-pick (`git cherry-pick <sha>`) them into your working branch, otherwise make the code edits as needed. Once all the changes are ready submit a PR against the `hotfix/<hotfix name>` branch you created in the main repo. PR validation should kick in automatically as long as the branch follows the `hotfix/*` naming convention. Once CI is green then the fix can be merged into the `hotfix/<hotfix name>` branch.
Hotfix 브랜치가 생성된 후에는 평소에 사용하던 작업 프로세스(즉, 새 브랜치를 생성하거나 포크에서 동일한 이름의 브랜치에서 작업하는 등)를 이용해야 합니다. 변경사항을 만들고 패키지에 대한 [버전 관리 지침](releases.md#package-versioning)에 따라 버전 번호를 증가시켜야 합니다. 만약 수정사항이 이미 메인 브랜치나 다른 브랜치에 있다면, 작업 중인 브랜치로 해당 사항들을 체리픽(`git cherry-pick <sha>`)할 수 있고, 그렇지 않다면 필요한 코드 수정을 진행해야 합니다. 모든 변경사항이 완료되면 메인 저장소에서 생성한 `hotfix/<hotfix name>` 브랜치로 Pull Request를 제출해야 합니다. 브랜치가 `hotfix/*` 명명 규칙을 따르면, Pull Request 검증은 자동으로 시작됩니다. CI가 성공적으로 수행되면, 수정된 사항을 `hotfix/<hotfix name>` 브랜치로 병합할 수 있습니다.
After the changes are merged into the `hotfix/<hotfix name>` branch the same release process we use for main can be used to produce a release out of that branch but when you queue the build be sure to set the branch name to the `hotfix/<hotfix name>`.
변경사항이 `hotfix/<hotfix name>` 브랜치로 병합된 후, 메인에서 사용하는 것과 동일한 Release 프로세스를 사용하여 해당 브랜치에서 Release를 생성할 수 있습니다. 그러나 빌드를 대기열에 추가할 때 브랜치 이름을 반드시 `hotfix/<hotfix name>`로 설정해야 합니다.
If the changes were not cherry-picked from `main` and they are needed there then merge (`git merge hotfix/<hotfix name>`) them from your `hotfix/<hotfix name>` branch into `main`. When merging accept the version numbers from `main` and make sure CHANGELOG entries are sorted by date then version.
만약 변경사항이 `main`으로 체리픽(cherry-pick)되지 않았고, `main`에 필요하다면 `git merge hotfix/<hotfix name>` 명령을 사용하여 `hotfix/<hotfix name>` 브랜치를 `main`으로 병합해야 합니다. 이때 병합을 수행할 때는 `main`의 버전 번호를 유지하고, CHANGELOG 항목이 날짜와 버전별로 정렬되어 있는지 확인해야 합니다.
Once the hotfix has been released and any changes merged back to `main` then you should delete the `hotfix/<hotfix name>` branch, it can always be recreated in the future from the last release tag if needed.
Hotfix가 배포되고 변경 사항이 `main`으로 병합되면, `hotfix/<hotfix name>` 브랜치를 삭제해야 합니다. 필요한 경우, 나중에 마지막 Release 태그로부터 항상 재생성할 수 있습니다.

199
docs/policies/reviewprocess.md
Просмотреть файл

@ -1,171 +1,168 @@
---
title: "Policies: Review Process"
title: "정책: 리뷰 프로세스"
permalink: policies_reviewprocess.html
folder: policies
sidebar: general_sidebar
---
## Introduction
## 소개
The Azure Developer Platform (ADP) Architecture Review Board is a board of language architects specializing in Java, Python, TS/JS, C#, C, C++, Go, Android, and iOS.
Azure Developer Platform (ADP) 아키텍처 리뷰 위원회는 Java, Python, TS/JS, C#, C, C++, Go, Android, iOS에 전문화된 언어 아키텍트들의 보드입니다.
**The Architecture Board reviews Track 2 libraries only**. By definition, a Track 2 library is one that follows our [Track 2 library design guidelines and specific language guidelines](https://azure.github.io/azure-sdk/general_introduction.html). This means that libraries produced solely by a code generator do NOT follow these guidelines; engineers MUST build a layer on top of the generated code in order to produce a library that meets the guidelines. We have developed the SDK Development Training program to help you be successful in building these libraries - find out more [here!](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/346/Azure-SDK-Development-Training)
아키텍처 위원회는 오직 Track 2 라이브러리만을 검토합니다. 정의상, Track 2 라이브러리는 우리의 Track 2 라이브러리 디자인 가이드라인과 특정 언어 가이드라인을 준수하는 라이브러리를 의미합니다. 이는 코드 생성기만으로 제작된 라이브러리는 이러한 가이드라인을 따르지 **않음**을 의미하며, 엔지니어들은 이 가이드라인을 만족시키는 라이브러리를 제작하기 위해 생성된 코드 위에 레이어를 **반드시** 구축해야 합니다. 이러한 라이브러리를 만드는데 성공할 수 있도록 SDK 개발 교육 프로그램을 개발했습니다 - [여기](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/346/Azure-SDK-Development-Training) 자세한 내용을 알아보세요!
We expect all Azure client libraries to pass rigorous API reviews similar to those conducted for any other API produced by Microsoft (for example, the .NET APIs). In addition to detailed reviews of new libraries, **all changes** to an API must be approved by an architect of the specific language before release.
우리는 모든 Azure 클라이언트 라이브러리가 Microsoft에서 생산하는 다른 API (예: .NET API)에 대해 실시하는 것과 유사한 엄격한 API 리뷰를 통과하길 기대합니다. 새로운 라이브러리의 상세한 리뷰 외에도, API에 대한 **모든 변경사항**은 릴리즈 전에 특정 언어의 아키텍트가 승인해야 합니다.
Note that the library review process described here is currently an **internal** one. This document is intended to clarify the process for Azure service teams looking to have their libraries reviewed.
여기서 설명하는 라이브러리 리뷰 프로세스는 현재 **내부적인** 프로세스입니다. 이 문서는 라이브러리를 검토하려는 Azure 서비스 팀들에게 프로세스를 명확하게 하는 데 의도되어 있습니다.
## API Review Process Roadmap
## API 리뷰 프로세스 로드맵
Typically, there will be a minimum of three meetings with the Architecture Board:
아키텍처 위원회와의 회의는 일반적으로 최소 세 번 이상 진행됩니다:
1. Introductory session
2. API reviews
3. API Sign Off
1. 소개 세션
2. API 리뷰
3. API 승인
라이브러리 서피스와 기타 요인에 따라, 하나 이상의 API 리뷰가 필요할 수 있습니다.
Depending on the library surface and other factors, more than one API reviews may be needed.
"릴리즈를 위한 아키텍처 보드 승인 기록" 이슈 템플릿을 사용하여 에픽을 생성하고, 리뷰와 승인을 추적합니다. 릴리즈 매니저는 PLR의 일부로 이 이슈에 대한 링크를 요청할 것입니다.
Create an epic using the “Record of Architecture Board Approval for Release” issue template to track reviews and approvals. The release manager will ask for a link to this issue as part of the PLR.
라이브러리 소유자가 아키텍처 보드와 충분히 일찍 연결하여 수정 및 (때때로 상당한) API 재디자인 시간을 확보하는 것이 중요합니다. 클라이언트 라이브러리 작업의 성격과 범위에 따라, 아키텍처 보드와의 교류시 따라야 할 일련의 과정은 다음 두 가지 경로 중 하나를 따를 것입니다:
It’s critical that library owners engage with the architecture board early enough to allow time for fixes and (sometimes significant) API redesign based on discussion. Depending on the nature and scope of the client library work being done, the sequence of events to follow when engaging with the architecture board will follow one of two paths:
1. **새로운 라이브러리, 대규모 피처 작업, 및/또는 파이프라인 변경**
1. **New libraries, large feature work, and/or pipeline changes**
이러한 변경사항은 아키텍처 보드 회의에서 최소 세 번 이상 논의되어야 합니다. 아래의 "리뷰 회의 유형 및 준비물" 섹션을 참조하십시오.
These changes should be discussed in an architecture board meeting at least three times. See “Types of Review Meetings and What to Prepare” section below.
2. **소규모, 목표 지향적인 변경과 버그 수정**
아래의 "소규모, 목표 지향적인 변경과 버그 수정 승인 받기" 섹션을 참조하십시오.
2. **Small, targeted changes and bug fixes**
당신이 진행하는 작업에 어떤 경로가 적용되는지 확실하지 않다면, 언어 아키텍트에게 지침을 구해야 합니다.
See “Getting approval for small, targeted changes and bug fixes” section below.
## 리뷰 회의 유형 및 준비물
If you are unsure which path applies to the work you are doing, you should consult with a language architect for guidance.
아키텍처 보드에 회의 요청을 위해 [이슈를 제출](https://github.com/Azure/azure-sdk/issues/new/choose)하십시오. 서비스가 사전 출시이며 아직 공개적으로 공개되지 않은 경우, 개인 저장소([azure-sdk-pr](https://github.com/Azure/azure-sdk-pr))를 사용하십시오. 이슈를 생성한 후, 스케줄링, 초대 목록 등과 같은 특정 요청을 전달하기 위해 [아키텍처 보드](mailto:adparch@microsoft.com)에 이메일을 보내십시오.
리뷰의 유형에 따라 적절한 템플릿을 사용하여 이슈를 생성하십시오. 이슈 템플릿에서 요구하는 모든 내용을 포함하고 올바른 형식으로 작성했는지 확인하십시오.
## Types of Review Meetings and What to Prepare
### 1. 소개 세션
[Submit an issue](https://github.com/Azure/azure-sdk/issues/new/choose) to the Architecture Board to request for a meeting. If the service is pre-release and not yet publicly disclosed, use the private repository ([azure-sdk-pr](https://github.com/Azure/azure-sdk-pr)). After creating the issue, email the [Architecture Board](mailto:adparch@microsoft.com) to communicate specific requests such as scheduling, invite lists, etc.
이 세션은 순수하게 정보 제공/교육을 위한 것으로, 보드가 서비스와 라이브러리/새로운 기능에 대해 속도를 내는 데 도움이 됩니다. 이를 통해 초기 피드백을 받을 수 있으며, 서비스 디자인에 영향을 줄 수 있습니다. API 네임스페이스, 함수 이름, 타입 등의 고수준 주제가 이 첫 번째 논의에서 제안될 것입니다.
Depending on the type of review, use the appropriate template to create the issue. Ensure that you included everything the issue template asks for and in the correct format.
**준비물 (리뷰 요청을 위한 GitHub 이슈에 포함시켜야 하는 내용):**:
* 서비스 소개 자료
* 서비스를 소개/설명하는 문서 링크
* 일부 팀들은 PowerPoint 소개를 준비하기도 합니다.
* 서비스 REST API에 대한 링크, 해당/가능한 경우.
* 챔피언 시나리오 예시
* 코드는 환영하지만 선택 사항입니다. 의사코드도 괜찮습니다.
* "챔피언 시나리오" 섹션을 참조하십시오
* [샘플 예시](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample1_DetectLanguage.md)
* 라이브러리의 샘플 폴더에 추가해야 합니다 ([예시](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples))
* 퀵스타트 샘플
* 소개 회의 시에는 선택 사항입니다
* 아래의 "퀵스타트 샘플" 섹션을 참조하십시오
### 1. Introductory Session
### 2. API 리뷰
API 리뷰 중에는 샘플 코드와 상세 API 목록을 살펴봅니다. 이러한 목록의 예시는 [여기](https://github.com/Azure/azure-sdk/blob/main/docs/dotnet/APIListingExample.md))에서 볼 수 있습니다.
This purely informational/educational to let the board get up to speed with the service and the library/new features that are coming. This allows for early feedback and will potentially affect the service design. High level topics such as API namespaces, function names, and types will be suggested in this first discussion.
API의 프로토타입이 있다면 API 목록을 생성할 수 있습니다:
**What to bring (include the following in GitHub issue requesting for review)**:
* Service introduction material
* Link to documentation introducing/describing the service
* Some teams also prepare a PowerPoint introductions
* Link to the service REST APIs, if applicable/available.
* Champion scenario samples
* Code is appreciated but optional. Pseudocode is fine.
* See “Champion scenarios” section below for definition
* [Sample example](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample1_DetectLanguage.md)
* Should be added to library’s sample folder ([example](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples))
* Quickstart samples
* Optional for introductory meeting
* See "Quickstart Samples" section below
* .NET의 경우, DLL을 [ApiView](http://apiview.dev/) 도구에 업로드합니다.
* Java의 경우, *-sources.jar 파일을 [ApiView] 도구에 업로드합니다 (예: azure-core-1.3.0-beta.1-sources.jar).
* Python의 경우, 우리의 [사용자 정의 API 스텁 생성기](https://github.com/Azure/azure-sdk-tools/tree/main/packages/python-packages/api-stub-generator#generate-stub-file)를 사용하여 공개 API 서피스를 담은 단일 파일을 생성합니다. stubgen의 출력을 ApiView 도구에 업로드합니다.
* TypeScript의 경우, [api-extractor](https://api-extractor.com/pages/setup/generating_docs/)를 사용하여 `api.json/docModel` 파일을 생성하고 [APIView](https://apiview.dev/)에 업로드합니다.
### 2. API Review
During API reviews, we look at sample code and detailed API listings. You can see an example of such listing [here](https://github.com/Azure/azure-sdk/blob/main/docs/dotnet/APIListingExample.md).
그 외 모든 언어에 대해서는 아키텍처 보드에 요청하여 개별적으로 가장 적합한 형식을 논의하십시오.
If you have a prototype of your APIs, you can generate the API listing:
상황과 서비스에 따라 둘 이상의 API 리뷰가 필요할 수 있습니다 (예를 들어, API 버전 간에 큰 변화가 있기 때문입니다). 그런 경우에는 팀이 다른 리뷰를 준비할 때 다른 이슈를 제출하십시오.
* For .NET, upload a DLL to the [ApiView](http://apiview.dev/) tool.
* For Java, upload the `*-sources.jar` file to the [ApiView](http://apiview.dev/) tool (e.g. `azure-core-1.3.0-beta.1-sources.jar`).
* For Python, use our [custom API stub generator](https://github.com/Azure/azure-sdk-tools/tree/main/packages/python-packages/api-stub-generator#generate-stub-file) to produce a single file with your public API surface. Upload the output of stubgen to the [ApiView](http://apiview.dev/) tool.
* For TypeScript, use [api-extractor](https://api-extractor.com/pages/setup/generating_docs/) to generate your `api.json/docModel` file and then upload to [APIView](https://apiview.dev/).
**준비물 (리뷰 요청을 위한 GitHub 이슈에 포함시켜야 하는 내용):**
* 각 언어의 API 목록에 대한 링크
* 아키텍트가 회의 전에 리뷰할 시간이 있도록 이를 최소한 **리뷰 예정일 5일 전**에 제공하십시오.
* 각 챔피언 시나리오에 대한 코드 샘플
* 퀵스타트 샘플
For all other languages, send a request to the Architecture Board to discuss the best format on individual basis.
### 3. API 승인
Depending on the situation and service, more than one API review may be needed (because there are major changes between API versions, for example). If that is the case, file another issue when the team is ready for another review.
API 승인 회의의 목표는 API에 대한 논란의 여지가 있는/해결되지 않은 질문을 해결하는 것입니다. 이러한 질문은 언어 아키텍트 또는 서비스 팀에서 제기될 수 있습니다.
**What to bring (include the following in GitHub issue requesting for review):**
* Links to the API Listings for each language reviewed
* Be sure to provide these at least **5 business days before** the intended review date so architects have time to review before the meeting
* Code samples for each champion scenario
* Quickstart samples
**모든 언어는 GA로 릴리즈되기 전에 반드시 승인을 받아야 합니다.** 두 번째 리뷰 이후 API에 대한 변경이 제한적인 경우, *아키텍트는 전체 회의가 필요 없이 이메일로 승인을 선택할 수 있습니다.*
### 3. API Sign Off
**준비물 (리뷰 요청을 위한 GitHub 이슈에 포함시켜야 하는 내용):**
* 각 언어에 대한 API 목록 링크
* API에 대한 미해결 질문에 대해 논의할 준비를 하십시오
The goal of the API sign-off meeting is to resolve any controversial/unsettled questions about the API. These questions can come from language architects or service teams.
### 챔피언 시나리오
**All languages must be signed off before any are released as GA.** When there have been limited changes made to the API since the second review, *architects may choose to sign off over email* without the need for a full meeting.
챔피언 시나리오는 클라이언트 라이브러리의 소비자가 일반적으로 수행할 것으로 예상되는 사용 사례입니다. 챔피언 시나리오는 일반적인 경우에 개발자 경험이 뛰어나도록 보장하는 데 사용됩니다. 챔피언 시나리오에 대한 전체 코드 샘플 (예를 들어, 에러 처리 등)을 보여줘야 합니다. 또한 라이브러리에서 **인증 워크플로우**가 어떻게 보일지도 보여주세요.
**What to bring (include the following in GitHub issue requesting for review):**
* Links to API Listings for each language
* Prepare to talk about unresolved questions about API
좋은 시나리오는 기술에 구애받지 않는 것입니다 (즉, 고객이 여러 가지 방법으로 동일한 작업을 수행할 수 있음), 그리고 이는 사용자의 20% 이상이 사용할 것으로 예상됩니다.
### Champion Scenarios
나쁜 시나리오의 예:
* 클라이언트 생성 (시나리오의 일부이며, 진정한 챔피언 시나리오에서 충분히 볼 수 있음)
* 이벤트 배치 보내기 (다시, 시나리오의 일부)
* 페이지 블롭 생성 (사용자 기반의 충분한 부분에서 사용되지 않음)
A champion scenario is a use case that the consumer of the client library is commonly expected to perform. Champion scenarios are used to ensure the developer experience is exemplary for the common cases. You need to show the entire code sample (including error handling, as an example) for the champion scenarios. Please also show how the **authentication workflow** would look like for your library.
### 퀵스타트 샘플
Good scenarios are technology agnostic (i.e. the customer can do the same thing in multiple ways), and are expected to be used by > 20% of users.
일반적인 방법을 보여주는 샘플:
Examples of bad scenarios:
* Create a client (it's part of a scenario, and we'll see it often enough in true champion scenarios)
* Send a batch of events (again, part of the scenario)
* Create a page blob (it's not used by enough of the user base)
* 새로운 리소스 생성
* 리소스 읽기
* 리소스 수정
* 리소스 삭제
* 에러 처리
* 경쟁 조건/동시성 문제 처리
### Quickstart Samples
## 리뷰 중 발생하는 일
Samples demonstrating common how-tos:
### 누가 참석해야 합니까?
* Create a new resource
* Read the resource
* Modify the resource
* Delete the resource
* Error handling
* Handling race conditions/concurrency issues
API와 서비스에 익숙한 사람들 (보통 엔지니어링 및/또는 PM 리드)이 참석해야 합니다.
## What Happens During Review
### 소개 세션
일반적인 의제는 서비스 팀이 약 30분 동안 서비스를 소개하는 것으로 시작합니다. 그 다음에 챔피언 시나리오가 제시되고, 각 시나리오에 이어서 논의가 이루어집니다. 이는 대부분의 시간을 차지합니다. 만약 Rest API가 사용 가능하다면, 시간이 허락할 경우 이에 대해 이야기합니다. 마지막으로 다음 리뷰 회의 전에 수행할 액션 아이템에 대한 짧은 요약이 있을 것입니다.
### Who should be present?
### API 리뷰
The people familiar with the APIs and service (usually the Engineering and/or PM Lead) should be present.
언어 아키텍트들은 리뷰 시점에 제공된 API 목록을 검토하였을 것입니다. 그들은 제공된 API와 샘플에 대한 논의를 바로 시작할 것입니다. 회의는 취할 액션 아이템에 대한 짧은 요약으로 끝날 것입니다.
### Introductory sessions
The typical agenda starts with service team presenting the service for about 30 minutes. Then champion scenarios will be presented, each followed by discussions. This will take up majority of the time. If there are Rest APIs available, the Board will discuss them if time allows. And finally, there’ll be a short summary of action items to be done before the next review meeting.
### API 승인
### API Reviews
일반적으로, API에 대한 일부 미결정/논란의 여지가 있는 질문들이 있을 것입니다. 이는 API를 검토한 언어 아키텍트들 또는 발표하는 팀에서 비롯될 수 있습니다. 이 리뷰의 목표는 API를 승인하는 것이기 때문에, 보드는 보통 이러한 질문에 대한 논의를 바로 시작합니다. 리뷰는 API에 대한 최종 승인이나 API를 승인받기 위해 따라야 하는 항목들로 끝날 것입니다.
Language architects will have reviewed the API Listings provided by the time of review. They’ll jump right into discussing the API and samples provided. The meeting will end with a short summary of action items to be taken.
### 필요한 퀴럼
### API Sign Off
API가 승인되기 위해서는 아키텍처 보드 회의에서 다음 조건들이 충족되어야 합니다:
Typically, there’ll be some unsettled/controversial questions on the API either from language architects who reviewed the API or from the presenting team. Since the goal of this review is to approve the API, the Board usually jumps right into discussing these questions. The review will end with a final approval of the API or follow up items to get the API to be approved.
* 모든 Tier-1 언어 (Java, Python, TS/JS, C#), 그리고 고려 중인 모든 언어의 대표들이 참석해야 합니다.
* 최소한 세 명의 다른 언어 그룹의 아키텍트들이 참석해야 합니다.
### Required Quorum
만약 언어 아키텍트가 회의에 참석하지 **않는다면**, 부 아키텍트가 해당 언어의 대표가 될 수 있습니다. 언어 대표 목록은 Azure SDK 그룹의 LT에 의해서만 변경될 수 있습니다.
For an API to be approved, the following conditions must be met at the Architecture Board meeting:
## 리뷰 이후에는 어떻게 되나요?
* Representatives from all Tier-1 languages (Java, Python, TS/JS, C#), and all languages under consideration must be present.
* A minimum of THREE architects from different language groups must be present.
소개 및 API 리뷰 세션에서는 보통 다음 회의 전에 처리해야 할 작업 목록이 있습니다. 이 작업 항목을 잊지 말고 따르십시오. 때때로, 이러한 작업 항목 중 하나는 아키텍트들이 제안한 변경 사항을 반영한 후 다른 API 리뷰를 예약하는 것일 수 있습니다.
If a language architect is *not* present at the meeting, a deputy architect can be the representative of that specific language instead. The list of language representatives can only be changed by the LT of the Azure SDK group.
"Release for Architecture Board Approval" 이슈 템플릿을 사용하여 에픽을 만들어 API 리뷰 및 승인을 추적하는 것을 잊지 마세요.
API Sign Off 세션 후 아키텍처 보드가 릴리스를 승인하면, SDK 팀은 Sign Off(승인) 리뷰를 요청하는 이슈에 "RELEASE FOR APPROVAL" 코멘트를 추가합니다. 승인 기록 에픽에 이슈 링크를 추가하는 것을 잊지 마세요!
## What Happens After Review
## API 변경 사항 미리보기
For introductory and API review sessions, there will usually be a list of action items to take before the next meeting. Be sure to follow up on these items. Sometimes, one of these action items could be to schedule for another API review once the architects' suggested changes have been made.
API 변경 사항은 일반적으로 GA로 출시되기 전에 일정 기간 베타 버전으로 출시됩니다. 이렇게 하면 고객들이 피드백을 제공할 수 있는 시간이 주어지며, 이 피드백을 바탕으로 GA 이전에 API에 조정이 이루어질 수 있습니다. 바로 GA로 가는 API 변경 사항은 이러한 피드백의 혜택을 받지 못하므로 고객이 사용하기 어렵고 우리가 지원하기 어려울 수 있습니다. 대부분의 경우, 전체 또는 축약된 리뷰 프로세스를 거친 API 변경 사항은 GA 전에 베타로 출시되어야 합니다.
Remember to create an epic using the issue template “Record of Architecture Board Approval for Release” to keep track of API reviews and approvals.
## 작은, 목표 지향적인 변경 사항 및 버그 수정에 대한 승인 받기
If after an API Sign Off session the Architecture Board approves the release, the SDK Team will add the comment “APPROVED FOR RELEASE” to the issue requesting for the Sign Off review. Remember to add the issue's link to the record of approval epic!
API를 수정하는 작은 또는 목표 지향적인 변경 사항 및 버그 수정의 경우, 각 언어의 아키텍트가 결합된/중앙 리뷰 없이 검토하고 승인할 수 있습니다. 이 검토를 가능한 한 빠르게 하는 것을 강력히 권장합니다. 이것은 API 차이에 대한 링크를 포함하는 GitHub 이슈를 열어 수행해야 합니다. 모든 아키텍트를 리뷰어로 포함시키십시오. 경우에 따라 API의 작은 변경 사항을 효율성을 위해 배치하는 것이 이치에 맞습니다. 언어 아키텍트가 더 깊은 토론이 필요하다고 판단하면, 해당 아키텍트와의 회의를 예약해야 합니다. 만약 이것이 크로스-언어 토론이라면, 보드 회의를 예약해야 합니다.
## Previewing API Changes
API에 대한 모든 변경 사항은 릴리스 전에 언어 아키텍트가 승인해야 함을 기억하십시오.
It is expected that API changes are released in beta for a period of time before they are released as GA. This gives customers time to provide feedback which could result in adjustments to the API before it GAs. API changes that go straight to GA do not benefit from this feedback which can result in them being difficult for customers to use and for us to support. In most circumstances, API changes going through either the full or abbreviated review process should be released as beta before GA.
## 검토가 필요한 API 변경 사항 추적
## Getting Approval for Small, Targeted Changes and Bug Fixes
API가 미리보기 상태에 있거나 GA 상태에 있을 때, API 변경 사항은 항상 명확하지 않을 수 있습니다(개발자 또는 리뷰어에게). 따라서 이런 변경사항을 식별하고 검토하여 고객들에게 최상의 SDK 라이브러리 경험을 제공하는 것이 중요합니다. 장기적으로는 API 추가, 변경, 그리고 중단을 감지하는 도구를 구축할 계획입니다. 그 때까지는, 이미 출시된 API를 수정하는 코드 변경 사항을 식별하기 위해 PR에서 "APIChange" 라벨을 사용할 것입니다. 이것은 언어 아키텍트가 변경 사항을 검토해야 함을 나타냅니다. 아키텍트가 변경 사항을 승인하면 "ArchApproved" 라벨을 추가하게 됩니다. 릴리스 전에는 라이브러리에 병합된 모든 변경 사항을 검토하여 모든 "APIChange" 라벨이 "ArchApproved" 라벨과 짝을 이루고 있는지 확인해야 합니다. 여기에 Java 라이브러리에 대한 [예제 쿼리](https://github.com/Azure/azure-sdk-for-java/pulls?utf8=%E2%9C%93&q=is%3Apr+label%3AAPIChange+)가 있습니다.
For small or targeted changes and bug fixes which modify APIs, the architect in each language can review and sign off without a combined/central review. We highly recommend doing this review as early as possible. This should be done on GitHub by opening an issue with links to API diffs. Include all architects as reviewers. In some cases it makes sense for small changes to the API to be batched for efficiency. If a language architect determines there is a need for a deeper discussion, then a meeting with that architect should be scheduled. If it’s a cross-language discussion, then a board meeting should be scheduled.
Remember that **all** changes to an API must be approved by the language architect before release.
## Tracking API Changes That Need to be Reviewed
While an API is in preview or after it is in GA, changes to APIs are not always obvious (to the developer or the reviewer) when they’re being made so it’s important that we identify them and review them to ensure the best SDK library experience for our customers. Long-term we will have tooling in place to detect API additions, changes, and breaks. Until then, we will use the “APIChange” label on PRs to identify code changes that included a modification to an already released API. This signals to that a language architect needs to review the change. Once they’ve approved the change they would add the “ArchApproved” label. Before release, a review of all changes merged into the library should be done to ensure that all “APIChange” labels are paired with an “ArchApproved” label. Here is an [example query](https://github.com/Azure/azure-sdk-for-java/pulls?utf8=%E2%9C%93&q=is%3Apr+label%3AAPIChange+) for the Java libraries.
When the library developers indicate they’re ready to release, these should be reviewed by the architect as part of final signoff before GA. Libraries should not be released as GA (or updated to GA) if there are unresolved “APIChange” labels without a corresponding “ArchApproved” label. Once final review is requested, all “APIChange” labels will be responded to within 5 working days.
라이브러리 개발자들이 릴리스 준비가 되었다고 표시하면, 아키텍트가 GA 이전에 최종 승인의 일부로 이를 검토해야 합니다. 해결되지 않은 "APIChange" 라벨이 있고 대응하는 "ArchApproved" 라벨이 없는 경우 라이브러리는 GA로 출시되어서는 안됩니다(또는 GA로 업데이트되어서는 안됩니다). 최종 리뷰가 요청되면, 모든 "APIChange" 라벨에는 5일 이내에 응답될 것입니다.
{% include refs.md %}