From 1c59ad457b90c29e26a0d6de92f66ea5f4caff45 Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Thu, 12 Jul 2018 14:15:15 -0400 Subject: [PATCH 1/5] Drafty draft --- docs/rfcs/xxx-pretranspile.md | 44 +++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 docs/rfcs/xxx-pretranspile.md diff --git a/docs/rfcs/xxx-pretranspile.md b/docs/rfcs/xxx-pretranspile.md new file mode 100644 index 00000000000..c0e59970fdf --- /dev/null +++ b/docs/rfcs/xxx-pretranspile.md @@ -0,0 +1,44 @@ +# Pre-transpiled Atom packages + +## Status + +Proposed + +## Summary + +This feature will enable package authors to use conventional npm tooling and package.json conventions to take advantage of JavaScript transpilers like Babel or TypeScript. + +## Motivation + +Transpiling packages on _publish_ rather than _load_ will have great benefits for package authors: + +* Standard `npm` tooling like `prepare` scripts will work for apm packages exactly as they work for npm packages. This will remove the need for custom transpiler pipeline modules like [atom-babel6-transpiler](https://github.com/atom/atom-babel6-transpiler) or [atom-typescript-transpiler](https://github.com/smhxx/atom-ts-transpiler) with their own, independent documentation, configuration and setup. +* Packages can move transpiler-related dependencies to `devDependencies` and trim installation bloat substantially. (as a data point, the TypeScript compiler is 30MB.) +* First-time package load will no longer take a hit from transpiling all of the source into the cache. All package loads will benefit from no longer needing to check and side-load from the compiler cache. + +## Explanation + +### Package publishing + +During the `apm publish` call, apm will invoke [`npm pack`](https://docs.npmjs.com/cli/pack) to run all standard npm lifecycle hooks and prepare a `.tar.gz` file. apm then creates a release associated with the created tag and uploads the `.tar.gz` file as an attachment called `package.tar.gz`. + +### Package installation + +When a user installs a package from atom.io, atom.io first checks to see if its GitHub repository has a release corresponding to that tag with an artifact named `package.tar.gz`. If one is found, the artifact's URL is returned as the `dist` field in the [API response](https://flight-manual.atom.io/atom-server-side-apis/sections/atom-package-server-api/#get-apipackagespackage_nameversionsversion_name). Otherwise, the existing logic is used to return the GitHub tag tarball URL that's returned now. + +## Drawbacks + +Doing this makes installing a package in production more different than loading it during development. This increases the number of variables that can cause issues between local development and the production of an `apm publish` artifact, like tweaking your `.npmignore` file properly. + +## Rationale and alternatives + +_Alternative: publish packages to Actual Npm.org._ We could identify Atom packages in the npm registry by the `engine` field we already use, which should keep regular npm from installing it by mistake. The downsides here are: + +* It becomes harder to search for _just_ Atom packages; we'd have to hack npm search a bit. +* "Starring" would likely break. +* The transition path for existing users of apm and atom.io is not as smooth. +* Easier to typo `apm` and `npm` commands and have an undesirable outcome. + +## Unresolved questions + +Do we want to deprecate transpilation-on-demand for local development, as well? It may add a bit of friction for package development, but transpilers like TypeScript tend to offer a `--watch` option to transpile live, and it would let us eliminate a lot of complexity in the way Atom loads JavaScript. From 633180324a4c7fe3715ccee72b227edf7d2d9d59 Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Fri, 20 Jul 2018 11:43:11 -0400 Subject: [PATCH 2/5] Store artifacts in S3 --- docs/rfcs/xxx-pretranspile.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rfcs/xxx-pretranspile.md b/docs/rfcs/xxx-pretranspile.md index c0e59970fdf..3f3c8645d70 100644 --- a/docs/rfcs/xxx-pretranspile.md +++ b/docs/rfcs/xxx-pretranspile.md @@ -20,11 +20,11 @@ Transpiling packages on _publish_ rather than _load_ will have great benefits fo ### Package publishing -During the `apm publish` call, apm will invoke [`npm pack`](https://docs.npmjs.com/cli/pack) to run all standard npm lifecycle hooks and prepare a `.tar.gz` file. apm then creates a release associated with the created tag and uploads the `.tar.gz` file as an attachment called `package.tar.gz`. +During the `apm publish` call, apm will invoke [`npm pack`](https://docs.npmjs.com/cli/pack) to run all standard npm lifecycle hooks and prepare a `.tar.gz` file. apm then uploads the `.tar.gz` file to atom.io, which uploads it to an S3 bucket. ### Package installation -When a user installs a package from atom.io, atom.io first checks to see if its GitHub repository has a release corresponding to that tag with an artifact named `package.tar.gz`. If one is found, the artifact's URL is returned as the `dist` field in the [API response](https://flight-manual.atom.io/atom-server-side-apis/sections/atom-package-server-api/#get-apipackagespackage_nameversionsversion_name). Otherwise, the existing logic is used to return the GitHub tag tarball URL that's returned now. +When a user installs a package from atom.io, atom.io first checks to see if it has a precompiled tarball in its S3 bucket. If one is found, the artifact's public URL is returned as the `dist` field in the [API response](https://flight-manual.atom.io/atom-server-side-apis/sections/atom-package-server-api/#get-apipackagespackage_nameversionsversion_name). Otherwise, the existing logic is used to return the GitHub tag tarball URL that's returned now. ## Drawbacks From 444695174d08c69f528734e9ed37ae18536bee13 Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Fri, 20 Jul 2018 11:43:35 -0400 Subject: [PATCH 3/5] We won't actually be able to disable the compile cache entirely (sadface) --- docs/rfcs/xxx-pretranspile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rfcs/xxx-pretranspile.md b/docs/rfcs/xxx-pretranspile.md index 3f3c8645d70..901a55203c9 100644 --- a/docs/rfcs/xxx-pretranspile.md +++ b/docs/rfcs/xxx-pretranspile.md @@ -14,7 +14,7 @@ Transpiling packages on _publish_ rather than _load_ will have great benefits fo * Standard `npm` tooling like `prepare` scripts will work for apm packages exactly as they work for npm packages. This will remove the need for custom transpiler pipeline modules like [atom-babel6-transpiler](https://github.com/atom/atom-babel6-transpiler) or [atom-typescript-transpiler](https://github.com/smhxx/atom-ts-transpiler) with their own, independent documentation, configuration and setup. * Packages can move transpiler-related dependencies to `devDependencies` and trim installation bloat substantially. (as a data point, the TypeScript compiler is 30MB.) -* First-time package load will no longer take a hit from transpiling all of the source into the cache. All package loads will benefit from no longer needing to check and side-load from the compiler cache. +* First-time package load will no longer take a hit from transpiling all of the source into the cache. ## Explanation From af6da3d8db6186199f0d6fbfc0a4d1c540aeb4f2 Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Fri, 20 Jul 2018 11:46:55 -0400 Subject: [PATCH 4/5] Add a note about manual tagging --- docs/rfcs/xxx-pretranspile.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/rfcs/xxx-pretranspile.md b/docs/rfcs/xxx-pretranspile.md index 901a55203c9..cc6c1325180 100644 --- a/docs/rfcs/xxx-pretranspile.md +++ b/docs/rfcs/xxx-pretranspile.md @@ -22,6 +22,8 @@ Transpiling packages on _publish_ rather than _load_ will have great benefits fo During the `apm publish` call, apm will invoke [`npm pack`](https://docs.npmjs.com/cli/pack) to run all standard npm lifecycle hooks and prepare a `.tar.gz` file. apm then uploads the `.tar.gz` file to atom.io, which uploads it to an S3 bucket. +The `npm version` call will still be skipped if the `--tag` is provided, so manual publishing with `apm publish --tag` will still work as it does today. + ### Package installation When a user installs a package from atom.io, atom.io first checks to see if it has a precompiled tarball in its S3 bucket. If one is found, the artifact's public URL is returned as the `dist` field in the [API response](https://flight-manual.atom.io/atom-server-side-apis/sections/atom-package-server-api/#get-apipackagespackage_nameversionsversion_name). Otherwise, the existing logic is used to return the GitHub tag tarball URL that's returned now. From 0d13eabceac1fe06acf9f0524175face5955f397 Mon Sep 17 00:00:00 2001 From: sadick254 Date: Fri, 3 Sep 2021 09:24:25 +0300 Subject: [PATCH 5/5] Update RFC number --- docs/rfcs/{xxx-pretranspile.md => 005-pretranspile.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/rfcs/{xxx-pretranspile.md => 005-pretranspile.md} (100%) diff --git a/docs/rfcs/xxx-pretranspile.md b/docs/rfcs/005-pretranspile.md similarity index 100% rename from docs/rfcs/xxx-pretranspile.md rename to docs/rfcs/005-pretranspile.md