From 27e63e2b33be48b26a44da69c09198ef9a8dce21 Mon Sep 17 00:00:00 2001
From: Charles Lyding <19598772+clydin@users.noreply.github.com>
Date: Thu, 20 Feb 2020 18:26:20 -0500
Subject: [PATCH] fix(@angular-devkit/build-angular): mark programmatic builder
 execution functions as experimental

While the builders when executed via the Angular CLI and their associated options are considered stable, the programmatic APIs are not considered officially supported and are not subject to the breaking change guarantees of SemVer.
The programmatic APIs for the builders are now explicitly marked as experimental. This allows the package to use a stable versioning scheme while also continuing to provide access to the experimental programmatic API elements of the package.
---
 packages/angular_devkit/build_angular/src/browser/index.ts | 6 ++++++
 .../angular_devkit/build_angular/src/dev-server/index.ts   | 7 ++++++-
 .../angular_devkit/build_angular/src/extract-i18n/index.ts | 3 +++
 packages/angular_devkit/build_angular/src/karma/index.ts   | 3 +++
 .../angular_devkit/build_angular/src/ng-packagr/index.ts   | 3 +++
 .../angular_devkit/build_angular/src/protractor/index.ts   | 3 +++
 packages/angular_devkit/build_angular/src/server/index.ts  | 7 ++++++-
 7 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/packages/angular_devkit/build_angular/src/browser/index.ts b/packages/angular_devkit/build_angular/src/browser/index.ts
index ec8a3cbca1e7..0de231bbcf4b 100644
--- a/packages/angular_devkit/build_angular/src/browser/index.ts
+++ b/packages/angular_devkit/build_angular/src/browser/index.ts
@@ -79,6 +79,9 @@ import { Schema as BrowserBuilderSchema } from './schema';
 
 const cacheDownlevelPath = cachingDisabled ? undefined : findCachePath('angular-build-dl');
 
+/**
+ * @experimental Direct usage of this type is considered experimental.
+ */
 export type BrowserBuilderOutput = json.JsonObject &
   BuilderOutput & {
     baseOutputPath: string;
@@ -186,6 +189,9 @@ async function initialize(
   return { config: transformedConfig || config, projectRoot, projectSourceRoot, i18n };
 }
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 // tslint:disable-next-line: no-big-function
 export function buildWebpackBrowser(
   options: BrowserBuilderSchema,
diff --git a/packages/angular_devkit/build_angular/src/dev-server/index.ts b/packages/angular_devkit/build_angular/src/dev-server/index.ts
index 8163ff6c2358..736fe3741eee 100644
--- a/packages/angular_devkit/build_angular/src/dev-server/index.ts
+++ b/packages/angular_devkit/build_angular/src/dev-server/index.ts
@@ -62,16 +62,21 @@ const devServerBuildOverriddenKeys: (keyof DevServerBuilderOptions)[] = [
   'deployUrl',
 ];
 
+/**
+ * @experimental Direct usage of this type is considered experimental.
+ */
 export type DevServerBuilderOutput = DevServerBuildOutput & {
   baseUrl: string;
 };
 
 /**
- * Reusable implementation of the build angular webpack dev server builder.
+ * Reusable implementation of the Angular Webpack development server builder.
  * @param options Dev Server options.
  * @param context The build context.
  * @param transforms A map of transforms that can be used to hook into some logic (such as
  *     transforming webpack configuration before passing it to webpack).
+ *
+ * @experimental Direct usage of this function is considered experimental.
  */
 // tslint:disable-next-line: no-big-function
 export function serveWebpackBrowser(
diff --git a/packages/angular_devkit/build_angular/src/extract-i18n/index.ts b/packages/angular_devkit/build_angular/src/extract-i18n/index.ts
index 648a04da3d47..6748db2a9e6d 100644
--- a/packages/angular_devkit/build_angular/src/extract-i18n/index.ts
+++ b/packages/angular_devkit/build_angular/src/extract-i18n/index.ts
@@ -121,6 +121,9 @@ class NoEmitPlugin {
   }
 }
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 export async function execute(
   options: ExtractI18nBuilderOptions,
   context: BuilderContext,
diff --git a/packages/angular_devkit/build_angular/src/karma/index.ts b/packages/angular_devkit/build_angular/src/karma/index.ts
index a501f9f3ff9a..76678ec8c1d5 100644
--- a/packages/angular_devkit/build_angular/src/karma/index.ts
+++ b/packages/angular_devkit/build_angular/src/karma/index.ts
@@ -60,6 +60,9 @@ async function initialize(
   ];
 }
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 export function execute(
   options: KarmaBuilderOptions,
   context: BuilderContext,
diff --git a/packages/angular_devkit/build_angular/src/ng-packagr/index.ts b/packages/angular_devkit/build_angular/src/ng-packagr/index.ts
index d8e2fa24262c..09aad0f68717 100644
--- a/packages/angular_devkit/build_angular/src/ng-packagr/index.ts
+++ b/packages/angular_devkit/build_angular/src/ng-packagr/index.ts
@@ -26,6 +26,9 @@ async function initialize(
   return packager;
 }
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 export function execute(
   options: NgPackagrBuilderOptions,
   context: BuilderContext,
diff --git a/packages/angular_devkit/build_angular/src/protractor/index.ts b/packages/angular_devkit/build_angular/src/protractor/index.ts
index eb4b81578074..7d3aca6cd704 100644
--- a/packages/angular_devkit/build_angular/src/protractor/index.ts
+++ b/packages/angular_devkit/build_angular/src/protractor/index.ts
@@ -85,6 +85,9 @@ async function updateWebdriver() {
 
 export { ProtractorBuilderOptions };
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 export async function execute(
   options: ProtractorBuilderOptions,
   context: BuilderContext,
diff --git a/packages/angular_devkit/build_angular/src/server/index.ts b/packages/angular_devkit/build_angular/src/server/index.ts
index a8f0c2c74e63..6c0934943164 100644
--- a/packages/angular_devkit/build_angular/src/server/index.ts
+++ b/packages/angular_devkit/build_angular/src/server/index.ts
@@ -31,7 +31,9 @@ import {
 import { JsonCompilationStats, webpackStatsLogger } from '../webpack/utils/stats';
 import { Schema as ServerBuilderOptions } from './schema';
 
-// If success is true, outputPath should be set.
+/**
+ * @experimental Direct usage of this type is considered experimental.
+ */
 export type ServerBuilderOutput = json.JsonObject & BuilderOutput & {
   baseOutputPath: string;
   outputPaths: string[];
@@ -43,6 +45,9 @@ export type ServerBuilderOutput = json.JsonObject & BuilderOutput & {
 
 export { ServerBuilderOptions };
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 export function execute(
   options: ServerBuilderOptions,
   context: BuilderContext,