Revisit Release Process

[jheer]

Using this issue to document the current release process and brainstorm potential changes.

Current Vega Release Steps

​

• Review all commits since last release
  • Check if patch, minor, or major changes per package
  • Determine new package version numbers
  • Draft release notes, organized by package
    ​
• Update dependencies (esp. dev dependencies)
  • Address any issues or breakage
    ​
• Update all package version numbers
  • Be sure to bump the Vega schema package upon minor updates to Vega
    ​
• Test Vega
  • Run unit tests and linting
  • Build the full project (yarn build)
  • Manually check the Vega dev tests (run yarn serve, and browse to /test/)
    ​
• Update and test documentation
  • Update version numbers in docs/_data/versions.yml
  • Run yarn docsbuild, which is also called upon yarn build
  • Run yarn docs to run jekyll locally, test documentation files
  • Commit updated docs files
    ​
• Merge all updated files to the 'main' branch
  • I typically stage in a PR branch named 'chore: v5.26.0' or similar.
  • Upon merge, the documentation will update! So be ready to release :)
    ​
• Perform the release
  • Ensure vega/schema exists in a sibling directory of the vega project
  • This is critical to make sure the schema registry is updated
  • Run yarn release (proper permissions on npm required)
  • Hope that nothing fails! If so, figure out what happened and fix it
  • After npm release, add a release with notes/changelog on GitHub
    ​

Possible Future Improvements

​

• Typings and dependency versions

  • By far the biggest release pain point over time has been vega-typings
  • It often breaks upon various updates to typescript, dtslint, and/or prettier
  • This is why you will see some fixed versions in package.json!
  • Updating the typings -- or rehauling the typings + schema altogether -- could help
    ​

• Package versioning and changelog

  • Right now all packages have independent version numbers
  • It may be simplifying to move to shared version numbers
  • Right now patch/minor/major bumps are made manually
  • We could leverage conventional commits (which we now enforce) to automate this
  • We might similarly (semi-)automate changelog generation
    ​

• In-browser testing of interactive specs

  • Right now I manually test specs and docs in browser
  • Automated testing, including of interactions, could be done via puppeteer
    ​

• New mechanism for updating the vega/schema repo

  • Requiring the schema project in a sibling folder is brittle and error prone
  • Possibly do this through GitHub actions upon a release?

• Consider switching from yarn to npm

  • npm got better over time, catching up with yarm
  • No major impetus here, but one less dependency/install
    ​

• Consolidate packages (questionable / not highest priority in my mind)

  • Right now we have a monorepo with lots of sub-packages
  • This modularity may be overkill?
  • I don't think many (if any) of the packages are used in isolation
  • One might consolidate some parts into a more monolithic Vega package

[jheer]

cc: @domoritz @lsh

[lsh]

Here are a few other notes I think we should add to this list:

• Make sure you are logged into npm via the cli in order to run yarn release.
• vega-cli depends on vega, so it might be worth it to habitually update the dependency version there.
• We should probably also bump the version in the Vega editor during a release for consistency.