VPP Pushing_and_Testing_a_Tag

Contents

• 1 Intro
• 2 Considerations when laying a new tag
  • 2.1 Branch structure
  • 2.2 How git describe picks versions
  • 2.3 Format of tags
• 3 Mechanics of Tagging
  • 3.1 Identify the commit you wish to tag & Check out that commit
  • 3.2 Lay the annotated (and preferably signed) tag locally
  • 3.3 Test locally using build-root/scripts/version
  • 3.4 Push the tag
• 4 Deleting A Tag
  • 4.1 Remove the local tag
  • 4.2 Remove the remote tag

Intro

The vpp package builds utilize

git describe

to construct the versions for Ubuntu and Debian packages built. This is done by the

build-root/scripts/version

script. Because of this when we want to change versions, we need to lay a tag, and then test to see that what we expected to happen happens.

This page covers how to push and test a tag on existing branches, it does *not* cover pulling new branches.

Considerations when laying a new tag

Branch structure

vpp's branching structure currently is:

----------- master ---------------------------->
                                 \
                                  \------ stable/1606------->

The master branch is where the bulk of development takes place.

The stable/1606 branch is the 'throttle' for preparing the 16.06 release. Only bug fixes should go into stable/1606.

It is expected that we will in the future carry forward a similar structure, example:

----------- master ------------------------------------------------------------------------>
                                 \                                                             \
                                  \------ stable/1606------->                \---------stable/1609----->

How git describe picks versions

git describe walks back through the history of the specified (in this case current) commit till it finds a tag. If two or more tags are found on that commit, it will pick the newest tag. (note: its more complicated than this in corner cases which we should not hit, feel free to read the git describe manpage.

Format of tags

1. Tags are to be annotated (and preferably signed)
2. Tags are of the format "${next release version for this branch}-${optional rc}"
3. ${next release version for this branch} for a "stable/${YY}${MM}" branch is "v${YY}.${MM}"
4. ${optional rc} is of the form rc0 (note lower case rc) on master
5. ${optional rc} is of the form rc1 or rc2 (note lower case rc) on "stable/${YY}${MM}" branches

Examples:

• If the next release after 16.06 is to be 16.09, then the tag set on master after the pulling of stable/1606 would be v16.09-rc0
• If the next release is 16.06 then the first tag on the branch stable/1606 should be v16.06-rc1
  • Note: that first tag on stable/1606 should be set on the first commit to stable/1606 that is *not* a commit on master. This is to avoid issues with mis-picking of tags if both are on the same commit (one shared between master and stable/1606).

Mechanics of Tagging

1. Identify the commit you wish to tag & Check out that commit
2. Lay the annotated (and preferably signed) tag locally
3. Test locally using build-root/scripts/version
4. Push tag to gerrit
5. Verify the tag remotely

Identify the commit you wish to tag & Check out that commit

Typically (but not always), you will want to check out the HEAD of the branch you are laying a tag on.

Example:

git checkout stable/1606

and make sure its up to date:

git pull

Lay the annotated (and preferably signed) tag locally

If you are going to lay a signed tag:

git tag -s ${tagname} -m ${tag annotation}

If you are going to lay an unsigned annotated tag:

git tag -a ${tagname} -m ${tag annotation}

Examples:

For a tag for stable/1606 for RC2 (signed):

git tag -s v16.06-rc2 -m "Version 16.06-rc2"

For a tag on stable/1606 for RC2 (unsigned):

git tag -a v16.06-rc2 -m "Version 16.06-rc2"

Test locally using build-root/scripts/version

First verify your tag is as you expect it:

git show ${tagname}

Example:

git show v16.06-rc2

Then run

src/scripts/version

which should return

${tagname suppressing the leading 'v'}

In our example:

16.06-rc2

Push the tag

git push origin ${tag}

Deleting A Tag

NOTE: this is an "emergency" procedure and only recommended if necessary (like in the case of a release where there is a commit required after the release tag was created). If you need to move a tag forward, simply delete the existing tag, then create the new one per the above Mechanics of Tagging procedure.

Make sure to delete tag from both the local and remote repo.

Remove the local tag

git tag -d <tagname>

Remove the remote tag

git push origin :refs/tags/<tagname>

The above procedure most probably will not work with Gerrit, with the following diagnostic:

ubuntu@vpp-dev:~/vpp$ git push origin :refs/tags/v20.09
Username for 'https://gerrit.fd.io': ayourtch
Password for 'https://[email protected]': 
remote: error: branch refs/tags/v20.09:
remote: You need 'Delete Reference' rights or 'Push' rights with the 
remote: 'Force Push' flag set to delete references.
remote: User: ayourtch
remote: Contact an administrator to fix the permissions
remote: Processing changes: refs: 1, done    
To https://gerrit.fd.io/r/vpp
 ! [remote rejected]     v20.09 (prohibited by Gerrit: not permitted: delete)
error: failed to push some refs to 'https://gerrit.fd.io/r/vpp'
ubuntu@vpp-dev:~/vpp$

If that happens, go to gerrit GUI listing the tags here: https://gerrit.fd.io/r/admin/repos/vpp,tags - you should have the permissions to delete the tag from the GUI. Wait for the git.fd.io to show that the tag has disappeared, to ensure no inconsistencies for the jobs.