Solve release branch name issue

martriay commented 5 months ago

Right now our release process indicates creating a WIP branch for a soon to be release following the release-vX.Y.Z branch name pattern. That's the same pattern that our docsite uses to identify branches to pull from. This results in a WIP branch getting released as the latest docs, even before approving the PR and effectively releasing the version.

Since release-vX.Y.Z branches trigger deploys on a public visible site, it's a protected branch. This results in the CI version bump script to require a PAT token to automatically write a commit for the version bump.

Option 1

Make the docsite pull v* tags instead of branches
Remove the branch protection on release-v* branches

Pros: we can drop the PAT token requirement, which feels leaner although security-wise it's probably the same since the PAT is fine grained and restricted to writing to this repo only -- roughly equivalent to removing the branch protection.

Option 2

Change the release process' so that

the version bump branch name is something else than release-v*
add a release-v* branch creation step (for the docsite to pull)

martriay commented 5 months ago

I think I lean towards option 1, it feels cleaner and we can get rid of the tag vs release branch dichotomy -- only tags are relevant, release-v* branches are just an utilitiy to run the version bump workflow.

The downside is that we cannot safely push docs fixes without affecting the released tag. A potential solution to this is implementing some sort of nightly build documentation, something we've been thinking for a while even for the Contracts for Solidity docsite.

martriay commented 5 months ago

To carry on with option 1, I reviewed all (tag, release branch) pairs and this is the summary:

v0.8.1 tag vs branch: minor doc fixes
v0.8.0 tag vs branch: minor doc fixes
v0.8.0-beta.1 tag vs branch: minor link fix
v0.8.0-beta.0 tag vs branch: same contents
v0.7.0 tag vs branch: minor links fix
v0.7.0-rc.0: version already banned from antora for breaking its yml file
v0.6.1 tag vs branch all the way down to v0.3.0 tag vs branch: same commit + wizard deprecation commit
v0.2.1 tag vs branch: same commit but no antora.yml
v0.2.0 tag vs branch: same commit but no antora.yml
v0.1.0 tag has no associated release branch nor antora.yml

So I conclude it's safe to migrate to using tags for the docsite immediately as long as we ban the v0.1.0, v0.2.x, and v0.7.0-rc.0 tags. Implemented the change in https://github.com/OpenZeppelin/docs.openzeppelin.com/pull/399.

Status

[x] Make the docsite pull v* tags instead of branches
[x] Migrate tags to their corresponding release-v* branches' HEAD
[x] Add tag protection on v* tags
[x] Remove the branch protection on release-v* branches

^ i'll do the latter after merging this PR

martriay commented 5 months ago

Migrated the tags to their corresponding branch with this bash script:

retag() {
  local branch=$1
  local version="$(echo "$branch" | sed 's|origin/release-||')"

  echo "Retagging version $version to branch $branch"

  git tag -d $version
  git push origin :refs/tags/$version
  git checkout $branch
  git tag $version
  git push origin $version
}

git fetch origin

# List all remote branches that match the pattern "release-v*", then loop through them
git branch -r --list 'origin/release-v*' | while read branch; do
  retag "$branch"
done

OpenZeppelin / cairo-contracts