From d94dd88405ce948d6297b3ebb55997abc0eef84e Mon Sep 17 00:00:00 2001 From: Dan Mosedale Date: Wed, 31 Jul 2019 11:41:23 -0700 Subject: [PATCH 1/5] Partial first cut at the inital doc; more to come --- docs/v2-system-addon/vendor.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/v2-system-addon/vendor.md diff --git a/docs/v2-system-addon/vendor.md b/docs/v2-system-addon/vendor.md new file mode 100644 index 0000000000..c8c2586aa3 --- /dev/null +++ b/docs/v2-system-addon/vendor.md @@ -0,0 +1,30 @@ +# Vendoring in npm libraries + +#### Build system basics + +#### Vendored libraries as externals + +#### Is this library a good candidate to depend on and vendor? + +#### How to vendor in a library + +* [ ] file a vendoring bug in Bugzilla + +* [ ] Get license approval from the licensing team + + [ ] review the mozilla-central policy at https://www.mozilla.org/en-US/MPL/license-policy/ + + [ ] file a license bug as described in the policy doc to request approval + + [ ] make it block the next upcoming export bug (if that bug is not already + + filed, file one) + + + [ ] post a patch to add the license to + + [ `toolkit/content/license.html` ](https://searchfox.org/mozilla-central/source/toolkit/content/license.html) + + + [ ] get the patch reviewed +* [ ] Install the package using npm + + [ ] Check that you're using npm 6.9.0 using `npm --version` + + [ ] Be sure to save the exact version by passing `--save-exact` to `npm install` + +* [ ] XXX more to come + From 6df7d01d7df5b4bf856cf442ba199cfeae60bb12 Mon Sep 17 00:00:00 2001 From: Dan Mosedale Date: Wed, 31 Jul 2019 13:55:17 -0700 Subject: [PATCH 2/5] Reformat and extend --- docs/v2-system-addon/vendor.md | 53 +++++++++++++++++++++------------- 1 file changed, 33 insertions(+), 20 deletions(-) diff --git a/docs/v2-system-addon/vendor.md b/docs/v2-system-addon/vendor.md index c8c2586aa3..fcb0f0078e 100644 --- a/docs/v2-system-addon/vendor.md +++ b/docs/v2-system-addon/vendor.md @@ -8,23 +8,36 @@ #### How to vendor in a library -* [ ] file a vendoring bug in Bugzilla - -* [ ] Get license approval from the licensing team - + [ ] review the mozilla-central policy at https://www.mozilla.org/en-US/MPL/license-policy/ - + [ ] file a license bug as described in the policy doc to request approval - + [ ] make it block the next upcoming export bug (if that bug is not already - - filed, file one) - - + [ ] post a patch to add the license to - - [ `toolkit/content/license.html` ](https://searchfox.org/mozilla-central/source/toolkit/content/license.html) - - + [ ] get the patch reviewed -* [ ] Install the package using npm - + [ ] Check that you're using npm 6.9.0 using `npm --version` - + [ ] Be sure to save the exact version by passing `--save-exact` to `npm install` - -* [ ] XXX more to come - +- [ ] file a bug for vendoring in the library itself + +- [ ] Get license approval from the licensing team + + - [ ] review the mozilla-central policy at + https://www.mozilla.org/en-US/MPL/license-policy/ + - [ ] file a license bug as described in the policy doc to request approval + - [ ] make it block the next upcoming export bug (if that bug is not already + filed, file one) + - [ ] post a patch to add the license to + [ `toolkit/content/license.html` ](https://searchfox.org/mozilla-central/source/toolkit/content/license.html) + - [ ] get the patch reviewed + - [ ] make sure that the patch gets landed at export time. + +- [ ] Install the package using npm + + - [ ] Check that you're using npm 6.9.0 with `npm --version` + - [ ] Be sure to save the exact version by passing `--save-exact` to + `npm install` + +- [ ] Include the vendored files and reference them + + - [ ] update [`bin/vendor.js`](../../bin/vendor.js) to copy any files + needed at runtime as well as the license to the [`vendor/` + directory](../../vendor/) + - [ ] execute `bin/vendor.js` to copy your files into place so they get committed + - [ ] Add the exported symbol for your library to the list of externals in + [`webpack.system-addon.config.js`](../../webpack.system-addon.config.js) so + that webpack knows where to link the symbol from + + - [ ] Add the library to the list of scripts in + [`bin/render-activity-stream-html.js`](../../bin/render-activity-stream.js) + so it gets loaded at runtime From 78322013197880b09bd6261edf5da44ed1a4ec17 Mon Sep 17 00:00:00 2001 From: Dan Mosedale Date: Wed, 31 Jul 2019 13:58:07 -0700 Subject: [PATCH 3/5] More cleanups --- docs/v2-system-addon/vendor.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/v2-system-addon/vendor.md b/docs/v2-system-addon/vendor.md index fcb0f0078e..2842b706df 100644 --- a/docs/v2-system-addon/vendor.md +++ b/docs/v2-system-addon/vendor.md @@ -33,11 +33,11 @@ - [ ] update [`bin/vendor.js`](../../bin/vendor.js) to copy any files needed at runtime as well as the license to the [`vendor/` directory](../../vendor/) - - [ ] execute `bin/vendor.js` to copy your files into place so they get committed + - [ ] execute `bin/vendor.js` to copy your files into place so they get + committed and referenced at runtime - [ ] Add the exported symbol for your library to the list of externals in - [`webpack.system-addon.config.js`](../../webpack.system-addon.config.js) so - that webpack knows where to link the symbol from - + [`webpack.system-addon.config.js`](../../webpack.system-addon.config.js) + so that webpack knows where to link the symbol from - [ ] Add the library to the list of scripts in - [`bin/render-activity-stream-html.js`](../../bin/render-activity-stream.js) + [`bin/render-activity-stream-html.js`](../../bin/render-activity-stream-html.js) so it gets loaded at runtime From 800649bc3fd7aef5f2098bf343772546c1007139 Mon Sep 17 00:00:00 2001 From: Dan Mosedale Date: Wed, 31 Jul 2019 13:58:54 -0700 Subject: [PATCH 4/5] Add testing step --- docs/v2-system-addon/vendor.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/v2-system-addon/vendor.md b/docs/v2-system-addon/vendor.md index 2842b706df..85380aea32 100644 --- a/docs/v2-system-addon/vendor.md +++ b/docs/v2-system-addon/vendor.md @@ -41,3 +41,4 @@ - [ ] Add the library to the list of scripts in [`bin/render-activity-stream-html.js`](../../bin/render-activity-stream-html.js) so it gets loaded at runtime + - [ ] test and make sure that everything builds and works at runtime From 7b7f4433b078f6b5144952412572fb72b9204a8e Mon Sep 17 00:00:00 2001 From: Dan Mosedale Date: Thu, 1 Aug 2019 16:42:40 -0700 Subject: [PATCH 5/5] Add missing steps; clarify; clean up --- docs/v2-system-addon/vendor.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/v2-system-addon/vendor.md b/docs/v2-system-addon/vendor.md index 85380aea32..0aa7a57b14 100644 --- a/docs/v2-system-addon/vendor.md +++ b/docs/v2-system-addon/vendor.md @@ -8,7 +8,8 @@ #### How to vendor in a library -- [ ] file a bug for vendoring in the library itself +- [ ] file a bug for vendoring in the library itself so that there's + an easy-to-find audit trail in Bugzilla, should it be needed - [ ] Get license approval from the licensing team @@ -35,10 +36,16 @@ directory](../../vendor/) - [ ] execute `bin/vendor.js` to copy your files into place so they get committed and referenced at runtime - - [ ] Add the exported symbol for your library to the list of externals in + - [ ] add the exported symbol (the library's global name) for your library + to the list of externals in [`webpack.system-addon.config.js`](../../webpack.system-addon.config.js) so that webpack knows where to link the symbol from - - [ ] Add the library to the list of scripts in + - [ ] add the library to the list of scripts in [`bin/render-activity-stream-html.js`](../../bin/render-activity-stream-html.js) so it gets loaded at runtime + - [ ] add the library to the list of scripts in + [`AboutNewTabService.jsm`](../../AboutNewTabService.jsm) so that it gets + preloaded for better browser startup performance + - [ ] add the library to [`jar.mn`](../../jar.mn) so that it gets + packaged into released builds - [ ] test and make sure that everything builds and works at runtime