add changesets and documentation (#510)

silesky · web-flow · commit e2661b7be7a8 · 2022-06-30T17:07:13.000-05:00
diff --git a/.buildkite/pipeline.yml b/.buildkite/pipeline.yml
@@ -107,20 +107,3 @@ steps:
       - ssh://git@github.com/segmentio/cache-buildkite-plugin#v2.0.0:
           key: "v1.1-cache-dev-{{ checksum 'yarn.lock' }}"
           paths: [".yarn/cache/"]
-
-  # Deploy and NPM publish releases
-  - label: ":rocket: [Browser] Release Production"
-    depends_on: [build]
-    branches: "v*"
-    agents:
-      queue: v1
-    commands:
-      - npm config set "//registry.npmjs.org/:_authToken" $${NPM_TOKEN}
-      - yarn install --immutable
-      - yarn workspace @segment/analytics-next exec make build-prod
-      - NODE_ENV=production RELEASE=true yarn workspace @segment/analytics-next exec bash ./scripts/release.sh
-      - yarn workspace @segment/analytics-next exec npm publish
-    plugins:
-      - ssh://git@github.com/segmentio/cache-buildkite-plugin#v2.0.0:
-          key: "v1.1-cache-dev-{{ checksum 'yarn.lock' }}"
-          paths: [".yarn/cache/"]
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@1.6.0/schema.json",
+  "ignore": ["standalone-playground", "with-next-js", "with-vite"],
+  "changelog": [
+    "@changesets/changelog-github",
+    {
+      "repo": "segmentio/analytics-next"
+    }
+  ],
+  "commit": false,
+  "access": "restricted",
+  "baseBranch": "master",
+  "linked": []
+}
diff --git a/.github/PULL_REQUEST_TEMPLATE b/.github/PULL_REQUEST_TEMPLATE
@@ -1,9 +1,12 @@
 <!---
 
 Hello! And thanks for contributing to the Analytics-Next 🎉
-
-Please add a description of your PR, including the what and why
+- Please add:
+  - a description of your PR, including the what and why
+  - a changeset (if applicable)
 
 Also make sure to describe how you tested this change, include any gifs or screenshots you find necessary.
-
 --->
