bug: dynamically parse the latest/actual release version when building docs

[bobleesj]

Problem

I was wondering why the online doc never displayed the latest release notes (i.g. 3.5.0) when we push 3.5.0 tag, even though CHANGELOG.rst contains 3.5.0 information in main.

It turns outs, when we checkout the repository to build the doc, we checked out the commit of the tag, not the main repository which contains the modified CHANGELOG.rst. The reason we checked out the tag is that it always displayed the correct version number. However, the main branch contains an additional commit that modifies CHANGLEOG.rst by the CI. This is what we (I) failed to recognize for a while.

Proposed solution

Hence, we need to build docs by checking out the main branch as shown in this PR (https://github.com/Billingegroup/release-scripts/pull/120/files#r1900318116). However, it doesn't have the tag information that can be automatically detected by our git-versioning dependency. How do we still get the right tag version? We can dynamically parse the latest release from GitHub's release via requests - hence the changes in this code.

Result:

Shown below, I have tested this implementation using my dummy org/repo that does full release of 0.5.14, using a single run of git tag and push:

[bobleesj]

@sbillinge ready for review

[bobleesj]

We can dynamically get these information in our cookiecutting standard

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (5359054) to head (2d1de2c).

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #312   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            9         9           
  Lines          516       516           
=========================================
  Hits           516       516           

[bobleesj]

this release variable becomes the software version in src/index.rst

[sbillinge]

This is a nice workaround, but I wonder if it is taking us in the right direction. When we make a tag, we want it to actually tag something meaningful. Presumably the 3.6.0 tag should tag the 3.6.0 release, which actually, should include the built changelog.

I wonder if our changelog workflow could somehow delete the tag on upstream and then remake it after the CHANGELOG is merged instead? I am not sure if that is possible.

[bobleesj]

Presumably the 3.6.0 tag should tag the 3.6.0 release, which actually, should include the built changelog.

I agree.

Delete the tag on upstream and then remake it after the CHANGELOG is merged instead?

This could be it. I can look into this. I will report back

[bobleesj]

@sbillinge it's actually working. Thanks for the GREAT idea.

  delete-create-new-tag:
    # For a full release, we delete and create a new tag to reflect the latest changes in the CHANGELOG.rst.
    # Recall that during the full release, the `main` branch's CHANGELOG.rst has been updated, and we want the
    # tag to reflect the latest changes in the CHANGELOG.rst done by the update-changelog above.
    # For more discussions, please read https://github.com/Billingegroup/release-scripts/pull/120
    ....
        uses: actions/checkout@v4
        with:
          ref: main
      - name: Delete the tag
        run: |
          git fetch --tags
          git tag -d "${{ github.ref_name }}"
          git push origin ":${{ github.ref_name }}"
      - name: Create a new tag (Expect commit SHA to match with that of main branch)
        run: |
          git tag "${{ github.ref_name }}"
          git push origin "${{ github.ref_name }}"

Will update PRs after lunch.

[bobleesj]

@sbillinge - closing this PR, tag creation/deletion is handled by release-scripts..