1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
|
# Runbook
This documents some maintenance tasks for esbuild so I don't forget how they
work. There are a lot of moving parts now that esbuild uses trusted publishing.
## Publishing a release
Publishing a release is now done by using GitHub Actions as a
[trusted publisher](https://docs.npmjs.com/trusted-publishers).
To publish a new release:
1. Update the version in [`version.txt`](./version.txt). Only include the number. Do not include a leading `v`.
2. Copy that version verbatim (without the leading `v`) to a `##` header in [`CHANGELOG.md`](./CHANGELOG.md). This usually replaces the `## Unreleased` header used for unreleased changes.
3. Run `make platform-all` to update the version number in all `package.json` files. The publishing workflow will fail without this step.
4. Commit and push using a message such as `publish 0.X.Y to npm`. This should trigger the publishing workflow described below.
Pushing a change to [`version.txt`](./version.txt) causes the following:
- The [`publish.yml`](./.github/workflows/publish.yml) workflow in this repo
will be triggered, which will:
1. Build and publish all npm packages to npm using trusted publishing
2. Create a tag for the release that looks like `v0.X.Y`
3. Publish a [GitHub Release](https://github.com/evanw/esbuild/releases) containing the release notes in [`CHANGELOG.md`](./CHANGELOG.md)
- The [`release.yml`](https://github.com/esbuild/deno-esbuild/blob/main/.github/workflows/release.yml)
workflow in the https://github.com/esbuild/deno-esbuild repo runs
occasionally. On the next run, it will notice the version change and:
1. Clone this repo
2. Run `make platform-deno`
3. Commit and push the new contents of the `deno` folder to the `deno-esbuild` repo
4. Create a tag for the release that looks like `v0.X.Y`
5. Post an event to the https://api.deno.land/webhook/gh/esbuild webhook
6. Deno will then add a new version to https://deno.land/x/esbuild
You can also manually trigger this workflow if you want it to happen immediately.
- The [`release.yml`](https://github.com/esbuild/esbuild.github.io/blob/main/.github/workflows/release.yml)
workflow in the https://github.com/esbuild/esbuild.github.io repo runs
occasionally. On the next run, it will notice the version change and:
1. Create a new `dl/v0.X.Y` script for the new version number
2. Update the `dl/latest` script with the new version number
3. Commit and push these new scripts to the `gh-pages` branch of the `esbuild.github.io` repo
4. GitHub Pages will then deploy these updates to https://esbuild.github.io/
You can also manually trigger this workflow if you want it to happen immediately.
## Adding a new package
Each platform (operating system + architecture) needs a separate optional npm
package due to how esbuild's installer works. New packages should be created
under the `@esbuild/` scope so it's obvious that they are official.
Create a directory for the new package inside the [`npm/@esbuild`](./npm/@esbuild/)
directory. Then modify the rest of the repo to reference the new package. The
specifics for what to modify depends on the platform, but a good place to
start is to search for the name of a similar existing package and see where
it's used.
In addition, you'll need to prepare that package for the next release. To do
that:
1. Create an empty package with the expected name and a version of 0.0.1
2. Publish it with `npm publish --access public` (note that scoped packages are private by default)
3. Log in to the npm website and go to the package settings
4. Ensure that the only maintainer is the [esbuild](https://www.npmjs.com/~esbuild) user
5. Add the GitHub repo as the trusted publisher:
- **Organization or user:** `evanw`
- **Repository:** `esbuild`
- **Workflow filename:** `publish.yml`
6. Ensure publishing access is set to **Require two-factor authentication and disallow tokens (recommended)**
|
