NSH SFC/Pushing and Testing a Tag

Intro

The nsh_sfc 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

nsh_sfc branching structure currently is:

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

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

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

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

----------- master ------------------------------------------------------------------------>
                                 \                                                             \
                                  \------ stable/1609------->                \---------stable/1701----->

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 17.01 is to be 17.04, then the tag set on master after the pulling of stable/1701 would be v17.04-rc0
• If the next release is 17.04 then the first tag on the branch stable/1701 should be v17.01-rc1
  • Note: that first tag on stable/1701 should be set on the first commit to stable/1701 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/1701).

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/1701

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/1701 for RC2 (signed):

git tag -s v17.01-rc2 -m "Version 17.01-rc2"

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

git tag -a v17.01-rc2 -m "Version 17.01-rc2"

== Test locally using build-root/scripts/version ==

First verify your tag is as you expect it:

git show ${tagname}

Example:

git show v17.01-rc2

Then run

build-root/scripts/version

which should return

${tagname suppressing the leading 'v'}

In our example:

17.01-rc2

Push the tag

git push origin ${tag}

Verify the tag remotely

1. Check in git.fd.io to make sure the tag appears.

1. After the next patch merges on the branch to which the tag was applied, go look in
   1. https://nexus.fd.io/content/repositories/fd.io.${branchname with dots instead of '/'}.ubuntu.trusty.main/io/fdd/nsh_sfc/nsh_sfc/ to make sure you see patches with the new version.