Skip to content

release-management.md

Latest commit

 

History

History
231 lines (150 loc) · 15.5 KB

release-management.md

File metadata and controls

231 lines (150 loc) · 15.5 KB

Release Management

These notes cover how to release and deploy the three primary apps, i.e. service, website, and crawler.

NOTE: All apps are transitioning to use GitHub actions for deploying. This documentation will be changing as that effort proceeds, so check back here before every release and deploy.

Pre-Release: Update SPDX Libraries

Before creating a release, consider updating the SPDX-related libraries used by the service and crawler. These libraries are responsible for correctly identifying SPDX license IDs; outdated versions may cause license expressions to be reported as NOASSERTION. Check for updates in the following repositories:

Acceptance Test

Before Release and Deploy, follow the acceptance testing recommendations in this section.

End-to-end integration tests have been implemented to ensure that the functionalities of the service API work as expected. Further effort is required to enhance the test suite and cover more cases and error handling.

To manually trigger the integration tests, you can use GitHub Actions in the operations repository. If you run the tests on the main branch, all the tests committed to that branch will be executed. By default, the integration tests compare the results from the development deployment with the production deployment. You can configure the development and production deployments in testConfig.js.

After running the integration tests, confirm there are no exceptions in the console logs for the dev deployment. Check the log stream for the clearlydefined-api-dev Web App and the cdcrawler-dev Web App in Azure Portal under Monitoring → Log stream.

The current tests include:

  • Harvesting components that are supported by ClearlyDefined.
  • Retrieving information from the harvest store through the /harvest API.
  • Computing and retrieving definitions for coordinates through the /definitions API.
  • Searching for definitions for coordinates through the GET /definitions API.
  • Curating components through the PATCH /curations API.
  • Retrieving curation information through the /curations API.
  • Previewing definitions with curation through the /definitions API.
  • Retrieving attachments through the /attachments API.
  • Generating notices for all component types supported by ClearlyDefined through the POST /notices API
  • Validating origins for supported component types and providers through the /origins API.
  • Retrieving service statistics through the /stats API.
  • Retrieving crawler status metrics through the /status API.

Release

This process is for production only. Skip to Deploy for dev apps.

  1. Write release notes. This will help you determine the version to use for the new release. See How to create Release Notes for information on the structure of the notes. Writing these early will help identify what needs to be tested. Save the notes outside of GitHub (e.g. Google Docs).
  2. Decide the appropriate version for the new release following Semantic Versioning. See TLDR; Understanding Semantic Versioning for guidance on selecting the new version.)
  3. Update the version
    • in master branch, run npm version <NEW_VERSION> --no-git-tag-version (e.g. npm version v2.4.0 --no-git-tag-version)
    • commit updated version to master branch
    • push commit directly to master branch (This is the only time you should directly push to master)
  4. Update code being published
    • DO NOT CREATE A PR as this causes the histories to be out of sync
    • rebase prod on revision... master (git checkout prod && git merge master --ff-only && git push origin prod) TODO: double check the git commands work, as I do this in Tower.
    • Check that the update was successful by comparing prod to master and master to prod. Both should show "There isn’t anything to compare." and "prod and master are identical." or "master and prod are identical." (_Links are for the crawler. Use a similar process for the service and website.)
  5. Create the release
    • click Draft a new release
    • change Target to prod
    • click Choose a tag and type the tag (e.g. v2.4.0) and click + Create new tag: (should show the new tag)
    • set the Release title to the version (e.g. v2.4.0)
    • for the notes, use the full set of release notes created previously (good for complex releases requiring explanation) or use the Generate release notes button (good for short releases that are straight forward)
    • verify Set as the latest release is checked
    • click Publish release

Deploy

Repositories, Workflows, and Azure Apps

service

website

crawler:

dev Deploy

All three apps use the common deployment workflows defined in operations/.github/workflows for dev deploy.

A deploy workflow is triggered by merging into the master branch which will be deployed to <Azure App basename>-dev.

You can also deploy manually. This is commonly used to test a PR branch before merging.

  • under the Actions tab, select Build and Deploy -- DEV workflow
  • click Run workflow drop down
  • click the Branch: master drop down
  • select the branch or tag you want to deploy
  • click Run workflow button.

Confirm the ghcr package was created.

Confirm that the dev health endpoint has the correct version and sha.

prod Deploy

All three apps use the common deployment workflows defined in operations/.github/workflows for prod deploy. The Crawler requires an additional step described in Crawler Production Deploy - Extra Steps.

A deploy workflow is triggered when a release is published. The prod branch will be deployed to <Azure App basename>-prod and <Azure App basename>-prod-europe.

