fast-tooling/PUBLISHING.md

Publishing

This project uses 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-design-to-code-4685ad54-b24a-4d2b-b160-519d410f468d.json

{
  "type": "minor",
  "comment": "Add fancy new feature for components.",
  "packageName": "@microsoft/design-to-code",
  "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. :::

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 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 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

npm run check

2. Check for changes and that a change file is generated

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.

npm run bump

NPM Authentication Best Practices

1. Publishing with an NPM Token should be configured to require two-factor authentication or automation tokens from the fastsvc@microsoft.com service account which uses the Authenticator App for 2FA, if needed for manual publishing, otherwise automation skips 2FA.
2. When creating the new NPM Access Token select the "Automation" type which will then bypass 2FA from the workflow.
3. Add this token to GitHub Secrets as NPM_TOKEN.
4. Always include registry-url: 'https://registry.npmjs.org' on actions/setup-node@v1 runner, in the YAML workflow file, even though it feels like it should be the default.
5. Always set NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} to minimize authentication issues. This will automatically create the correct .npmrc configuration for the workflow.

GIT Authentication Best Practices

1. Automated committing to a protected branch such as main requires a PAT (Personal Access Token) from a user with 'git' security permissions specifying 'repo' during the creation of the PAT. After the creation of the PAT, ensure the PAT has SSO authorization for the Microsoft Organization which should be a dropdown next to the newly created PAT in the GitHub UI.
2. This token should be added to the repositories GitHub Secrets as GH_TOKEN.
3. The token can then be referred to in GitHub workflows as GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}.

Publishing Resources

• Hackernoon
• GitHub