github.com/gophercloud/gophercloud@v1.11.0/RELEASE.md (about)

     1  # Gophercloud release
     2  
     3  ## Contributions
     4  
     5  ### The semver label
     6  
     7  Gophercloud follows [semver](https://semver.org/).
     8  
     9  Each Pull request must have a label indicating its impact on the API:
    10  * `semver:patch` for changes that don't impact the API
    11  * `semver:minor` for changes that impact the API in a backwards-compatible fashion
    12  * `semver:major` for changes that introduce a breaking change in the API
    13  
    14  Automation prevents merges if the label is not present.
    15  
    16  ### Metadata
    17  
    18  The release notes for a given release are generated based on the PR title: make
    19  sure that the PR title is descriptive.
    20  
    21  ## Release of a new version
    22  
    23  Requirements:
    24  * [`gh`](https://github.com/cli/cli)
    25  * [`jq`](https://stedolan.github.io/jq/)
    26  
    27  ### Step 1: Collect all PRs since the last release
    28  
    29  Supposing that the base release is `v1.2.0`:
    30  
    31  ```
    32  for commit_sha in $(git log --pretty=format:"%h" v1.2.0..HEAD); do
    33          gh pr list --search "$commit_sha" --state merged --json number,title,labels,url
    34  done | jq '.[]' | jq --slurp 'unique_by(.number)' > prs.json
    35  ```
    36  
    37  This JSON file will be useful later.
    38  
    39  ### Step 2: Determine the version
    40  
    41  In order to determine the version of the next release, we first check that no incompatible change is detected in the code that has been merged since the last release. This step can be automated with the `gorelease` tool:
    42  
    43  ```shell
    44  gorelease | grep -B2 -A0 '^## incompatible changes'
    45  ```
    46  
    47  If the tool detects incompatible changes outside a `testing` package, then the bump is major.
    48  
    49  Next, we check all PRs merged since the last release using the file `prs.json` that we generated above.
    50  
    51  * Find PRs labeled with `semver:major`: `jq 'map(select(contains({labels: [{name: "semver:major"}]}) ))' prs.json`
    52  * Find PRs labeled with `semver:minor`: `jq 'map(select(contains({labels: [{name: "semver:minor"}]}) ))' prs.json`
    53  
    54  The highest semver descriptor determines the release bump.
    55  
    56  ### Step 3: Release notes and version string
    57  
    58  Once all PRs have a sensible title, generate the release notes:
    59  
    60  ```shell
    61  jq -r '.[] | "* [GH-\(.number)](\(.url)) \(.title)"' prs.json
    62  ```
    63  
    64  Add that to the top of `CHANGELOG.md`. Also add any information that could be useful to consumers willing to upgrade.
    65  
    66  **Set the new version string in the `DefaultUserAgent` constant in `provider_client.go`.**
    67  
    68  Create a PR with these two changes. The new PR should be labeled with the semver label corresponding to the type of bump.
    69  
    70  ### Step 3: Git tag and Github release
    71  
    72  The Go mod system relies on Git tags. In order to simulate a review mechanism, we rely on Github to create the tag through the Release mechanism.
    73  
    74  * [Prepare a new release](https://github.com/gophercloud/gophercloud/releases/new)
    75  * Let Github generate the  release notes by clicking on Generate release notes
    76  * Click on **Save draft**
    77  * Ask another Gophercloud maintainer to review and publish the release
    78  
    79  _Note: never change a release or force-push a tag. Tags are almost immediately picked up by the Go proxy and changing the commit it points to will be detected as tampering._