Add Beachball to repository for publishing NPM packages (#103)

* add initial beachball implementation

* Change files

* updates on issues found during testing including updated documentation

* update to workspace dictionary items

* remove to revert inadvertant change file commit

* update documentation

* Change files

* update to notify on Discord

* update to remove change files on initial rollout

* updates to resolve review feedback

.github/workflows/cd-publish.yml

@@ -0,0 +1,53 @@
+name: CD - Publisher
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 7 * * 0-4'
+
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  GITHUB_SERVICE_USER: "FAST DevOps"
+  GITHUB_SERVICE_EMAIL: "fastsvc@microsoft.com"
+      
+jobs:
+  build_linux:
+    runs-on: ubuntu-latest
+    if: contains('janechu,williamw2,awentzel,eisenbergeffect', github.actor)
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+        token: ${{ env.GITHUB_TOKEN }}
+
+    - name: Set Git User
+      run: |
+        git config --global user.name "${{ env.GITHUB_SERVICE_USER }}"
+        git config --global user.email "${{ env.GITHUB_SERVICE_EMAIL }}"
+   
+    - name: Install package dependencies / prepare workspaces
+      run: npm ci
+
+    - name: Check for the presence of changed files inside ./change
+      run: npm run check
+
+    - name: Build
+      run: npm run build --if-present
+
+    - name: Test
+      run: npm run test --if-present
+   
+    - name: Publish NPM packages
+      env:
+        NPM_SECRET_TOKEN: ${{ secrets.NPM_TOKEN }}
+      run: npm run publish-ci -n $NPM_SECRET_TOKEN
+    
+    - name: Notify on Discord
+      uses: appleboy/discord-action@master
+      with:
+        webhook_id: ${{ secrets.DISCORD_NOTIFICATION_WEBHOOK_ID }}
+        webhook_token: ${{ secrets.DISCORD_NOTIFICATION_WEBHOOK_TOKEN }}
+        color: "#DE2D6D"
+        username: "FAST DevOps Bot"
+        message: "Publish was triggered by ${{ github.actor }} located at https://github.com/microsoft/fast-tooling/actions"

.github/workflows/ci-validate.yml

@@ -1,4 +1,4 @@
-name: CI - FAST Tooling
+name: CI - Validator
 
 on:
   push:

.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  "cSpell.words": [
+    "appleboy",
+    "awentzel",
+    "beachball",
+    "changehint",
+    "copyfiles",
+    "eisenbergeffect",
+    "instrumenter",
+    "janechu",
+    "languageservice",
+    "prettierrc",
+    "williamw2"
+  ]
+}

CONTRIBUTING.md

@@ -1,5 +1,7 @@
 # Contributing to FAST Tooling
 
+Contributions are welcome! You can submit a pull request to fix a bug, implementing a feature, or even correcting simple documentation typos.
+
 ## Getting started
 
 ### Machine setup
@@ -57,36 +59,19 @@ Packages are located within the `packages` folder of the repository. Each packag
 
 ### Submitting a pull request
 
-If you'd like to contribute by fixing a bug, implementing a feature, or even correcting typos in our documentation, you'll want to submit a pull request. Ensure that your changes adhere to the standards defined in the [style guide](./STYLE_GUIDE.md). Before submitting a pull request, be sure to [rebase](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) your branch from `main` or use the *merge* button provided by GitHub.
-When submitting your pull request please make the title clear and concise, provide a description of the change, and specify any issues that will be closed.
+Prior to submitting a pull request please follow the following steps.
 
