Skip to content

Using Swift APIView

Jump to bottom
Travis Prescott edited this page Oct 6, 2022 · 2 revisions

1. Introduction

APIView now has support for the Swift language! Please see the guidance in the azure-sdk-tools repo for installation and usage instructions.

This document describes how to use Swift APIView to facilitate reviews for iOS.

2. Limitations

APIView itself supports Manual, Automatic, and PR-based reviews. Unfortunately, at this time, there is only support for Manual reviews for Swift APIView. When Automatic and PR-based reviews are supported, this guidance will be revised.

3. APIView Review Process

APIView is a tool used by the Architecture Review Board (ARB or ArchBoard) to review and approve the API surface areas of SDKs prior to release to ensure quality UX and prevent or mitigate breaking changes. However, it can be used by service teams to gather feedback on specific features, which facilitates early engagement.

All SDKs should have their API surface area reviewed and approved by the ARB. Feature reviews are a courtesy and an approval on a feature review can never be considered as approval to release an SDK, even if the proposed SDK only incorporates approved features. An SDK review must be created and approved separately.

4. SDK Reviews

SDK reviews are what the ArchBoard uses to approve the release of SDKs. While the approval of feature reviews can make it easier to review the SDK, the only API-surface area that matters is what will be expressed in the SDK. For languages which have automatic reviews, the automatic review is the SDK review and is used for release-gating SDKs.

Since Swift does NOT have automatic reviews, manual reviews must be used. The following guidance should be used for creating and maintaining Swift SDK reviews.

  1. all revisions in an SDK review must be prefixed with "SDK" to clearly distinguish them from feature reviews. This is done using the "optional review/revision label" in the APIView UI when uploading the token file.
  2. the version of Swift APIView should be the same for all revisions. If a change in Swift APIView results in a non-trivial diff that is distracting, a new APIView should be created. If the version of Swift APIView stays consistent, a given SDK review could facilitate review of many SDK releases.
  3. the first entry in the APIView MUST be the latest released GA version of the SDK (if applicable).
  4. the next entry in the APIView MUST be the latest released beta version of the SDK (if applicable).
  5. all revisions MUST be accurately tagged with the SDK version they represent. If the version does not look correct, it can be forcefully set by supplying the --package-version argument. The optional review label when creating the review should say "SDK - {version}".
  6. no SDK version may appear more than once in the revision history. If a change is made to a proposed release as a new revision, the outdated revision MUST be deleted before the latter revision can be approved. This is to prevent confusion as to which version of a the SDK was actually approved.

image

5. Feature Reviews

Feature reviews are helpful for service teams to collect feedback early and should make it easier to review SDK releases. However, the "approved" status of any feature review is NOT approval for the release of any SDK, even if the proposed SDK only contains approved features. All SDK releases must have an approved SDK review.

The follow guidance should be followed for creating feature reviews.

  1. all revisions in a feature review must be prefixed with "Feature" to clearly distinguish them from SDK reviews. This is done using the "optional review/revision label" in the APIView UI when uploading the token file.
  2. the version of Swift APIView should be the same for all revisions. If a change in Swift APIView results in a non-trivial diff that is distracting, a new APIView should be created. If the version of Swift APIView stays consistent, a given SDK review could facilitate review of many features.
  3. the first entry in the APIView MUST be the latest released GA version of the SDK (if applicable). The optional label when creating this review should say "Feature - {version}".
  4. the next entry in the APIView MUST be the latest released beta version of the SDK (if applicable). The optional label when creating this review should say "Feature - {version}".
  5. except for the baseline revisions, further revisions MUST NOT be labeled with any SDK version. The optional label when creating these revisions should be "Feature - {feature name}".

image

Clone this wiki locally