git.iko.soy/elk
on master help sign in
Merge pull request #1749 from BrianHicks/npm-installers-for-0.19
3306537Evan Czaplicki
installers/npm/PUBLISHING.mdnew file+171
compare with master
unifiedsplit
@@ -0,0 +1,171 @@
1+# Publishing a new release
2+
3+A new version of Elm came out. Huzzah! Here's how to update the `npm` installer.
4+
5+## 1. Create tarballs of binaries
6+
7+You can find a list of what binaries we'll need to tar up in `index.js`.
8+
9+For example:
10+
11+```javascript
12+var root =
13+ "https://github.com/elm/compiler/releases/download/" +
14+ binVersion +
15+ "/binaries-for-";
16+
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:
29+
30+1. `binaries-for-mac.tar.gz`
31+2. `binaries-for-windows.tar.gz`
32+3. `binaries-for-linux.tar.gz`
33+
34+Each of these tarballs should have **only the Elm binary** inside them - no
35+directories!
36+
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:
39+
40+```shell
41+$ tar cvzf binaries-for-linux.tar.gz elm
42+```
43+
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:
80+
81+```shell
82+$ git tag 0.19.0
83+$ git push origin 0.19.0
84+```
85+
86+Now this tag should exist on GitHub, allowing us to upload binaries to it.
87+
88+## 5. Upload binaries
89+
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.
94+
95+Upload the tarballs you created in step 1.
96+
97+## 6. Publish beta release
98+
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
106+```
107+
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+```
114+
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.
119+
120+## 7. Verify beta installer
121+
122+Make an empty directory and run `npm init` inside it.
123+
124+Then run this:
125+
126+```shell
127+$ npm install elm@beta --ignore-scripts
128+```
129+
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`
163+
164+You're done! Now whenever anyone does `npm install -g elm` they'll get the
165+version you just uploaded.
166+
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.
installers/npm/UPLOADING.mddeleted−8
@@ -1,8 +0,0 @@
1−## Uploading new binaries
2−
3−1. Assemble a `.tar.gz` file for each desired operating system/architecture combination desired. Each tarball should contain a directory (e.g. `Elm-Platform-0.15`, although the directory name does not matter) whose contents are the binaries like `elm-make` for the appropriate environment. The tarballs must benamed according to this format: `(`[`process.platform`](https://nodejs.org/api/process.html#process_process_platform)` + "-" + `[`process.arch`](https://nodejs.org/api/process.html#process_process_arch)` + ".tar.gz")` - e.g. for 64-bit OS X, `darwin-x64.tar.gz`.
4−2. Sign into [the elm-platform npm binaries repo](https://bintray.com/elmlang/elm-platform/npm), select the appropriate version, and click Upload
5−3. Enter the version number (e.g. `0.15.1`) under **Target Repository Path**.
6−4. Click **Upload Files** and select the `.tar.gz` files from earlier. (You can multi-select in the dialog.)
7−5. Once everything is done uploading, hit **Save Changes**. You should now see each of the files listed at the bottom of the page, along with an auto-generated `.asc` file which contains a PGP signature so people can verify the files were downloaded correctly.
8−6. If everything looks right, hit **Publish** to make them available for download.
installers/npm/bin/elmnew file+33
@@ -0,0 +1,33 @@
1+#!/usr/bin/env node
2+
3+// This file exists for the benefit of npm users who have --ignore-scripts
4+// enabled. (Enabling this flag globally is a good security measure.)
5+// Since they won't run the post-install hook, the binaries won't be downloaded
6+// and installed.
7+//
8+// Since this file is included in "bin" in package.json, npm will install
9+// it automatically in a place that should be on the PATH. All the file does
10+// is to download the appropriate binary (just like the post-install hook would
11+// have), replace this file with that binary, and run the binary.
12+//
13+// In this way, the first time a user with --ignore-scripts enabled runs this
14+// binary, it will download and install itself, and then run as normal. From
15+// then on, it will run as normal without re-downloading.
16+
17+var install = require("..").install;
18+var spawn = require("child_process").spawn;
19+var path = require("path");
20+var fs = require("fs");
21+
22+// Make sure we get the right path even if we're executing from the symlinked
23+// node_modules/.bin/ executable
24+var targetPath = fs.realpathSync(process.argv[1]);
25+
26+// cd into the directory above bin/ so install() puts bin/ in the right place.
27+process.chdir(path.join(path.dirname(targetPath), ".."));
28+
29+install(process.platform, process.arch).then(function() {
30+ spawn(targetPath, process.argv.slice(2), {
31+ stdio: "inherit"
32+ }).on("exit", process.exit);
33+});
installers/npm/binaries/elmdeleted−1
@@ -1 +0,0 @@
1−echo "The npm installation of Elm did not complete successfully! Please try reinstalling Elm through npm. If you still see this message even after reinstalling, please file a bug at https://github.com/elm-lang/elm-platform/issues to let us know. You can find manual installers at http://elm-lang.org/install"
installers/npm/binaries/elm-makedeleted−1
@@ -1 +0,0 @@
1−echo "The npm installation of Elm did not complete successfully! Please try reinstalling Elm through npm. If you still see this message even after reinstalling, please file a bug at https://github.com/elm-lang/elm-platform/issues to let us know. You can find manual installers at http://elm-lang.org/install"
installers/npm/binaries/elm-packagedeleted−1
@@ -1 +0,0 @@
1−echo "The npm installation of Elm did not complete successfully! Please try reinstalling Elm through npm. If you still see this message even after reinstalling, please file a bug at https://github.com/elm-lang/elm-platform/issues to let us know. You can find manual installers at http://elm-lang.org/install"
installers/npm/binaries/elm-reactordeleted−1
@@ -1 +0,0 @@
1−echo "The npm installation of Elm did not complete successfully! Please try reinstalling Elm through npm. If you still see this message even after reinstalling, please file a bug at https://github.com/elm-lang/elm-platform/issues to let us know. You can find manual installers at http://elm-lang.org/install"
installers/npm/binaries/elm-repldeleted−1
@@ -1 +0,0 @@
1−echo "The npm installation of Elm did not complete successfully! Please try reinstalling Elm through npm. If you still see this message even after reinstalling, please file a bug at https://github.com/elm-lang/elm-platform/issues to let us know. You can find manual installers at http://elm-lang.org/install"
installers/npm/index.jsnew file+21
@@ -0,0 +1,21 @@
1+var binwrap = require("binwrap");
2+var path = require("path");
3+
4+var packageInfo = require(path.join(__dirname, "package.json"));
5+// Use major.minor.patch from version string - e.g. "1.2.3" from "1.2.3-alpha"
6+var binVersion = packageInfo.version.replace(/^(\d+\.\d+\.\d+).*$/, "$1");
7+
8+var root =
9+ "https://github.com/elm/compiler/releases/download/" +
10+ binVersion +
11+ "/binaries-for-";
12+
13+module.exports = binwrap({
14+ binaries: ["elm"],
15+ urls: {
16+ "darwin-x64": root + "mac.tar.gz",
17+ "win32-x64": root + "windows.tar.gz",
18+ "win32-ia32": root + "windows.tar.gz",
19+ "linux-x64": root + "linux.tar.gz"
20+ }
21+});
installers/npm/install.jsdeleted−34
@@ -1,34 +0,0 @@
1−var binstall = require("binstall");
2−var path = require("path");
3−var fs = require("fs");
4−var packageInfo = require(path.join(__dirname, "package.json"));
5−
6−// Use major.minor.patch from version string - e.g. "1.2.3" from "1.2.3-alpha"
7−var binVersion = packageInfo.version.replace(/^(\d+\.\d+\.\d+).*$/, "$1");
8−
9−// 'arm', 'ia32', or 'x64'.
10−var arch = process.arch;
11−
12−// 'darwin', 'freebsd', 'linux', 'sunos' or 'win32'
13−var operatingSystem = process.platform;
14−
15−var filename = operatingSystem + "-" + arch + ".tar.gz";
16−var url = "https://dl.bintray.com/elmlang/elm-platform/"
17− + binVersion + "/" + filename;
18−
19−var binariesDir = path.join(__dirname, "binaries");
20−var packageInfo = require(path.join(__dirname, "package.json"));
21−var binaryExtension = process.platform === "win32" ? ".exe" : "";
22−var executablePaths = Object.keys(packageInfo.bin).map(function(executable) {
23− return path.join(binariesDir, executable + binaryExtension);
24−});
25−var errorMessage = "Unfortunately, there are no Elm Platform " + binVersion + " binaries available for your operating system and architecture.\n\nIf you would like to build Elm from source, there are instructions at https://github.com/elm-lang/elm-platform#build-from-source\n";
26−
27−binstall(url, {path: binariesDir, strip: 1},
28− {verbose: true, verify: executablePaths, errorMessage: errorMessage}
29−).then(function(successMessage) {
30− console.log(successMessage);
31− }, function(errorMessage) {
32− console.error(errorMessage);
33− process.exit(1);
34− });
installers/npm/package.json+12−18
@@ -1,15 +1,16 @@
1{
1{
2 "name": "elm",
2 "name": "elm",
3− "version": "0.18.0",
3+ "version": "0.19.0",
4 "description": "The Elm Platform: Binaries for the Elm programming language.",
4 "description": "The Elm Platform: Binaries for the Elm programming language.",
5+ "main": "index.js",
5 "preferGlobal": true,
6 "preferGlobal": true,
6 "license": "BSD-3-Clause",
7 "license": "BSD-3-Clause",
7 "repository": {
8 "repository": {
8 "type": "git",
9 "type": "git",
9− "url": "https://github.com/elm-lang/elm-platform.git"
10+ "url": "https://github.com/elm/compiler.git"
10 },
11 },
11− "homepage": "https://github.com/elm-lang/elm-platform/tree/master/installers/npm",
12+ "homepage": "https://github.com/elm/compiler/tree/master/installers/npm",
12− "bugs": "https://github.com/elm-lang/elm-platform/issues",
13+ "bugs": "https://github.com/elm/compiler/issues",
13 "author": {
14 "author": {
14 "name": "Richard Feldman",
15 "name": "Richard Feldman",
15 "email": "richard.t.feldman@gmail.com",
16 "email": "richard.t.feldman@gmail.com",
@@ -19,32 +20,25 @@
19 "node": ">=4.0.0"
20 "node": ">=4.0.0"
20 },
21 },
21 "scripts": {
22 "scripts": {
22− "install": "node install.js"
23+ "install": "binwrap-install",
24+ "prepublishOnly": "binwrap-test"
23 },
25 },
24 "files": [
26 "files": [
25− "install.js",
27+ "index.js",
26− "binaries"
28+ "bin",
29+ "bin/elm"
27 ],
30 ],
28 "keywords": [
31 "keywords": [
29 "bin",
32 "bin",
30 "binary",
33 "binary",
31 "binaries",
34 "binaries",
32 "elm",
35 "elm",
33− "elm-make",
34− "elm-package",
35− "elm-platform",
36− "elm-reactor",
37− "elm-repl",
38 "platform"
36 "platform"
39 ],
37 ],
40 "bin": {
38 "bin": {
41− "elm": "binaries/elm",
39+ "elm": "bin/elm"
42− "elm-make": "binaries/elm-make",
43− "elm-package": "binaries/elm-package",
44− "elm-reactor": "binaries/elm-reactor",
45− "elm-repl": "binaries/elm-repl"
46 },
40 },
47 "dependencies": {
41 "dependencies": {
48− "binstall": "1.2.0"
42+ "binwrap": "0.1.4"
49 }
43 }
50}
44}