-#### Change Files
-Any pull request which includes changes within the `packages/*` directory requires a corresponding change file. Before pushing your changes to create a pull request, be sure you have included the necessary change file(s). To generate a change file, run `npm change` in the root of the repository. The generated file will be checked into the repo automatically for you as part of the process.
-
-:::note
-When working across feature branches, you'll need to target the branch using the following command: `npm change --branch origin/{branch-name}`.
-:::
-
-**Example: Generated change file:**
-```json
-{
-  "type": "minor",
-  "comment": "Add fancy new feature for components.",
-  "packageName": "@microsoft/fast-tooling",
-  "email": "name@example.com",
-  "dependentChangeType": "minor",
-  "date": "2021-03-01T19:10:06.323Z"
-}
-```
-
-Running `npm change` will walk you through a CLI process for generating change files. The process will walk you through selecting the type of change as well as ask you to provide a description of any changes. As a convenience, the utility looks to provide recent commit messages for use in the description. *For changes which do not affect the published package(s), please use "none" when selecting the change type*.
-
-More information on the change process and change types can be found on the [beachball website](https://microsoft.github.io/beachball/cli/change.html#change).
+1. Review and adhere to the standards defined in the [style guide](./STYLE_GUIDE.md).
+2. Rebase your branch from `main` or use the *merge* button provided by GitHub. If you're new to rebasing checkout [Merging vs Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).
+3. Generate a change file(s) using `npm run change` located in `./change/*` and used for continuous delivery. As a convenience, the interactive prompt looks to provide recent commit messages for use in the description. *For changes which do not affect the published package(s), please use "none" when selecting the change type*.
+4. Finally, when submitting your pull request please make the title clear and concise, provide a description of the change, and specify any issues that will be closed.
 
 :::note
 If you are addressing multiple issues which are unrelated, consider either doing multiple pull requests, or generate separate change files to ensure accurate generation of changelogs and versioning of packages.
 :::
 
+For additional details on package versioning and changelog generation read the [Publishing](./PUBLISHING.md) documentation.
+
 ### Documenting breaking changes
 
 Make sure to document the migration strategy in a `MIGRATION.md` file in the package(s) that has breaking changes, eg. `packages/fast-tooling/MIGRATION.md`.
@@ -102,7 +87,7 @@ Example of how to format `MIGRATION.md`:
 - `Bat` has been updated to use the new API [`BatConfig`](link/to/api).
 ```
 
-### Recommended Settings for Visual Studio Code
+### Recommended settings for Visual Studio Code
 
 You can use any code editor you like when working with the FAST Tooling monorepo. One of our favorites is [Visual Studio Code](https://code.visualstudio.com/). VS Code has great autocomplete support for TypeScript and JavaScript APIs, as well as a rich ecosystem of plugins.
 

PUBLISHING.md

@@ -0,0 +1,48 @@
+# Publishing
+This project uses [Beachball](https://microsoft.github.io/beachball/) to publish packages to NPM. The process involves a series of script commands located in the root `package.json` file to check, change, and publish NPM packages.
+
+The pipeline process looks for change files on an automated schedule or manual execution and publishes to the NPM Registry.
+
+## How it works
+Beachball is configured for patches and minor changes in a single file (`./beachball.config.js`). _Major changes are ignored, except when manually planning a Major release._
+
+Running `npm run change` triggers an interactive process on the command line to capture the type and description of the change. These details are used to generate a file in the `./change/*` folder. Change file names are formatted as `{package-name}-{guid}.json` with the following example.
+
+File location and name: `change/@microsoft-fast-tooling-4685ad54-b24a-4d2b-b160-519d410f468d.json`
+```json
+{
+  "type": "minor",
+  "comment": "Add fancy new feature for components.",
+  "packageName": "@microsoft/fast-tooling",
+  "email": "name@example.com",
+  "dependentChangeType": "minor",
+  "date": "2021-03-01T19:10:06.323Z"
+}
+```
+:::note
+More information on the change process and change types can be found on the [Beachball website](https://microsoft.github.io/beachball/cli/change.html#change).
+:::
+
+These changes are then committed and submitted as a pull request for code review. Once approved and merged into `main` the continuous delivery (CD) process awaits, located on GitHub Actions [CD - Publisher](https://github.com/microsoft/fast-tooling/blob/main/.github/workflows/cd-publish.yml) workflow. This process is triggered every Sunday through Thursday night or on-demand available for repository code owners.
+
+Once fired, the `./change/*` files are used as instructions for Beachball's [Semantic versioning](https://semver.org/) and changelog generation. The process then runs `npm run publish-ci` to publish new package versions to the NPM registry. Publishing to the NPM registry requires a GitHub Secret `NPM_TOKEN` which can be found on the NPM User account for the "Access Tokens" page.
+
+If successful, all changes are then committed back into the `main` branch and a notification is sent to the Discord's channel named `#ms-internal-notifications`. This requires two GitHub Secrets where the values can be found within the Discord channel's Webhook URL `https://discord.com/api/webhooks/{DISCORD_NOTIFICATION_WEBHOOK_ID}/{DISCORD_NOTIFICATION_WEBHOOK_TOKEN}`. These GitHub Secret key names are DISCORD_NOTIFICATION_WEBHOOK_ID and DISCORD_NOTIFICATION_WEBHOOK_TOKEN.
+
+## Testing
+When Beachball configurations are changed it's a great idea to validate the entire Beachball publishing process.
+
+1. Check that changes are acknowledged
+```bash
+npm run check
+```
+
+2. Check for changes and that a change file is generated
+```bash
+npm run change
+```
+
+3. Check that each package is versioned and changelogs are created (Changelogs are named `CHANGELOG.json` and `CHANGELOG.md`). This command simulates publishing, without updating the NPM registry. This is a verification step only, the bumped changes should not be staged or committed. Simply revert after the changes are successful.
+```bash
+npm run bump
+```

beachball.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+    disallowedChangeTypes: ["major"],
+};

package.json

@@ -20,6 +20,11 @@
     "url": "https://github.com/microsoft/fast-tooling/issues/new/choose"
   },
   "scripts": {
+    "bump": "beachball bump",
+    "change": "beachball change",
+    "check": "beachball check --changehint \"Run 'npm run change' to generate a change file\"",
+    "publish": "beachball publish",
+    "publish-ci": "beachball publish -y --access public",
     "test:diff:error": "echo \"Untracked files exist, try running npm prepare to identify the culprit.\" && exit 1",
     "test:diff": "git update-index --refresh && git diff-index --quiet HEAD -- || npm run test:diff:error",
     "test": "npm run prettier --workspaces --if-present && npm run test:diff && npm run test --workspaces --if-present"
@@ -37,20 +42,19 @@
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^2.23.0",
     "@typescript-eslint/parser": "^2.23.0",
+    "beachball": "^2.16.0",
+    "chalk": "^2.4.2",
+    "copyfiles": "^2.4.1",
+    "dotenv": "^6.0.0",
     "eslint": "^6.8.0",
     "eslint-config-prettier": "^6.10.1",
     "eslint-plugin-import": "^2.20.1",
     "eslint-plugin-react": "^7.19.0",
-    "chalk": "^2.4.2",
-    "copyfiles": "^2.4.1",
-    "dotenv": "^6.0.0",
     "glob": "^7.1.2",
     "husky": "^4.2.5",
     "lint-staged": "^10.1.2",
     "prettier": "2.0.2",
     "rimraf": "^3.0.2",
     "yargs": "^16.2.0"
-  },
-  "dependencies": {
   }
 }