Foam: Document publishing foam-vscode

[jsjoeio]

This message is copied from a private channel in Discord (if you have access, you can view here).

As for publishing, you can use lerna to publish all packages in lockstep.

First bump the package version by running this in the monorepo root:

yarn lerna version <major|minor|patch>

That will bump the version numbers of all packages, and their internal references, so for example foam-vscode will point to the new version of foam-core etc.

It will also push a tag to github. If you want to dry run this locally without pushing, you can run

yarn lerna version minor --no-git-tag-version --no-push

When you're ready to publish, you can do:

yarn lerna publish

Once the npm packages are published, you can package up the vscode extension with the following command in the foam-vscode directory:
yarn package-extension

The vsce tool does not understand yarn monorepos, so what this will do is use npm to install the package, which requires the foam-core dependency to have already been published to npm. I know this is ass backwards, since if you discover that something is wrong in the packaged extension, you'll need to fix whatever issue there is and then republish the packages to npm, which will again bump the version number and cause potentially dead versions in the registry. If you want to avoid that, you can first create an alpha version with creating a prerelease version, e.g. 0.4.1-alpha.0, with:

yarn lerna publish <premajor|preminor|prepatch|prerelease>

Anyway, once you've gotten a nicely packaged vsix file, you can install
and test it locally:

code --install-extension foam-vscode-0.4.1.vsix

If everything is fine, you can then publish the vsix file to marketplace:

vsce publish --packagePath foam-vscode-0.4.1.vsix

That should probably be documented, and the process could be improved, but that's what it is now :man_shrugging:

Two things I wanted to note here:

1. Ideally, it would be nice to auto-publish via a GitHub action
2. Publishing the extension should be documented somewhere for contributors

[riccardoferretti]

