← Javascript Development

JS Build Process

Release Process

Note: You will need to login to private Banno registry (npm login) to be able to publish to it. See the instructions at the top of the https://npm.banno-internal.com/ page. (Use your Banno LDAP credentials.)

It is recommended to use a tool such as np, publish-please, or release-it when releasing a new version of a project. They ensure that necessary steps are taken, and avoid the gotchas of npm publish. The following process assumes you are using np:

  1. Make sure the distribution files have been built (if applicable) and that tests are passing.

  2. Run the np tool and answer the interactive questions.

    Very important: If it is a prerelease, or an older version, or anything other than what should be the new default version of a project, you must specify a tag: e.g. np --tag next for a prerelease, or np --tag older for an old version that was never published. More info: https://docs.npmjs.com/cli/dist-tag

  3. Create release notes in GitHub.

Manual Method

  1. Make sure you are in the master branch and have pulled the latest commits.
  2. Increment the version in the package.json to the new version. Be sure to follow semantic versioning.
  3. Run all unit and E2E tests.
  4. Build the distribution files. This will depend on the project – check the docs and code. Older projects use grunt dist/grunt or gulp; newer projects will probably use npm scripts.
  5. Stage and commit your changes with a message like “Release vX.X.X”.
  6. Create a new tag: git tag vX.X.X -a -m 'Tagging vX.X.X'
  7. Push everything to the remote repository: git push && git push --tags
  8. If releasing the “latest” version of a project, publish it to the registry: npm publish
  • Very important: If it is a prerelease, or an older version, or anything other than what should be the new default version of a project, you must specify a tag: e.g. npm publish --tag next for a prerelease, or npm publish --tag older for an old version that was never published. More info: https://docs.npmjs.com/cli/dist-tag
  1. Create release notes in GitHub.

Note that if you have git-extras installed, you can perform steps 5-7 (after you stage your changes) with a single command: git release vX.X.X

Proposed Build Process

The process that follows has been discussed but has not yet been decided on.

This document contains recommendations/guidelines on how to construct a build process and how github repositories are organized for JS projects.

Following this process ensures that releases only contain the output of the dist task. It also ensures the source branch (master) does not include distributables. Doing it this provides the following benefits:

  • Fewer files in the release branch means that environments that don’t need the source code (production deploys and higher-level projects) are faster – They don’t need to download or store the source, or rebuild the distributables.
  • The separation of files and history between source and distribution makes it cleaner to look at and work with. The release branch can be distributed as-is (through links, Bower, zipped packages, etc), and developers can ignore those files during development.

Prepare a Repository

In order to prepare a repository for distributable releases, create a release branch and a snapshot branch, both with an empty initial commit. You can do this by using the –orphan flag with git checkout.

Assumptions

Each project has a package.json file with a version, name, homepage URL, and repository URL.

The grunt dist task should prepend the application code with the version number from package.json (using grunt-banner or similar tool). It should create all the release code (including mock services) in a .gitignored dist folder.

Each project should have a README that describes the build process (or points to this documentation).

Build Process

  1. Decide on the new version number. It should follow semantic versioning.

  2. Switch to the master branch and ensure it is up to date and the working directory is clean.

  3. Run tests (and make sure it’s working in the browser too).

  4. Add gulp-banno-release (if not installed) and run gulp release --setversion=X.X.X. This task will do the following:

    1. Update the version number across the codebase: README, docs,package.json and bower.json, etc.
    2. Build the distribution. This is usually done with grunt dist. Ensure the distributables have been built correctly. (For libraries: Copy/build a Bower manifest for the distribution.)
    3. Commit the changes. Use a commit message like “Release vX.X.X”.
    4. Copy the current commit hash to clipboard for later (git rev-parse HEAD).
    5. Switch to the snapshot branch and make sure it is up to date and the working directory is clean.
    6. Merge master into snapshot with the version number as the commit message.
    7. Switch to the release branch and make sure it is up to date and the working directory is clean.
    8. Copy files from the .gitignored dist folder to the project’s root directory.
    9. Commit and push new dist files to release branch with version and commit hash (from your clipboard from step 2) as the message (e.g. v0.0.1 e2bc44fa491706d9bd0f3ccb3f3011e6b98b9108).
    10. Create an annotated tag based off the latest commit to the release branch with the same commit message as the previous step.
    git tag v0.0.1 -a -m 'v0.0.1 e2bc44fa491706d9bd0f3ccb3f3011e6b98b9108'
    1. Push the changes (with tags) to GitHub: git push --tags origin master snapshot release

  5. Create release notes in GitHub

Note

Commits should never otherwise be pushed to the snapshot or release branches.

Examples

(link to some of our projects that follow this)

References

This process is loosely based on the release process of angular-ui/bootstrap. They put all versions of their build files in a separate branch, and keep a separate repository up to date with release files, which is what their bower registry is linked to. Rather than using a separate repository for release files, this process just uses another branch.