Minor doc updates (#987)

README.md

@@ -79,20 +79,24 @@ show help message
 
 skips the prompts for publish
 
-## Overriding Concurrency
-
-In large monorepos, the Beachball sync process can be time-consuming due to the high number of packages. To optimize performance, you can override the default concurrency (typically set to 2 or 5) by setting the NPM_CONCURRENCY environment variable to a value that best suits your needs
-
 ## Examples
 
 ```
-  $ beachball
+$ beachball
 
-  $ beachball check
+$ beachball check
 
-  $ beachball publish -r http://localhost:4873 -t beta
+$ beachball publish -r http://localhost:4873 -t beta
 ```
 
-<!--
-If making changes, don't forget to update the version under packages/beachball/README.md too!
--->
+## Notes
+
+### Overriding concurrency
+
+In large monorepos, the Beachball sync process can be time-consuming due to the high number of packages. To optimize performance, you can override the default concurrency (typically 2 or 5) by setting the `NPM_CONCURRENCY` environment variable to a value that best suits your needs.
+
+### API surface
+
+Beachball **does not** have a public API beyond the provided [options](https://microsoft.github.io/beachball/overview/configuration.html). Usage of private APIs is not supported and may break at any time.
+
+If you need to customize something beyond what's currently supported in the options, please open a feature request or talk with the maintainers.

change/beachball-6783701e-869a-4075-b933-f3ea58db98f7.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Update readme",
+  "packageName": "beachball",
+  "email": "elcraig@microsoft.com",
+  "dependentChangeType": "patch"
+}

docs/cli/options.md

@@ -40,4 +40,3 @@ These options are applicable for the `publish` command, as well as `bump` and/or
 | `--token`                     | `-n`  |                                | credential to use with npm commands. its type is specified with the `--authType` argument                                                  |
 | `--verbose`                   |       | `false`                        | prints additional information to the console                                                                                               |
 | `--yes`                       | `-y`  | if CI detected, `true`         | skips the prompts for publish                                                                                                              |
-| `--new`                       |       | `false`                        | publishes new packages if not in registry                                                                                                  |

src/bump/bumpPackageInfoVersion.ts

@@ -3,7 +3,8 @@ import semver from 'semver';
 import { BeachballOptions } from '../types/BeachballOptions';
 
 /**
- * Bumps an individual package version based on the change type
+ * Bumps an individual package version based on the change type.
+ * **This mutates `info.version`!**
  */
 export function bumpPackageInfoVersion(pkgName: string, bumpInfo: BumpInfo, options: BeachballOptions): void {
   const { calculatedChangeTypes, packageInfos, modifiedPackages } = bumpInfo;

src/publish/getNewPackages.ts

@@ -2,17 +2,24 @@ import { BumpInfo } from '../types/BumpInfo';
 import { listPackageVersions } from '../packageManager/listPackageVersions';
 import { NpmOptions } from '../types/NpmOptions';
 
+/**
+ * Get package versions from the registry to determine if there are any new packages that didn't
+ * have a change file. (This will only fetch packages *not* in `modifiedPackages`.)
+ * @returns List of detected new packages
+ */
 export async function getNewPackages(
   bumpInfo: Pick<BumpInfo, 'modifiedPackages' | 'packageInfos'>,
   options: NpmOptions
 ): Promise<string[]> {
   const { modifiedPackages, packageInfos } = bumpInfo;
 
-  const newPackages = Object.keys(packageInfos).filter(pkg => !modifiedPackages.has(pkg) && !packageInfos[pkg].private);
+  const maybeNewPackages = Object.keys(packageInfos).filter(
+    pkg => !modifiedPackages.has(pkg) && !packageInfos[pkg].private
+  );
 
-  const publishedVersions = await listPackageVersions(newPackages, options);
+  const publishedVersions = await listPackageVersions(maybeNewPackages, options);
 
-  return newPackages.filter(pkg => {
+  return maybeNewPackages.filter(pkg => {
     if (!publishedVersions[pkg]?.length) {
       console.log(`New package detected: ${pkg}`);
       return true;

src/publish/publishToRegistry.ts

@@ -12,6 +12,7 @@ import { callHook } from '../bump/callHook';
 
 /**
  * Publish all the bumped packages to the registry.
+ * This will bump packages on the filesystem first if `options.bump` is true.
  */
 export async function publishToRegistry(originalBumpInfo: BumpInfo, options: BeachballOptions): Promise<void> {
   const bumpInfo = _.cloneDeep(originalBumpInfo);

src/types/BeachballOptions.ts

@@ -43,11 +43,12 @@ export interface CliOptions
   keepChangeFiles?: boolean;
   /**
    * For publish: If true, publish all newly added packages in addition to modified packages.
-   * New packages *with change files* will always be published regardless of this option.
+   * This is rarely needed since new packages *with change files* will always be published
+   * regardless of this option.
    *
    * (This has limited use unless you pushed new packages directly to the main branch, or
    * your PR build doesn't run `beachball check`. Otherwise, `beachball check` will require
-   * change files to be created for the missing packages.)
+   * change files to be created for the new packages.)
    */
   new: boolean;
   package?: string | string[];

src/types/BumpInfo.ts

@@ -1,13 +1,16 @@
 import { ChangeSet, ChangeType } from './ChangeInfo';
-import { PackageInfo, PackageGroups } from './PackageInfo';
+import { PackageInfos, PackageGroups } from './PackageInfo';
 import { VersionGroupOptions } from './BeachballOptions';
 
 export type BumpInfo = {
   /** Changes coming from the change files */
   changeFileChangeInfos: ChangeSet;
 
-  /** Cached version of package info (e.g. package.json, package path) */
-  packageInfos: { [pkgName: string]: PackageInfo };
+  /**
+   * Cached version of package info (e.g. package.json, package path).
+   * This will be updated to reflect the bumped versions and dependencies.
+   */
+  packageInfos: PackageInfos;
 
   /** Change types collated by the package names */
   calculatedChangeTypes: { [pkgName: string]: ChangeType };