Add missed doc site page and update instructions (#1193)

Author: ecraig12345

.github/workflows/pr.yml

@@ -55,6 +55,9 @@ jobs:
 
       - run: yarn checkchange --verbose
 
+      - run: yarn format:check
+        if: matrix.os == 'ubuntu-latest'
+
       - run: yarn lint
 
       - run: yarn test:unit

.prettierignore

@@ -8,6 +8,9 @@
 .nojekyll
 .nvmrc
 docs/.vuepress/dist/
+docs/.vuepress/.cache/
+docs/.vuepress/.temp/
+docs/.yarn
 /change/
 /CHANGELOG.*
 /lib/

.prettierrc.json5

@@ -4,6 +4,7 @@
   "singleQuote": true,
   "printWidth": 120,
   "arrowParens": "avoid",
+  "endOfLine": "lf",
   "overrides": [
     {
       // format .json5 files as jsonc for VS Code support

CLAUDE.md

@@ -22,17 +22,6 @@ Beachball is a CLI tool for automating semantic version bumping, changelog gener
 | Format                        | `yarn format`                   |
 | Update snapshots              | `yarn update-snapshots`         |
 
-### Required before each commit
-
-- `yarn build`
-- `yarn test`
-- `yarn lint`
-- `yarn format`
-
-### Required before creating a PR
-
-Use `/beachball-change-files` to generate a Beachball change file. Use `yarn change` for `beachball change` and `yarn checkchange` for `beachball check`.
-
 ## Architecture
 
 **Entry point:** `src/cli.ts` dispatches to commands: `check`, `change`, `bump`, `publish`, `canary`, `sync`, `init`, `config`.
@@ -52,7 +41,9 @@ Use `/beachball-change-files` to generate a Beachball change file. Use `yarn cha
 
 **Option resolution:** CLI args > `beachball.config.js` (via cosmiconfig) > defaults. `getParsedOptions()` returns both raw `cliOptions` and merged `options`.
 
-## Code Conventions
+## Coding standards
+
+### Style and conventions
 
 **No global state:** `process.cwd()`, `process.chdir()`, and `process.exit()` are banned via ESLint. All operations take an explicit `cwd` parameter. `process.exit()` should only be called in `cli.ts`.
 
@@ -64,7 +55,27 @@ Use `/beachball-change-files` to generate a Beachball change file. Use `yarn cha
 
 **Style:** Prettier with single quotes, 120 char width, trailing commas (ES5)
 
-## Test Structure
+### Documentation
+
+- You must update the documentation site when adding a new option or command
+- Also consider whether documentation site updates are needed for other new features or behavior changes
+- All headings in the documentation site and other markdown files must use sentence case
+
+### Required before each commit
+
+- `yarn build`
+- `yarn test`
+- `yarn lint`
+- `yarn format`
+
+### Required before creating a PR
+
+- Use `/beachball-change-files` to generate a Beachball change file. Use `yarn change` for `beachball change` and `yarn checkchange` for `beachball check`.
+- Consider whether the
+
+## Testing
+
+### Test structure
 
 Three Jest projects:
 
@@ -74,7 +85,7 @@ Three Jest projects:
 
 Test helpers in `src/__fixtures__/` provide mock factories for repos, logs, package infos, and change files.
 
-### Test writing tips
+### Test writing standards
 
 - Avoid manually creating complex object structures (such as `PackageInfos`, `ChangeInfo`, `BumpInfo`, or `BeachballOptions`). Consider one of the following approaches instead:
   - call the real function for generating the structure if possible
@@ -84,3 +95,13 @@ Test helpers in `src/__fixtures__/` provide mock factories for repos, logs, pack
 - Any test of a function which writes to the console should call `initMockLogs()` to mock and capture output.
 - Beachball's logs are its UI. Often, tests should include complete inline snapshots of output (especially if it's only a few lines).
 - Where reasonable, prefer complete tests of values: `expect(someObj).toEqual({...})` rather than `expect(someObj.foo).toEqual(...)` or `expect(someObj).toMatchObject({...})`, or `expect(someArray).toEqual([...])` rather than `expect(someArray).toContain(...)`
+
+## Documentation site
+
+The doc site uses Vuepress and is located under `/docs`. It uses a separate yarn installation with Node 22 + Yarn 4 to get rid of very outdated deps while keeping beachball v2 on Node 14.
+
+### Editing and validating docs
+
+- If running in a standalone agent environment, you must run `cd docs && yarn` to install dependencies first
+- Doc changes can be validated with `cd docs && yarn docs:build`
+- If adding a new page, you MUST add it to the sidebar in `docs/.vuepress/config.ts`.

README.md

@@ -66,7 +66,7 @@ target branch from remote (default: as configured in `git config init.defaultBra
 
 ### `--type`
 
-for the `change` command: change type for all changed packages
+for the `change` command: [change type](https://microsoft.github.io/beachball/concepts/change-types.html) for all changed packages
 
 ### `--package`
 

beachball.config.js

@@ -1,6 +1,8 @@
 // @ts-check
 /** @type {Partial<import('./src/types/BeachballOptions').RepoOptions>}*/
 const config = {
+  branch: 'main',
+  commit: false,
   disallowedChangeTypes: ['major'],
   ignorePatterns: [
     '.*ignore',

change/beachball-a39bc663-3482-4134-a5a6-ff7e04b36043.json

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

docs/.vuepress/config.ts

@@ -27,6 +27,7 @@ export default defineUserConfig({
         children: [
           '/concepts/bump-algorithm',
           '/concepts/change-files',
+          '/concepts/change-types',
           '/concepts/ci-integration',
           '/concepts/groups',
         ],

docs/README.md

@@ -1,26 +1,3 @@
----
-home: true
-# heroImage: /hero.png
-heroText: The Sunniest Semantic Version Bumper
-tagline: Makes automating npm publishing a breeze
-actions:
-  - text: Get Started →
-    link: /overview/getting-started
-    type: primary
+# Beachball doc site
 
-features:
-  - title: Synchronized in git and npm
-    details: 'keep your git and npm versions in sync in CI and local workflows'
-  - title: Generates Changelogs
-    details: same command will generate changelogs for your users
-  - title: Automated Version Bumps
-    details: one command line to bump package(s) in your repo with semver
-  - title: Single or Monorepo
-    details: compatible out of the box for single repo or monorepos
-  - title: Pre-Publish Validation Checks
-    details: double and triple check git repo and npm registry before publish
-  - title: Zero Config Versioning
-    details: no config is required to get started, do more in one line
-
-footer: MIT Licensed | Copyright © 2019-present Microsoft
----
+This site is built with Vuepress v2. It uses a separate yarn installation with Node 22 + Yarn 4 to get rid of very outdated deps while keeping beachball v2 on Node 14.

docs/index.md

@@ -0,0 +1,26 @@
+---
+home: true
+# heroImage: /hero.png
+heroText: The Sunniest Semantic Version Bumper
+tagline: Makes automating npm publishing a breeze
+actions:
+  - text: Get Started →
+    link: /overview/getting-started
+    type: primary
+
+features:
+  - title: Synchronized in git and npm
+    details: 'keep your git and npm versions in sync in CI and local workflows'
+  - title: Generates Changelogs
+    details: same command will generate changelogs for your users
+  - title: Automated Version Bumps
+    details: one command line to bump package(s) in your repo with semver
+  - title: Single or Monorepo
+    details: compatible out of the box for single repo or monorepos
+  - title: Pre-Publish Validation Checks
+    details: double and triple check git repo and npm registry before publish
+  - title: Zero Config Versioning
+    details: no config is required to get started, do more in one line
+
+footer: MIT Licensed | Copyright © 2019-present Microsoft
+---