Skip to content

Latest commit

 

History

History
120 lines (82 loc) · 7.17 KB

PIPELINE.md

File metadata and controls

120 lines (82 loc) · 7.17 KB
Raw

Frodo Library Release Pipeline

The Frodo Library project uses a fully automated release pipeline based on GitHub workflows and actions (check GitHub services status):

Frodo Library Release Pipeline Workflow

Releasing Frodo Library

This information is only actionable if you are an active contributor or maintainer with appropriate access to the repository and need to understand how frodo-lib releases work.

Every Push Triggers A Release

Frodo Library adopted the principle of continuous integration. Therefore every push to the main branch in the [rockcarver/frodo-lib] repository triggers the automated release pipeline.

The pipeline determines the type of release - prerelease, patch, minor, major - for the push:

  • Scans the commit and PR comments for trigger phrases:
    • PATCH RELEASE triggers a patch release
    • MINOR RELEASE triggers a minor release
    • MAJOR RELEASE triggers a major release
    • Everything else triggers a prerelease
  • Bumps the version accordingly:
    <major>.<minor>.<patch>-<prerelease>
  • Updates the changelog file in keep a changelog format:
    • Creates a new release heading using the bumped version and a date stamp
    • Moves the content of the Unreleased section into the new section
    • Adds release details links

❗❗❗ IMPORTANT ❗❗❗
Contributors are instructed to submit pull requests. Maintainers must make sure none of the commit comments nor the PR comment contain trigger phrases that would cause the pipeline to perform an undesired version bump and release.

Automatic Pre-Releases During Iterative Development

The default release type (if no specific and exact trigger phrases are used) results in a pre-release. Pre-releases are flagged with the label Pre-release on the release page indicating to users that these releases are not considered final or complete.

Pre-releases are a great way to publish the latest and greatest functionality but they are not fully polished, readme and changelog might not be updated and test coverage might not be complete.

Triggering Patch, Minor, and Major Releases

Maintainers must validate PRs contain an updated Unreleased section in thechangelog before merging any PR. Changelog entries must adhere to the keep a changelog format.

Maintainers must use an appropriate trigger phrase (see: Every Push Triggers A Release) in the PR title to trigger the appropriate automated version bump and release.

❗❗❗ IMPORTANT ❗❗❗
Maintainers must adhere to the guidelines set forth by the npm project to determine the appropriate release type:

NPM Versioning Guidelines

Current Pipeline Explained

Trigger Event

The trigger event is any push to the main branch in the repository.

Build

Builds the library, bumps the version, and makes the build artifacts available for processing in subsequent pipeline steps.

Test

Downloads the build artifacts produced in the Build step and runs all the automated tests.

npm-release

Publishes the npm package using the new version tag to npmjs.com.

Release

Downloads the build artifacts produced in the Build step, updates the changelog, and creates a GitHub release based on the new version tag and posts the following artifacts:

  • CHANGELOG.md
  • LICENSE
  • Release.txt - Generated for each release containing the git sha of the release
  • <new version tag>.zip - Generated for each release containing the full repository as a .zip archive
  • <new version tag>.tar.gz - Generated for each release containing the full repository as a .tar.gz archive

Doc

Builds the library API docs and publishes them to https://rockcarver.github.io/frodo-lib/.

Pipeline Maintenance

Pipeline maintenance is a tricky business. Pipeline testing in forks is difficult because GitHub by default imposes a different behaviour for pipeline events than in the main repository. Some pipeline steps require branch names, which means the pipeline needs to be adopted to run in the fork and branch it is being tested in.

All of the above has lead the team to make and test pipeline changes in the main repository on the real pipeline.

Recover From A Wrong Version Bump And Release

When testing the pipeline and especially when experimenting with the automated version bump logic, it is unavoidable that once in a while a version is released that really has to be removed. E.g. during the pipeline development and testing of the first full automation, a bump to version 1.0.0 was triggered unintentionally. While minor and patch version bumps can be dealt with, major version bumps should really not be taken lightly.

So to recover from that, the following needs to happen:

  1. Manually delete the faulty release from the release page
  2. Manually modify the following files in your fork:
    • CHANGELOG.md
      1. Find the faulty release heading towards the top of the file
        1. Move your changelog entries in the faulty release section back into the Unreleased section
        2. Now remove the faulty release header
      2. Find the link to the faulty release tag at the bottom of the file and remove it
    • package.json
      • Fine the 1 occurance of the frodo version in package.json and reset it to the previous version from before the faulty version bump
    • package-lock.json
      • Find the 2 occurances of the faulty version in package-lock.json and reset them to the previous version from before the faulty version bump
  3. Commit your changes and create a new pull request
  4. In the frodo repository, merge the PR and provide the appropriate comment to trigger the intended version bump
  5. Remove the faulty release from npmjs.com This is important as without this step the faulty release will remain published on npmjs.com (npm registry).
    • You must be a maintainer of the package on npmjs.com.
    • Issue the following command:
      npm unpublish @rockcarver/[email protected]
  6. Remove the faulty tag from the repository:
    This is important because you cannot update an existing tag and in order to eventually release the version in the future, you must delete it first. Beware the difference between version (e.g. 1.0.0) and tag (e.g. v1.0.0). This step requires you to use the tag:
    • From the command line, navigate to the directory where you cloned the frodo repository (not your fork, the real one!)
    • Issue the following command:
      git push --delete origin v1.0.0
  7. Validate the pipeline created the desired new version and release