-
Notifications
You must be signed in to change notification settings - Fork 0
3.2 | Packaging and publishing
After running the build-production script, and building the extension, the next step is packaging. Packaging is the process of creating a .vsix file, which contains all the required resources.
A .vsix file uses a simple zip compression, so you can open it with any program that can handle zip compression. The tool that creates .vsix files is called vsce, and it's one of the project's dependencies, defined in the package.json file. When you create a new package, vsce decides which files to include, based on the content of a .vscodeignore file. The .vscodeignore files, similarly to .gitignore files define the files and folders you don't want to include, by using glob patterns. You don't want to include any files that are not required in runtime, for example, TypeScript files, the configurations for static analysis tools, etc. After the packaging, you can decide to publish the package to Visual Studio Marketplace, or just share the .vsix file directly. If you want to install the package manually, select the Extensions tab in VS Code, click on the Views and More Actions.. button (the 3 dots), and click on Install from VSIX....
You have to include package.json, the JavaScript files, the TextMate grammars, language-configuration.json, README.md, CHANGELOG.md, and parts of the res folder. The package might also contain the platform-specific executable of the language server, so that we don't force the user to install Node.js. Some of these files come from the language server, if you need more information, read the language server wiki pages. However, not all resources are included into all packages.
The VS Code extension ecosystem allows us to publish platform-specific packages of the same extension. This means that we can (and do) create platform-specific packages for Windows x64, Mac x64, Linux x64, and we have a universal one that works on all other platforms, including the web. The reason behind this is that the language server has platform-specific executable files (for example an .exe file for Windows x64). We could include all 3 executables into the package, but it would mean, that we need to include 2 unnecessary large files. Instead, we only include the Windows x64-specific executable into the Windows x64-specific package of the extension, and this is similarly true for the Mac x64 and Linux x64 versions of the extension.
You can create the packages with the package-universal, package-windows-x64, package-macos-x64, package-linux-x64, and the package-all scripts.
When I create a new release for the extension, I follow these steps:
-
I update the npm packages.
-
I update the CHANGELOG.md file, based on the commits since the last release.
-
I update the README.md file's Release notes section (a shorter version of the changelog), and all the other sections if necessary.
-
I update the year in LICENSE, if this is the first release in the current year.
-
I change the
versionof the extension in the package.json. When I add a whole new feature, I increment the minor version, but if the release only contains improvements and bug fixes, I increment the patch version. -
I build the extension in production mode, using the build-production script.
-
I package the extension for all targets using the package-all script.
-
I regenerate the PAT (Personal Access Token) in Azure DevOps if it's expired, and add the new one to GitHub secrets (Settings / Secrets and variables / Actions / Repository secrets / Update secret).
-
I create a commit with the name
Version <VERSION>, and push it to GitHub. It's important to commit and push before publishing because the README.md file's content (at the moment of publishing) will be the description of the extension in Visual Studio Marketplace. -
I create a new GitHub Release, where I copy the content from the CHANGELOG.md file, and upload the packages.
-
I publish the extension with the following command:
npx vsce publish --packagePath dagor-shader-language-support-<VERSION>.vsix dagor-shader-language-support-win32-x64-<VERSION>.vsix dagor-shader-language-support-linux-x64-<VERSION>.vsix dagor-shader-language-support-darwin-x64-<VERSION>.vsixIf you want to create a pre-release version, add the
--pre-releaseflag to the command.It can take a couple of minutes to see the new versions in the marketplace.
When you go to the management page of the extension, make sure to select the Gaijin directory, instead of the Gaijin Team, otherwise, you won't see the extensions.