github.com/lineaje-labs/syft@v0.98.1-0.20231227153149-9e393f60ff1b/RELEASE.md (about)

     1  # Release
     2  
     3  ## Creating a release
     4  
     5  This release process itself should be as automated as possible, and has only a few steps:
     6  
     7  1. **Trigger a new release with `make release`**. At this point you'll see a preview
     8    changelog in the terminal. If you're happy with the changelog, press `y` to continue, otherwise
     9    you can abort and adjust the labels on the PRs and issues to be included in the release and
    10    re-run the release trigger command.
    11  
    12  1. A release admin must approve the release on the GitHub Actions release pipeline run page.
    13     Once approved, the release pipeline will generate all assets and publish a GitHub Release.
    14  
    15  1. If there is a release Milestone, close it.
    16  
    17  Ideally releasing should be done often with small increments when possible. Unless a
    18  breaking change is blocking the release, or no fixes/features have been merged, a good
    19  target release cadence is between every 1 or 2 weeks.
    20  
    21  
    22  ## Retracting a release
    23  
    24  If a release is found to be problematic, it can be retracted with the following steps:
    25  
    26  - Deleting the GitHub Release
    27  - Untag the docker images in the `ghcr.io` and `docker.io` registries
    28  - Revert the brew formula in [`anchore/homebrew-syft`](https://github.com/anchore/homebrew-syft) to point to the previous release
    29  - Add a new `retract` entry in the go.mod for the versioned release
    30  
    31  **Note**: do not delete release tags from the git repository since there may already be references to the release
    32  in the go proxy, which will cause confusion when trying to reuse the tag later (the H1 hash will not match and there
    33  will be a warning when users try to pull the new release).
    34  
    35  
    36  ## Background
    37  
    38  A good release process has the following qualities:
    39  
    40  1. There is a way to plan what should be in a release
    41  1. There is a way to see what is actually in a release
    42  1. Allow for different kinds of releases (major breaking vs backwards compatible enhancements vs patch updates)
    43  1. Specify a repeatable way to build and publish software artifacts
    44  
    45  
    46  ### Planning a release
    47  
    48  To indicate a set of features to be released together add each issue to an in-repository
    49  Milestone named with major-minor version to be released (e.g. `v0.1`). It is OK for other
    50  features to be in the release that were not originally planned, and these issues and PRs
    51  do not need to be added to the Milestone in question. Only the set of features that, when
    52  completed, would allow the release to be considered complete. A Milestone is only used to:
    53  
    54  - Plan what is desired to be in a release
    55  - Track progress to indicate when we may be ready to cut a new release
    56  
    57  Not all releases need to be planned. For instance, patch releases for fixes should be
    58  released when they are ready and when releasing would not interfere with another current
    59  release (where some partial or breaking features have already been merged).
    60  
    61  Unless necessary, feature releases should be small and frequent, which may obviate the
    62  need for regular release planning under a Milestone.
    63  
    64  
    65  ### What is in a release
    66  
    67  Milestones are specifically for planning a release, not necessarily tracking all changes
    68  that a release may bring (and more importantly, not all releases are necessarily planned
    69  either).
    70  
    71  This is one of the (many) reasons for a Changelog. A good Changelog lists changes grouped
    72  by the type of change (new, enhancement, deprecation, breaking, bug fix, security fix), in
    73  chronological order (within groups), linking the PR where the change was made in the
    74  Changelog line. Furthermore, there should be a place to see all released versions, the
    75  release date for each release, the semantic version of the release, and the set of changes
    76  for each release.
    77  
    78  **This project auto-generates the Changelog contents for each current release and posts the
    79  generated contents to the GitHub Release page**. Leveraging the GitHub Releases feature
    80  allows GitHub to manage the Changelog on each release outside of the git source tree while
    81  still being hosted with the released assets.
    82  
    83  The Changelog is generated from the metadata from in-repository issues and PRs, using
    84  labels to guide what kind of change each item is (e.g. breaking, new feature, bug fix,
    85  etx). Only issues/PRs with select labels are included in the Changelog, and only if the
    86  issue/PR was created after the last release. Additional labels are used to exclude items
    87  from the Changelog.
    88  
    89  The above suggestions imply that we should:
    90  
    91  - Ensure there is a sufficient title for each PR and issue title to be included in the
    92    Changelog
    93  - The appropriate label is applied to PRs and/or issues to drive specific change type
    94    sections (deprecated, breaking, security, bug, etc)
    95  
    96  **With this approach as we cultivate good organization of PRs and issues we automatically
    97  get an equally good Changelog.**
    98  
    99  
   100  ### Major, minor, and patch releases
   101  
   102  The latest version of the tool is the only supported version, which implies that multiple
   103  parallel release branches will not be a regular process (if ever). Multiple releases can
   104  be planned in parallel, however, only one can be actively developed at a time. That is, if
   105  PRs attached to a release Milestone have been merged into the main branch, that release is
   106  now the "next" release. **This implies that the source of truth for release lies with the
   107  git log and Changelog, not with the release Milestones** (which are purely for planning and
   108  tracking).
   109  
   110  Semantic versioning should be used to indicate breaking changes, new features, and fixes.
   111  The exception to this is `< 1.0`, where the major version is not bumped for breaking changes,
   112  instead the minor version indicates both new features and breaking changes.