|
| 1 | + |
| 2 | + |
| 3 | +<p style="text-align: center;">Adams Bridge Release Checklist</p> |
| 4 | + |
| 5 | +<p style="text-align: center;">Version 2.0</p> |
| 6 | + |
| 7 | +<div style="page-break-after: always"></div> |
| 8 | + |
| 9 | +# Overview |
| 10 | + |
| 11 | +This document provides the signoff checklist that is used when finalizing any Adams Bridge release version. |
| 12 | + |
| 13 | +# Release Creation |
| 14 | + |
| 15 | +## Versioning |
| 16 | + |
| 17 | +Adams Bridge RTL releases may be created for new major, minor, or patch versions, as described in the [semantic versioning specification](https://semver.org/spec/v2.0.0.html). Steps described in this document are followed for each of these releases. |
| 18 | + |
| 19 | +Pre-release versions are denoted with the alphanumeric key `rc<incrementing_numeric_value>` to indicate that the version is a release candidate. Release candidates are tagged to indicate that feature and validation effort has reached a finalized state, and the final release is pending further review. An example release candidate tag is: `v2.2.0-rc3` |
| 20 | + |
| 21 | +Modifications may also be applied to supporting collateral of a patch release (non-RTL code such as documentation, test scripts, and validation environment) by opening pull requests to the `patch_v<MAJOR>.<MINOR>` branch. When a release receives updates to the documentation or validation material (with no other modifications) this is considered a new "build" from a versioning perspective. Semantic versioning specifies that build metadata can be included in a release version by appending build data to the version. The format for appending build information is: `<MAJOR>.<MINOR>.<PATCH>+<build_identifier>`. |
| 22 | +In adams-bridge releases, the `build_identifier` is always an alphanumeric key that begins with a 1-indexed numeric value. The full format of the build identifier is: `<incrementing_numeric_value>.<alphanumeric_descriptor>[.<alphanumeric_descriptor>]`. |
| 23 | +The only supported values for `<alphanumeric_descriptor>` are the keywords `doc` and `val`. Multiple alphanumeric_descriptor values may be chained together using '.' as a delimiter. When chained together, alphanumeric_descriptor values will always be ordered with higher precedence descriptors shown first, in decreasing precedence. The order of precedence for supported descriptors is shown in the following table: |
| 24 | +| Precedence | alphanumeric_descriptor | |
| 25 | +| :-- | :-- | |
| 26 | +| Highest | `val` | |
| 27 | +| Lowest | `doc` | |
| 28 | + |
| 29 | + |
| 30 | +As a few examples: |
| 31 | +- A series of documentation updates to the 2.0.2 release of adams-bridge would be tagged as: `v2.0.2+1.doc`, `v2.0.2+2.doc`, ... , `v2.0.2+12.doc`. |
| 32 | +- A series of documentation and validation updates to the 2.1.1 release of adams-bridge might be tagged as: `v2.1.1+1.doc`, `v2.1.1+2.val`, ... `v2.1.1+16.val.doc`, `v2.1.1+17.doc`. |
| 33 | + |
| 34 | +Non-RTL updates are only applied to the latest patch release. That is, documentation updates to produce `v2.0.2+3.doc` are not applied to any `v2.0.1` release. A newer patch release inherits all documentation updates from prior patch releases, and may then be subsequently targeted for additional documentation updates. Thus, there is no guarantee that documentation from a given build is applicable to a prior patch release, as patch updates may have modified the area described in the documentation. |
| 35 | + |
| 36 | +## Branches |
| 37 | + |
| 38 | +Each major and minor release is created as a tag on the branch `main` of the adams-bridge repository. The tag is created using GitHub's repository release tagging feature, which also generates a zip file containing all of the code and documentation for that release. After tagging the release, any subsequent commits to `main` are pursuant to development efforts on future release versions, so the tagged release must be used to download the official release code. |
| 39 | + |
| 40 | +When necessary, a patch release may be applied retroactively to earlier versions of Adams Bridge. In this case, a new branch is created to contain the patched code base. Patch release branches follow the naming convention, `patch_v<MAJOR>.<MINOR>`, to indicate which version is being patched. After the patched branch reaches its finalized state, a tag is created on the patch branch to indicate the full version number of that patch. Thus, any patch release is created as a tag on the same branch, with an incrementing patch version number. |
| 41 | + |
| 42 | +## Steps |
| 43 | + |
| 44 | +For each release, the following steps are followed to ensure code functionality and quality. |
| 45 | + |
| 46 | +- Ensure all critical [issues](https://github.com/chipsalliance/adams-bridge/issues) and [Pull Requests](https://github.com/chipsalliance/adams-bridge/pulls) are closed |
| 47 | +- Verify expected checks and scripts are in place |
| 48 | + - Audit pipelines: Coverage logging enabled |
| 49 | + - Audit pipelines: File list checks updated |
| 50 | + - Audit pipelines: License header check targets updated |
| 51 | + - Audit pipelines: RDL generator script is updated |
| 52 | + - Audit pipelines: RDL file checker is updated |
| 53 | + - Audit pipelines: Promote pipeline synth check enabled |
| 54 | + - Audit pipelines: Promote pipeline lint check enabled (and test a false-negative) |
| 55 | + - Audit pipelines: Promote pipeline L0 regression list updated |
| 56 | + - Audit pipelines: Promote pipeline L0 regression enabled |
| 57 | +- Audit RTL and testbenches for FIXME/TODO items |
| 58 | +- Pre-Silicon Regressions |
| 59 | + - [L0 regression](../src/abr_top/stimulus/uvmf_mldsa_top_promote_regression.yml) |
| 60 | + - [L1 regression](../src/abr_top/stimulus/testsuites/abr_top_nightly_random_regression.yml) |
| 61 | + - Directed/Random regression per the [Test Plan](./AdamsBridge_TestPlan.xlsx) |
| 62 | +- Coverage Review |
| 63 | + - Coverage database is manually reviewed to ensure all required coverpoints are exercised |
| 64 | +- Register updates: |
| 65 | + - MLDSA_CORE_VERSION: Update version information according to the defined field mapping to match current release |
| 66 | + - MLKEM_CORE_VERSION: Update version information according to the defined field mapping to match current release |
| 67 | +- Lint review: |
| 68 | + - Lint must be completely clean after applying policies and waivers. |
| 69 | +- Formal Verification review |
| 70 | + - Formal test plans for cryptographic blocks are executed and pass |
| 71 | +- Update documentation |
| 72 | + - Core logic changes documented in the [AdamsBridgeHardwareSpecification](./AdamsBridgeHardwareSpecification.md) |
| 73 | + - [README](../README.md) updates |
| 74 | + - Update [Release_Notes](../Release_Notes.md) |
| 75 | + - Tag the main branch on GitHub to generate an official release |
0 commit comments