search

cucumber / vscode

Official Visual Studio Code Extension for Cucumber
MIT License
61 stars 16 forks source link

Optimise bundling to reduce extension size #195

Closed kieran-ryan closed 6 months ago

kieran-ryan commented 6 months ago

🤔 What's changed?

⚡️ What's your motivation?

Removes need to bundle documentation images - which are not used by the extension itself; and the GitHub URLs are the links used when we visit the extension in the marketplace, so packaging them is redundant.

Reduces extension size from 15,696,312 bytes to 1,038,033 bytes - a 93.4% decrease. Closes #194.

Changing to a bundle whitelisting strategy means not having to update the ignore file every time there are new directories or files included throughout the repository; and is less susceptible to inadvertently introducing unexpected artefacts.

Existing bundle:

cucumber-official-1.8.0/
├─ [Content_Types].xml
├─ extension.vsixmanifest
├─ extension/
│  ├─ ..HEAD
│  ├─ CHANGELOG.md
│  ├─ LICENSE.txt
│  ├─ README.md
│  ├─ RELEASING.md
│  ├─ language-configuration.json
│  ├─ package.json
│  ├─ .github/
│  │  ├─ renovate.json
│  │  ├─ workflows/
│  │  │  ├─ build.yaml
│  │  │  ├─ release-github.yml
│  │  │  ├─ release-marketplace.yaml
│  ├─ doc/
│  │  ├─ contributing/
│  │  │  ├─ vscode-output.png
│  ├─ images/
│  │  ├─ autocomplete.gif
│  │  ├─ document-outline.gif
│  │  ├─ formatting.gif
│  │  ├─ generate-step-definition.gif
│  │  ├─ goto-step-definition.gif
│  │  ├─ icon-128x128.png
│  │  ├─ icon-512x512.png
│  │  ├─ syntax-highlighting.gif
│  ├─ out/
│  │  ├─ c_sharp.wasm
│  │  ├─ extension.js
│  │  ├─ java.wasm
│  │  ├─ php.wasm
│  │  ├─ python.wasm
│  │  ├─ ruby.wasm
│  │  ├─ rust.wasm
│  │  ├─ tree-sitter.wasm
│  │  ├─ tsx.wasm
│  ├─ scripts/
│  │  ├─ update-settings-docs.sh
│  ├─ syntaxes/
│  │  ├─ gherkin-classic.tmLanguage

Optimised bundle:

cucumber-official-1.8.0/
├─ [Content_Types].xml
├─ extension.vsixmanifest
├─ extension/
│  ├─ CHANGELOG.md
│  ├─ LICENSE.txt
│  ├─ README.md
│  ├─ language-configuration.json
│  ├─ package.json
│  ├─ images/
│  │  ├─ icon.png
│  ├─ out/
│  │  ├─ c_sharp.wasm
│  │  ├─ extension.js
│  │  ├─ java.wasm
│  │  ├─ php.wasm
│  │  ├─ python.wasm
│  │  ├─ ruby.wasm
│  │  ├─ rust.wasm
│  │  ├─ tree-sitter.wasm
│  │  ├─ tsx.wasm
│  ├─ syntaxes/
│  │  ├─ gherkin-classic.tmLanguage

🏷️ What kind of change is this?

♻️ Anything particular you want feedback on?

📋 Checklist:

kieran-ryan commented 6 months ago

Summary

I think in essence it's a question of: "Do we want to store documentation images in git?" - which is probably a point of preference.

My answer to that question would have been 'no' as they are not necessarily part of the extension, however looking at Microsoft-developed extensions - storing them within git appears to be their in-house convention - so I have no problem adhering to that.

With that in mind, shall I proceed to revert the images to the repository, link their GitHub CDN references on the raw subdomain, and exclude them from the bundle? Will give the desired outcome of optimising the bundle size.

Detail

Solution wise, looking at plugins published by MS, they link to to https://raw.githubusercontent.com. That seems a reasonable way to go. I suppose you would then exclude the images from being bundled with VSCode.

https://marketplace.visualstudio.com/items?itemName=ms-python.python

And see: https://raw.githubusercontent.com/microsoft/vscode-python/main/README.md

Yes, the two distinct approaches to prevent including the images in the bundle appear to be either:

  1. Commit images to git, and then reference them via the raw subdomain (raw.githubusercontent.com) rather than their relative path. In the example, this is via the main branch

    <img src=https://raw.githubusercontent.com/microsoft/vscode-python/main/images/OpenOrCreateNotebook.gif width=1029 height=602>

    From the Cucumber Extension in the marketplace, if you open an image in a new tab, you will observe that it currently uses this domain - thus, including the images in the bundle is redundant.

    Storing image binaries in git repositories that do not relate to the software can have its own challenges, though is a divisive and opinionated topic.

  2. The other option is to create a static link for them in the GitHub CDN for that project. This can be done by opening the project in GitHub and either copying the image into an Issue or the web editor - GitHub will create the links for you.

    ![Using the "Quick Fix" action to fix a violation](https://user-images.githubusercontent.com/1309177/205176932-44cfc03a-120f-4bad-b710-612bdd7765d6.gif)

Examples

Extensions storing images in git

Extensions storing images

mpkorstanje commented 6 months ago

With that in mind, shall I proceed to revert the images to the repository, link their GitHub CDN references on the raw subdomain, and exclude them from the bundle?

Okay. Please use tbe raw subdomain.

It has two advantages

mpkorstanje commented 6 months ago

@kieran-ryan I think your force push messed things up a bit.

kieran-ryan commented 6 months ago

@mpkorstanje updated now. Have additionally provided a before and after of the directory structure in the PR description; and changed to a whitelisting strategy for including files in the bundle - which should be less susceptible to introducing redundant artifacts.