Procedure to create releases for Theia

Publishing releases

The Theia cpp-debug extension located here requires the debug adapter to be built, zipped and uploaded somewhere. When the extension is yarn-installed, it fetches and decompresses the adapter.

The approach that was taken so far was to build the adapter (this repo) and upload the artifact as a release on Github. Here are the steps, roughly:

1. Make sure to start from a clean repository (git clean -xfd).
2. This would be a good time to make sure you are up to date with upstream. Make sure the master branch on this repo is up-to-date too. Make sure you don't have unexpected commits on top.
3. Build with yarn.
4. Pack the files: I use npm pack, because yarn pack gives me a strange error that I never had time to debug yet:

$ npm pack 
npm notice 
npm notice 📦  cdt-gdb-vscode@0.0.61
npm notice === Tarball Contents === 
npm notice 4.2kB   package.json       
npm notice 130B    .vscodeignore      
npm notice 14.2kB  LICENSE            
npm notice 742B    README.md          
npm notice 473B    tsconfig.json      
npm notice 175.3kB yarn.lock          
npm notice 619B    .vscode/launch.json
npm notice 379B    .vscode/tasks.json 
npm notice 1.1kB   src/extension.ts   
npm notice === Bundled Dependencies === 
npm notice cdt-gdb-adapter
npm notice === Tarball Details === 
npm notice name:          cdt-gdb-vscode                          
npm notice version:       0.0.61                                  
npm notice filename:      cdt-gdb-vscode-0.0.61.tgz               
npm notice package size:  185.9 kB                                
npm notice unpacked size: 685.6 kB                                
npm notice shasum:        bedfcc974c9b50c8572be0e9db3c5cff3a730a30
npm notice integrity:     sha512-lT2QcLnB4qtMp[...]OwkanAW+/3dHg==
npm notice bundled deps:  1                                       
npm notice bundled files: 93                                      
npm notice own files:     9                                       
npm notice total files:   102                                     
npm notice 
cdt-gdb-vscode-0.0.61.tgz

$ yarn pack
yarn pack v1.12.3
error An unexpected error occurred: "Cannot find module \".\"".
info If you think this is a bug, please open a bug report with the information provided in "/home/emaisin/src/cdt-gdb-vscode/yarn-error.log".
info Visit https://yarnpkg.com/en/docs/cli/pack for documentation about this command.

5. Go to the New release page.
6. Fill the fields:
   1. For Tag Version and Release Title, I use the version (e.g. v0.0.61).
   2. Target stays master.
   3. Attach the .tgz created by npm pack.
7. Click Publish Release!
8. Give yourself a pat on the back, this is a good release.

Alternative procedure

The above procedure works by pulling the latest cdt-gdb-adapter package from npm. In case the package does not contain the latest changes from its GitHub project, we can follow the procedure below:

1. Make sure to start from a clean repository (git clean -xfd).

2. Create and checkout a release branch:

   git checkout -b release/<release-name>

3. Clone the cdt-gdb-adapter sources in this branch:

   git submodule add https://github.com/eclipse-cdt/cdt-gdb-adapter.git

4. Add the following script to cdt-gdb-vscode's package.json file:

   "scripts": {
       "preinstall": "cd cdt-gdb-adapter && yarn && yarn build && yarn pack --filename cdt-gdb-adapter.tgz",
   }

5. Change the cdt-gdb-adapter dependency constraint to the archive that will be packed on install:

   "dependencies": {
       "cdt-gdb-adapter": "file:cdt-gdb-adapter/cdt-gdb-adapter.tgz",
   }

6. Push your release branch to GitHub.

7. Build and pack cdt-gdb-vscode:

   yarn
   yarn build
   npm pack # `yarn pack` fails for some reason

8. Go to the New release page.

9. Fill the fields:

   1. For Tag Version and Release Title, I use the version and a tag (e.g. v0.0.61-theia.1).
   2. Point Target to your release branch.
   3. Attach the .tgz created by npm pack.

10. Click Publish Release!