@@ -1,171 +1,59 @@
1−# Publishing a new release
1+# Publishing
22
3−A new version of Elm came out. Huzzah! Here's how to update the `npm` installer.
3+Here's how to update the `npm` installer.
44
5−## 1. Create tarballs of binaries
65
7−You can find a list of what binaries we'll need to tar up in `index.js`.
6+## 1. GitHub Release
87
9−For example:
8+Create a [GitHub Release](https://github.com/elm/compiler/releases) with the following files:
109
11−```javascript
12−var root =
13− "https://github.com/elm/compiler/releases/download/" +
14− binVersion +
15− "/binaries-for-";
10+1. `binary-for-mac-64-bit.gz`
11+2. `binary-for-windows-64-bit.gz`
12+3. `binary-for-linux-64-bit.gz`
1613
17−module.exports = binwrap({
18− binaries: ["elm"],
19− urls: {
20− "darwin-x64": root + "mac.tar.gz",
21− "win32-x64": root + "windows.tar.gz",
22− "win32-ia32": root + "windows.tar.gz",
23− "linux-x64": root + "linux.tar.gz"
24− }
25−});
26−```
27−
28−If this is the end of your `index.js`, you'll need to create these files:
14+Create each of these by running the `elm` executable for each platform through `gzip elm`.
2915
30−1. `binaries-for-mac.tar.gz`
31−2. `binaries-for-windows.tar.gz`
32−3. `binaries-for-linux.tar.gz`
3316
34−Each of these tarballs should have **only the Elm binary** inside them - no
35−directories!
17+## 2. Try a beta release
3618
37−So create them by making a directory, putting all the binaries in it, `cd`-ing
38−into that directory, and then running something like this:
19+In `package.json`, bump the version to `"0.19.2-beta"`.
3920
40−```shell
41−$ tar cvzf binaries-for-linux.tar.gz elm
21+```bash
22+npm publish --tag beta
4223```
4324
44−Make sure each tarball contains all the binaries listed in that `binaries:` list
45−in `index.js`. (The Windows ones should have `.exe` at the end; `binwrap`
46−expects that they will, for Windows only.)
47−
48−## 2. Update the `bin/` binary wrappers
49−
50−Inside the npm installer's `bin/` directory, there should be a file for each of
51−the binaries that will be included in this release.
52−
53−Each of these must be executable! If you're not sure whether they are,
54−run `chmod +x` on them just to be sure.
55−
56−Their paths must also must all be listed in `package.json` in two places:
57−
58−1. The `"files":` field
59−2. The `"bin":` field
60−
61−If the executables are the same as they were for the last release, great!
62−You can proceed to the next step. If any binaries were removed, make sure to
63−remove them from these lists!
64−
65−## 3. Update `package.json` for a beta release
66−
67−In `package.json`, bump the version to the next applicable release, and add
68−a `"-beta"` suffix to it.
69−
70−For example, if it was on `"0.18.0"` you might bump it to `"0.19.0-beta"`.
71−The version number should match the release of Elm, such that if people do
72−`npm install elm@0.19.0@beta` they get what they would expect.
73−
74−## 4. Tag the beta release
75−
76−Commit this change and tag it with the name of the release **without** the
77−`-beta` suffix. (We will overwrite this tag later.)
78−
79−For example:
25+To test that it works, run these commands:
8026
81−```shell
82−$ git tag 0.19.0
83−$ git push origin 0.19.0
27+```bash
28+npm dist-tags ls elm
29+npm install elm@beta --ignore-scripts
8430```
8531
86−Now this tag should exist on GitHub, allowing us to upload binaries to it.
32+The `latest` tag should not be changed, and there should be an additional `beta` tag.
8733
88−## 5. Upload binaries
34+Try this on Windows, Linux, and Mac.
8935
90−Visit the [Create a New Release](https://github.com/elm-lang/elm-platform/releases/new)
91−page and use the `Tag version` dropdown to select the tag you just pushed. Give
92−it a title like `0.19.0`. Don't mention the `-beta` in it. The "beta" concept
93−is for `npm` only.
9436
95−Upload the tarballs you created in step 1.
37+## 3. Publish final release
9638
97−## 6. Publish beta release
39+Remove the `-beta` suffix from the version in `package.json`. Then run:
9840
99−Run this to publish the beta release. The `--tag beta` is **crucial** here.
100−Without it, `npm` will by default publish a new top-level release, which would
101−mean that what you just published would become what everyone gets when they
102−`npm install -g elm` without any additional qualifiers.
103−
104−```shell
105−$ npm publish --tag beta
41+```bash
42+npm publish
10643```
10744
108−Afterwards you should be able to do `npm info elm | less` and see something
109−like this in the JSON:
110−
111−```
112−'dist-tags': { latest: '0.18.0', beta: '0.19.0-beta' }
113−```
11445
115−If you messed this up, and the `latest` tag now points to the beta you just
116−published, don't panic - it's fixable! `dist-tags` can always be modified after
117−the fact. Read up on `npm` [dist-tags](https://docs.npmjs.com/cli/dist-tag)
118−to learn how to fix things.
46+## 4. Tag the `latest-0.19.1` version
11947
120−## 7. Verify beta installer
48+Many compiler releases have needed multiple `npm` publications. Maybe something does not work on Windows or some dependency becomes insecure. Normal `npm` problems.
12149
122−Make an empty directory and run `npm init` inside it.
50+The convention for each Elm release is to create a tag the latest one.
12351
124−Then run this:
125−
126−```shell
127−$ npm install elm@beta --ignore-scripts
52+```bash
53+npm dist-tag add elm@0.19.1-3 latest-0.19.1
12854```
12955
130−This should succeed with an exit code of `0`.
131−If it did, look in `node_modules/.bin/` for the binaries you expect.
132−They should be present, and they should also work as expected when you run them.
133−Because you installed them with `--ignore-scripts`, the first thing they should
134−do is to download themselves and then execute whatever command you requested
135−(e.g. `node_modules/.bin/elm make Main.elm`). If you run the same command a
136−second time, it should run faster because it doesn't have to download the binary
137−first.
138−
139−Now try it again with `--ignore-scripts` turned off:
140−
141−```shell
142−$ rm -r node_modules
143−$ npm install elm@beta --ignore-scripts=false
144−```
145−
146−This time it should download the binaries during the installation phase. Once
147−again you should be able to run the binaries from `node_modules/.bin/`, and
148−this time they should be fast from the first run because they're already
149−downloaded.
150−
151−## 8. Publish for real
152−
153−It's a good idea to ask others to try out the beta installer before doing this!
154−Especially on multiple operating systems.
155−
156−To publish the real version:
157−
158−1. Edit `package.json` to remove the `-beta` suffix from the version.
159−2. Commit that change and push it.
160−3. Use `git tag --force` to overwrite the previous tag (e.g. `0.19.0` - whatever you used before).
161−4. Force push the tag, e.g. `git push origin 0.19.0 --force-with-lease`.
162−5. `npm publish`
56+That way people who want a specific version can point to `latest-0.19.1` or `latest-0.18.0` instead of knowing the particular names of all the various publications.
16357
164−You're done! Now whenever anyone does `npm install -g elm` they'll get the
165−version you just uploaded.
58+You can read more about dist-tags [here](https://docs.npmjs.com/cli/dist-tag).
16659
167−The reason we only used the `-beta` suffix for `npm` was so that when we ran
168−tests on the beta version, it was all against the same (non-beta) URLs we'd end
169−up using for the real version. This means there's no opportunity for us to
170−introduce some sort of mismatch between the beta that we verified and the real
171−version.