Optimise bundling to reduce extension size

[kieran-ryan]

🤔 What's changed?

• Migrated documentation image links to use their GitHub URLs
• Changed bundle ignore file to a whitelisting strategy (as mentioned by maintainers of the VSCode Extension Manager) and used by Microsoft/vscode-mono-debug
• Changed to the larger logo

⚡️ 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?

• 🏦 Refactoring/debt/DX (improvement to code design, tooling, documentation etc. without changing behaviour)

♻️ Anything particular you want feedback on?

• Whether there is any opportunity to optimise the Cucumber logo - currently 33KB. SVG images are not accepted.
• Whether the provided GitHub CDN URLs are acceptable or need to be defined at a different GitHub CDN domain.

📋 Checklist:

• I agree to respect and uphold the Cucumber Community Code of Conduct
• Users should know about my change
  • I have added an entry to the "Unreleased" section of the CHANGELOG, linking to this pull request.

[mpkorstanje]

I don't understand this PR.

The images are pulled from a CDN and at the same time removed from the repository. I presume that the repository is what ultimately backs the CDN, so I would expect that removing the images from Github won't actually work?

[mpkorstanje]

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

[kieran-ryan]

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

• Microsoft extensions, however there are some exceptions (see below)
• Precommit Helper
• etc.

Extensions storing images

• Ruff - astral - November 2022
• Live Share - microsoft - created January 2018
• Remote Development - microsoft - created May 2019
• Makefile Tools - microsoft - created Februrary 2021
• etc.

[mpkorstanje]

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

• It keeps everything in version control and available. Once the CDN is used, the origin image is "gone".
• The raw domain uses the actual path to the file. This makes it possible for people to find the resource.

[mpkorstanje]

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

[kieran-ryan]

@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.

[mpkorstanje]

LGTM.

A minor quibble, but fixing that doesn't need a whole review cycle

[mpkorstanje]

This seems overly cautious. The entire out folder is expected to go into the plugin.

[kieran-ryan]

Agree. Main reason was to continue excluding ‘.map’ files (previous blacklist was ‘**/*.map’).

Perhaps a better strategy would be to whitelist ‘out’ and include an ‘exceptions’ section at the bottom of the ignore file to exclude ‘.map’ files. What do you think?

The discussion on excluding map files in the VSCode Python extension provides more context on reasons for this exclusion. Slowed the extension (at least previously), increased bundle size and only used for debugging to determine exact file and line number that threw an extension - which is not a present concern with this extension given it would apply to two files.