hi @jsjoeio - you are totally right, I have more notes from the handover with @jevakallio - will write them down in the foam doc.
I would also like to automate most of the flow (there is a testing step, which will need to be manual until we add more e2e tests), any guide/contribution/suggestion very much appreciated (somewhat related to #315)

[jsjoeio]

I can help with this if you want @riccardoferretti - feel free to assign to me after sharing your notes!

[jsjoeio]

More notes:
yarn lerna publish preminor

• update CHANGELOG.MD file

• yarn lerna publish preminor

from package/foam-vscode
yarn package-extension

• do local testing

  • linkdef generation
  • navigation
  • graph
  • snippets

• fix bugs if necessary (and CHANGELOG)

• yarn lerna publish minor

• republish
  from package/foam-vscode
  yarn package-extension

• might wanna test it again based on bug fixes

• publish the extension
  npx vsce publish --packagePath foam-vscode-XXX

• update the release notes

  • in GitHub, top right, click on releases
  • select "tags" in top left
  • pick last released tag, add release information from changelog
  • publish (no need to attach artifacts)

• announce on discord

TODO

• check whether we need the pre publish step, or if we can build the extension from the monorepo (once https://github.com/microsoft/vscode-vsce/pull/493 is merged)
  
  
  
  • to test if it works, just bump the version locally, then run the "yarn package extension" command --> if it works the issue if fixed, if it doesn't it's trying to get the package from 5pm
  
  
• replace in package-extension the use of npx with yarn
• write doc about release process
• create proper test script

[riccardoferretti]

when doing the second publish without changes, we need to force the new publish by using yarn lerna publish --force-publish \* (see https://lerna.js.org/#command-publish)

[riccardoferretti]

forgot to mention before, we should also make publishing to https://open-vsx.org/ part of this process

[jsjoeio]

Good call!

[riccardoferretti]

https://code.visualstudio.com/api/working-with-extensions/continuous-integration#automated-publishing

[riccardoferretti]

The latest and greatest script I am following now:

All commands are run from the root folder

1. checkout master and fast forward to origin/master
   
   
   
   • git checkout master && git fetch && git rebase
   
   
2. run sanity checks
   
   
   
   • yarn clean && yarn build && yarn test
   
   
3. Update ./packages/foam-vscode/CHANGELOG.md
4. Publish the pre-release packages to NPM
   
   
   
   • yarn lerna publish preminor --no-git-tag-version --no-push
   
   
   • This will:
   
   
   • Bump the version numbers of all packages, and their internal references (so e.g. foam-vscode will point to the new version of foam-core, etc)
   
   
   • Publish the packages to npm
   
   
   • Normally it would also push a tag to git, the --no-git-tag-version --no-push options prevent that from happening
   
   
   • This step is necessary because the extension packager doesn't work with monorepos (https://github.com/microsoft/vscode-vsce/pull/493), but needs the dependencies (in this case foam-core) to be in npm
   
   
5. Package the extension locally
   
   
   
   • yarn vscode:package-extension
   
   
   • the artifact can be found at ./packages/foam-vscode/foam-vscode-$version.vsix
   
   
6. Install the extension locally and do manual testing
   
   
   
   • yarn vscode:install-extension
   
   
   • do manual tests
   
   
7. Publish the release to git and NPM
   
   
   
   • yarn lerna publish minor
   
   
   • This will:
   
   
   • Bump the version numbers of all packages, and their internal references, as before
   
   
   • Create a git tag and push it to origin
   
   
   • Publish the packages to npm
   
   
8. Package the extension to be released
   
   
   
   • yarn vscode:package-extension
   
   
9. Publish the extension to the VSCode Marketplace
   
   
   
   • yarn vscode:publish-extension
   
   
10. Update the release notes in GitHub
    
    
    
    • in GitHub, top right, click on "releases"
    
    
    • select "tags" in top left
    
    
    • select the tag that was just released, click "edit" and copy release information from changelog
    
    
    • publish (no need to attach artifacts)
    
    
11. Announce to discord

[jsjoeio]

Oh man...I'm liking how this is shaking out @riccardoferretti 👏🏼 Step 10 sounds great too! Sorry I haven't had time to jump on this, thanks for getting started!

[jvmazagao]

Can steps 9 and 10 be automated?

The discord announces, I supposed that had Github Actions and 9 We can create an Action too.

But Great Script @riccardoferretti

[riccardoferretti]

Update. (and fixed numbering)

But as I get more familiar with this, I will probably turn it into a github action soon.
(I am using every release as a test bed for something ;) )

All commands are run from the root folder

1. checkout master and fast forward to origin/master
   
   
   
   • git checkout master && git fetch && git rebase
   
   
2. run sanity checks
   
   
   
   • yarn clean && yarn build && yarn test
   
   
3. Update ./packages/foam-vscode/CHANGELOG.md

4. Publish the pre-release packages to NPM

   • _This step is necessary because the extension packager doesn't work with monorepos (microsoft/vscode-vsce#493), but needs the dependencies (in this case foam-core) to be in npm_
   • yarn lerna version preminor --no-git-tag-version --no-push
   • This will:
     
     
     
     • Bump the version numbers of all packages, and their internal references (so e.g. foam-vscode will point to the new version of foam-core, etc)
     
     
     • Normally it would also push a tag to git, the --no-git-tag-version --no-push options prevent that from happening
     
     
   • git add *
   • git commit -m"Preparation for next release"
   • lerna publish from-package
   • Publish the packages to npm

5. Package the extension locally

   • yarn vscode:package-extension
   • the artifact can be found at ./packages/foam-vscode/foam-vscode-$version.vsix
6. Install the extension locally and do manual testing
   
   
   
   • yarn vscode:install-extension
   
   
   • do manual tests
   
   
7. Publish the release to git and NPM
   
   
   
   • yarn lerna publish minor
   
   
   • This will:
   
   
   • Bump the version numbers of all packages, and their internal references, as before
   
   
   • Create a git tag and push it to origin
   
   
   • Publish the packages to npm
   
   
8. Package the extension to be released
   
   
   
   • yarn vscode:package-extension
   
   
9. Publish the extension to the VSCode Marketplace
   
   
   
   • yarn vscode:publish-extension
   
   
   • if the publish command fails because the token has expired, follow the instructions here
   
   
   • (you don't need to install vsce, just call it via npx e.g. npx vsce login foam)
   
   
10. Update the release notes in GitHub
    
    
    
    • in GitHub, top right, click on "releases"
    
    
    • select "tags" in top left
    
    
    • select the tag that was just released, click "edit" and copy release information from changelog
    
    
    • publish (no need to attach artifacts)
    
    
11. Announce to discord