Developer guide

February 14, 2022 ยท View on GitHub

Prerequisite

  • Node v16

Develop

First-time install

# At the root of the repo
npm install

Development loop

  • Make changes to TypeScript files in the packages/cli folder.
  • In repo root, run npm start. This will build latest cli and run it inside the sandbox.
  • To debug with breakpoints
    1. Use Visual Studio Code to set breakpoints in any TypeScript file within packages/cli.
    2. Open debug menu, execute Debug with sandbox launch task.
  • Validate build output in packages/sandbox/public.

Simulate use cases

  • To test remote caching, enable/update the cache url option inside packages/sandbox/osmosfeed.yaml.
  • To test customization, create an packages/sandbox/includes directory and add snippets.
  • To test static file copying, create a packages/sandbox/static directory and add files.

Test

  • cd to the root of the repo. Then npm run test.
  • Unit tests are co-located with the source code in __tests__ folders
  • E2E tests are located in packages/test.
    • Each test scenario simulates a unique configuration of a repo. Add new new scenarios in packages/test/scenarios.
    • Each spec validates a single behavior under a senario. Add new specs in packages/test/test.js.
  • To debug with breakpoints
    1. Use Visual Studio Code to set breakpoints in either test code in packages/test or CLI code in packages/cli.
    2. Open debug menu, execute Debug tests launch task.

CI/CD

  • Build and test are automatically executed for pull requests.
  • GitHub acition will run npm publish when a git tag v<major>.<minor>.<patch> is pushed to master branch.

Publish

Pre-publish checklist

  1. Make sure index.hbs is referencing the latest version of JavaScript and CSS assets.

To publish beta build from feature branch

git checkout <name_of_your_branch>
cd packages/cli

# Choose one of the three
npm version prepatch --preid=beta   # starting a new beta (use prepatch|preminor|preemajor as needed)
npm version prerelease              # bumping up an existing beta

git add -u                          # Add updated package.json
git commit -m "message"             # Commit updated package.json
git push                            # Push updated package.json

git tag vX.Y.X                      # npm might have automatically added a tag. If not, perform the step manually
git push origin vX.Y.X

To publish official build from master branch

First, checkout the lastest master branch.

git checkout master
cd packages/cli

npm version patch|minor|major       # update official release to new semver

git add -u                          # Add updated package.json
git commit -m "message"             # Commit updated package.json
git push                            # Push updated package.json

git tag vX.Y.X                      # npm might have automatically added a tag. If not, perform the step manually
git push origin vX.Y.X

This cause GitHub action to build and publish to npm.

Post-publish checklist

  1. Update CHANGELOG.md to include the latest stable version
  2. Add changelog as release notes in GitHub Releases.
  3. Make sure all contributors are mentioned in the "thank you" section of the release notes
  4. Make sure the docs, demo, examples, and templates are up to date.