You can also deploy manually. THIS IS UNCOMMON. Production is setup to run the latest release. This might be used if something goes wrong after a new release is deployed to revert to the previous production release.

  • under the Actions tab, select Build and Deploy -- PROD workflow
  • click Run workflow drop down
  • click the Branch: master drop down
  • select the previous known good release's tag
  • click Run workflow button.

Confirm the ghcr package was created.

Additionally, the crawler publishes to Docker Hub. Verify a tag for the new release was added there.

  • crawler-prod Docker Hub - You should see a TAG named for newly released version. The latest TAG and the new version's TAG should have the same Digest sha and compressed size.

Confirm that the dev health endpoint has the correct version and sha.

The website production release does not include the healthcheck. It will take you to the home page.

Crawler Production Deploy - Extra Steps

Right now, the last step is to ask staff at MSFT to restart the production crawler. TODO: Working on a better process.

Once the final step completes, confirm that the production health endpoint has the correct version and sha.

Update Configuration

If the release includes service configuration changes, update the App Service settings for both clearlydefined-api-prod and clearlydefined-api-prod-europe to keep them in sync.

For crawler configuration changes, communicate the relevant updates to the appropriate stakeholders, as the crawlers are managed separately.

Verification After Deployment

After the deployment, API calls can be made to the service for verification purposes. The collection of sample API calls can be found at tools/integration/api-test.

Here are some steps to get started:

  1. To ensure that the service is up and running, perform a ping/health and confirm the build SHA and version match that of the release tag.
  2. Use the POST call to /harvest to add a new component for harvesting. You can find an example of this API call in the harvest folder of the sample collection. Replace the request body with the details of the new component. Please note that components that have already been harvested are usually skipped during the harvest process.
  3. To confirm that the component has been successfully harvested, you can either inspect the harvest store (such as Blob Storage) or make a GET call to /harvest. You can find examples of the API call in the harvest folder of the sample collection. Keep in mind that depending on the number of items in the queue, it may take some time for the harvest to be completed.
  4. Verify the definition of the component by making a GET call to /definitions. Examples of this call can be found in the definitions folder of the sample collection. Alternatively, you can also verify the definition through the ClearlyDefined website, e.g. https://clearlydefined.io/definitions/npm/npmjs/@types/aws-lambda/8.10.137, along with the corresponding coordinates.
  5. Verify the notice generation by making a POST call to /notices. You can find an example of this call in the notices folder of the sample api-test collection.
  6. Check the website to ensure that the recently harvested list is populated. You can click on the components listed there to verify their definitions.

Appendix

Create Release Notes

The release notes should follow this basic pattern...

NOTE: Anywhere there is a list of PRs, the format follows that returned by getPRs. See section Get the list of PRs since the last release. Copy and paste the PRs from the list into the release notes.

## Release Highlights

Release tag: [v1.0.0](https://github.com/clearlydefined/service/tree/v1.0.0)

Brief overview of the major impact of the release.

## Upgrade Notes

Describe any actions required to be able to use this version.  For example, instructions for running a database migration, how to process changes in file formats, etc.

## What’s changed

_The next line shows an example using the service app of how to create a link to a diff of all changes._

Changes: [v1.0.0...v1.0.1](https://github.com/clearlydefined/service/compare/v1.0.0...https://github.com/clearlydefined/service/compare/v1.0.1)

### Breaking Changes

* List of PRs that introduce breaking changes
* If none, do not include this section

### Minor Changes

* List of PRs, not in a previous section, that introduce minor changes
* If none, do not include this section

### Bug Fixes and Patches

* List of PRs, not in a previous section, that are bug fixes or patches
* If none, do not include this section

Understanding Semantic Versioning

If you are not familiar with Semantic Versioning, you are encouraged to read the official documentation for the full description.

Semantic Versioning tracks three levels of change in the version number (e.g. v2.3.4)

MAJOR: from v2.3.4 to v3.0.0

The first number increments if there is a breaking change meaning that the consumer cannot use this version without taking additional steps (Examples: new feature that is required, database schema changes, file format changes, changes to signatures/output of public methods, API changes, etc.)

NOTE: To limit the number of MAJOR releases, consider using deprecation. With deprecation, users can use either the old approach or the new one. If the old code is used, a deprecation message is logged advising an update to the new approach. When a MAJOR release is required, all deprecated code is removed.

MINOR: from v2.3.4 to v2.4.0

The second number increments if there is a minor change and no MAJOR changes (Examples: new feature that is optional, changes to signatures/output of private methods, new API endpoint, etc.)

PATCH: from v2.3.4 to v2.3.5

The third number increments if there are only trivial changes that do not impact processing and there aren't any MAJOR or MINOR changes (Examples: bug fixes, documentation changes, fixing typos, etc.)