+
+
+[] I've included a changeset (psst. run `yarn changeset`. Read about changesets [here](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md)).
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - master
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+
+      - name: Setup Node.js 12.x
+        uses: actions/setup-node@v2
+        with:
+          node-version: 12.x
+          cache: "yarn"
+
+      - name: Install Dependencies
+        run: HUSKY=0 yarn install --immutable
+
+      - name: Create Release Pull Request or Publish to npm
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: yarn update-versions-and-changelogs
+          publish: yarn release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -27,3 +27,5 @@ reports/*
 # ignore archives
 *.tgz
 *.gz
+
+.changelog
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,8 +6,10 @@ Thanks for taking the time to contribute to analytics-next!
 
 This is a list of guidelines to follow to help expedite your pull request so we can get it reviewed/merged more quickly:
 
+- Include a changeset by running `yarn changeset` and following the prompts. Read: [An introduction to using changesets](https://github.com/changesets/changesets/blob/main/docs/intro-to-using-changesets.md). (*Note: changesets are only for changes that would merit a package bump, not for internal or cosmetic improvements.*)
 - Make sure existing unit tests and CI are all passing
 - Write new unit tests for the code you're contributing
 - A major goal of analytics-next is to keep bundle sizes low. Avoid redundancy and use efficient/modern javascript where possible
-- Changes must be compatible with major browsers (including IE 11)
+- Changes must be compatible with major browsers
 - Document your testing process, include screenshots when appropriate
+
diff --git a/RELEASING.md b/RELEASING.md
@@ -1,14 +1,67 @@
 ## Releasing
 
-### Feature branches
+This repo makes use of the [changesets](https://github.com/changesets/changesets) package to manage changelog generation, and publishing, and pushing appropriate github tags.
+## What is a `changeset`?
+> "A changeset is an intent to release a set of packages at particular semver bump types with a summary of the changes made."
 
-Feature branches are automatically released under:
+Read: [An introduction to using changesets](https://github.com/changesets/changesets/blob/main/docs/intro-to-using-changesets.md).
 
-- `http://cdn.segment.com/analytics-next/br/<branch>/<latest|sha>/standalone.js.gz`
 
-### Production
 
-Once you have tested your changes and they have been approved for a new release, merge your pull request and follow the steps:
 
-- `make release`
-  > creates a release tag that is then compiled and published in CI
+
+To see what changes are going into the next release, run:
+```
+yarn changeset info
+```
+To test what the changelog will look like beforehand (locally), you can run:
+```bash
+export GITHUB_TOKEN="???"
+yarn changeset version
+```
+(see https://github.com/settings/tokens)
+
+Once you have tested your changes and they have been approved for a new release, merge the changeset pull request into master.
+
+
+
+## How releasing works
+1. As PRs are merged into master, we use a [special GitHub action](https://github.com/changesets/action) to updates the package versions and changelogs, automatically creating a `Versions Packages` PR.
+2. Once we're ready to publish a new release, we can look at the `Version Packages` PR. If we like the way the Changelog looks, we can merge it in right there. If we want to edit the generated changelog, we can edit the changelog directly on that PR and then merge. If we aren't ready to merge things in and we want to add more detail to a changeset, we can always edit the changeset in .changesets/* and merge those in. Changesets are just text files, and are meant to be human-editable.
+
+### Releasing is handled for us by the [Release GitHub Action](/.github/workflows/release.yml).
+
+As PRs are opened against `master`, this action will open and update a PR which generates the appropriate `CHANGELOG.md` entries and `package.json` version bumps.
+The generated PR has the title "Version Packages"
+
+Once ready for a release, approve the "Version Packages" PR and merge it into `master`.
+
+## FAQ
+
+### How do I publish packages to npm / create a new release?
+1. Merge the `Version Packages` PR.
+
+### What does merging in `Version Packages` PR do under the hood?
+Information is in the [@changesets automation instructions](https://github.com/changesets/changesets/blob/main/docs/automating-changesets.md#how-do-i-run-the-version-and-publish-commands)
+
+### How does the changeset bot and changeset github action work?
+[Check out the @changesets automation instructions](https://github.com/changesets/changesets/blob/main/docs/automating-changesets.md#automating-changesets)
+
+
+### I don't want to use automation, how do I manually create a release?
+
+```bash
+export GITHUB_TOKEN="???" ## changelog generator requirement (https://github.com/settings/tokens)
+
+yarn update-versions-and-changelogs && ## bump +  generate changelog + delete old changesets
+git add . && # add generated artifacts
+git commit -m "v1.X.X" &&
+yarn release && ### run prepublish scripts + publish all packages to npm
+git push --follow-tags ### push generated tags to git (e.g @segment/analytics-next@1.X.X)
+```
+
+### Feature branches
+
+Feature branches are automatically released under:
+
+- `http://cdn.segment.com/analytics-next/br/<branch>/<latest|sha>/standalone.js.gz`
diff --git a/package.json b/package.json
@@ -14,10 +14,17 @@
     "lint": "echo 'Linting all workspaces...' && yarn constraints && yarn workspaces foreach -p run lint",
     "build:dev": "yarn workspace @segment/analytics-next build:dev",
     "dev": "yarn workspace @segment/analytics-next exec make dev",
-    "postinstall": "husky install"
+    "postinstall": "husky install",
+    "changeset": "changeset",
+    "update-versions-and-changelogs": "changeset version && yarn version-run-all",
+    "release": "yarn prepublish-run-all && changeset publish && git push --follow-tags",
+    "prepublish-run-all": "yarn workspaces foreach -pt --no-private run prepublish",
+    "version-run-all": "yarn workspaces foreach -pt --no-private run version"
   },
   "packageManager": "yarn@3.2.1",
   "devDependencies": {
+    "@changesets/changelog-github": "^0.4.5",
+    "@changesets/cli": "^2.23.0",
     "@types/jest": "^28.1.1",
     "@typescript-eslint/eslint-plugin": "^5.21.0",
     "@typescript-eslint/parser": "^5.21.0",
@@ -33,5 +40,9 @@
     "ts-jest": "^28.0.4",
     "ts-node": "^10.8.0",
     "typescript": "^4.6.4"
+  },
+  "resolutions": {
+    "@segment/analytics-next": "workspace:*",
+    "@segment/analytics-node": "workspace:*"
   }
 }
diff --git a/packages/browser/Makefile b/packages/browser/Makefile
@@ -73,16 +73,6 @@ size: ## Verify the final size of Analytics-Next
 	NODE_ENV=production $(yarn_run) umd > /dev/null && $(yarn_run) size-limit
 .PHONY: size
 
-release: ## Releases Analytics Next to stage
-	$(yarn_run) np --yolo --no-publish --no-release-draft
-.PHONY: release
-
-release-manual: ## Releases Analytics Next to production
-	make build-prod
-	NODE_ENV=production aws-okta exec plat-write -- ./scripts/release.js
-	npm publish
-.PHONY: release-prod-manual
-
 handshake:
 	@echo "📡  Establishing Remote connection"
 	@robo --config ~/dev/src/github.com/segmentio/robofiles/development/robo.yml prod.ssh echo "✅ Connected"
diff --git a/packages/browser/package.json b/packages/browser/package.json
@@ -23,14 +23,16 @@
   "sideEffects": false,
   "scripts": {
     "build-prep": "sh scripts/build-prep.sh",
-    "version": "npm run build-prep && git add src/generated/version.ts",
+    "version": "yarn run build-prep && git add src/generated/version.ts",
     "umd": "webpack",
     "eslint": "yarn run -T eslint",
     "tsc": "yarn run -T tsc",
     "jest": "yarn run -T jest",
     "concurrently": "yarn run -T concurrently",
     "build:dev": "yarn clean && yarn build-prep && yarn concurrently 'yarn umd' 'yarn pkg' 'yarn cjs'",
     "build:prod": "NODE_ENV=production yarn clean && yarn build-prep && yarn concurrently 'NODE_ENV=production yarn umd' 'NODE_ENV=production yarn pkg' 'NODE_ENV=production yarn cjs'",
+    "build": "yarn build:prod",
+    "prepublish": "echo 'running Prepublish build step...' && yarn build:prod && NODE_ENV=production RELEASE=true bash scripts/release.sh",
     "pkg": "yarn tsc -p tsconfig.build.json",
     "cjs": "yarn tsc -p tsconfig.build.json --outDir ./dist/cjs --module commonjs",
     "clean": "rm -rf dist",
@@ -85,7 +87,6 @@
     "micro-memoize": "^4.0.9",
     "mime": "^2.4.6",
     "node-gyp": "^9.0.0",
-    "np": "^7.6.1",
     "playwright": "^1.20.0",
     "serve-handler": "^6.1.3",
     "size-limit": "^7.0.8",
diff --git a/packages/node/package.json b/packages/node/package.json
@@ -23,6 +23,7 @@
     "build:esm": "yarn tsc -p tsconfig.build.json --outDir ./dist/esm --module esnext",
     "watch:build": "yarn concurrently 'yarn:build:cjs --watch --sourceMap' 'yarn:build:esm --watch --sourceMap'",
     "watch:test": "yarn test --watch",
+    "prepublish": "echo 'Prepublish script...\n' && yarn build",
     "tsc": "yarn run -T tsc",
     "eslint": "yarn run -T eslint",
     "concurrently": "yarn run -T concurrently",
diff --git a/yarn.lock b/yarn.lock
