Skip to content

Latest commit

 

History

History
169 lines (103 loc) · 9.35 KB

PIPELINE.md

File metadata and controls

169 lines (103 loc) · 9.35 KB
Raw

Frodo Release Pipeline

The Frodo project uses a fully automated release pipeline based on GitHub workflows:

Frodo Release Pipeline Workflow

Releasing Frodo

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 releases work.

Every Push Triggers A Release

Frodo adopted the principle of continuous integration. Therefore every push to the main branch in the [rockcarver/frodo] repository trigger 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 get 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

Frodo is currently in a pre-1.0.0 phase. We are striving to release 1.0.0 very soon.

Current Pipeline Explained

Trigger Event

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

Smoke Tests

This step performs a quick smoke test of the vital functions like login with and without network proxy. All smoke tests must pass or pipeline execution terminates.

Update Changelog

This step calculates the new version but doesn't modify package.json and package-lock.json. Based on that new version, it creates a new heading in the CHANGELOG.md file and moves everything from the Unreleased section into the new version section. It also creates links to the release tags at the bottom of the CHANGELOG.md file. Last but not least, it commits the updated CHANGELOG.md file to the repository.

3rd-Party Actions

Bump Version

This step calculates the new version and corresponding tag, updates both package.json and package-lock.json and commits the changes to the main branch.

3rd-Party Actions

Release Notes

This step extracts the changes under the heading that matches the release version and uses it as the release notes. For pre-releases it also generates a section of changes based on commits that were part of the release.

Good release notes require the contributor and/or maintainer take the time and update the CHANGELOG.md file. Auto-generated release notes based on commit comments are less than optimal but acceptable for pre-releases.

Patch, minor, and major releases require a carefully curated CHANGELOG.md file.

3rd-Party Actions

Release

This step creates a GitHub release based on the tag created in a previous step and posts a number of artifacts:

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

Note: this step does not include the frodo binaries!

3rd-Party Actions

Binary Releases

The binaries are built by GitHub runners of the same OS as the binary they are building. That allows the binaries to be executed (tested) as one of the steps in the build process.

The binary builds run in parallel while all the previous steps run in sequence and must complete before the binay builds even kick off.

Linux Binary Release

This step builds the Linux binary and adds it to the release created in an earlier step.

3rd-Party Actions

Mac OS Binary Release

This step builds the Mac OS binary and adds it to the release created in an earlier step.

3rd-Party Actions

Windows Binary Release

This step builds the Windows binary and adds it to the release created in an earlier step.

3rd-Party Actions

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 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
  6. Validate the pipeline created the desired new version and release