Branch tag naming convention

[billsacks]

What convention should we use for naming cime branch tags - by which I mean tags that aren't on one of our "main" branches (master, maint-5.6, etc.)?

I would propose using tags like this:

branch_tags/cime5.7.9_a01

This would be a tag of a branch off of cime5.7.9. If another tag is needed that follows on from this one, it would be called:

branch_tags/cime5.7.9_a02

If, on the other hand, a completely different branch is needed off of cime5.7.9, then it would use a b rather than an a:

branch_tags/cime5.7.9_b01

Here is an example commit graph:

        F--G
       /
A--B--C--D--E
       \
        H

In this example, the center line is master, commit C is cime5.7.9, F is branch_tags/cime5.7.9_a01, G is branch_tags/cime5.7.9_a02, and H is branch_tags/cime5.7.9_b01. Here there is a tag for each commit, but that wouldn't need to be the case.

Some key points of this suggested naming convention are:

• It puts branch tags in their own name space so they aren't listed alongside the main cime tags.

• It does not attempt to give a descriptive name to the branch. I often find that, once I have created a branch tag for one purpose, the next tag on that branch is for a completely different purpose. Instead, the purpose of each tag should be stated clearly in the commit message for that (annotated) tag.

• It has numerical increments for changes along a given branch.

• It provides for the possibility that there might be two completely different branches off of the same cime master tag (via the a/b distinction). (In practice this will probably be rare, but I wanted to accommodate that possibility.)

Do others like this convention, or would you propose something different?

(This is a follow-on from the discussion in #1465 . Many people in CSEG don't like the convention that I proposed in the last comment there, so we're looking for something different.)

[rljacob]

If its not a maintenance branch or master, then it must be a feature branch. Tagging commits on feature branches is fine. Its good to keep those tag names separate from the main tags.

What if the feature branch starts from a commit that wasn't tagged? How then would a commit on that branch be tagged?

This would require people to keep the tag name space updated so you know if you need to add an a or b in the tag name.

In E3SM, we prepend any feature branch tags with the name "archive". Then its the group that wanted the tag, then some other description. There's no attempt to sequentially number tags on the same branch since we didn't think this would be a regular thing.

[mvertens]

@billsacks - thanks for putting this proposal together. I think what you are suggesting sounds very reasonable and like a good step forwards.

[billsacks]

@rljacob - thanks a lot for your thoughts. See replies below.

What if the feature branch starts from a commit that wasn't tagged? How then would a commit on that branch be tagged?

Good question. I'd propose using the last cime master tag in the name of the branch tag. In either case, the tag name used in the branch tag says, "This branch tag is based off of cimeX.Y.Z with some extra commits added on top" – it's just that some of those extra commits might actually be on master. So this would give a general indication of what cime tag you're close to, but can't be relied on to give the merge-base of the branch and master (use git merge-base if you want that).

A related question is: What if we find we need a tag of master in between two existing tags? e.g., we have cime5.7.9 and cime5.8.0 and we want to tag something on master in between those two. I'm not sure what to do in that case. An initial thought would be to use cime5.7.9.1. But what if we then need something between cime5.7.9 and cime5.7.9.1? So maybe we should use cime5.7.9.5, which is a bit awkward but gives us some wiggle room before and after if needed. I'm open to suggestions here, or we can cross that bridge when we come to it.

This would require people to keep the tag name space updated so you know if you need to add an a or b in the tag name.

I'm not sure what you mean by this. All tags would be pushed to ESCMI/cime; wouldn't that "keep the tag name space updated"?

In E3SM, we prepend any feature branch tags with the name "archive".

I'm not tied to branch_tags/, so am open to using any other prefix you or others prefer. (Though I don't understand why archive makes sense in this context.)

Then its the group that wanted the tag, then some other description.

We originally proposed tagging these with the group that wanted the tag (see discussion in #1465 ), but many members of CSEG didn't like that, because it can happen that one group wants the tag then other groups want to use the same tag, and people understandably found that confusing. And I have mentioned above why I stayed away from trying to include a description in the tag name. Sorry, I can't tell if you're making suggestions for what we do in cime or just providing some background information; if the former, feel free to argue your points further.

There's no attempt to sequentially number tags on the same branch since we didn't think this would be a regular thing.

This is very common for us with cime branch tags.

[billsacks]

Having not heard any objections to my proposal, I'm closing this discussion as resolved.

[rljacob]

Wait!

What if we find we need a tag of master in between two existing tags? e.g. we have cime5.7.9 and cime5.8.0

Semantic versions says you go from 9 to 10,11, 12 etc. So cime5.7.10 would be created. I feel strongly about this.

Though I don't understand why archive makes sense in this context.

One of the git guides says "tags make commits reachable". They protect commits that are off on feature branches from getting garbage collected. So kind of like archiving them.

If the tag name and branch name doesn't have enough info to tell what is going on, you could add it to the tag annotation (git tag -a). It should be possible for someone to figure out what that branch and its tags were for just be querying the git log.

[rljacob]

If you had cime5.7.8 and cime5.7.9 and wanted a tag in between, semver says to use pre-release identifiers with the latter tag. A dash has to follow the tag name. So in-between ones could be cime5.7.9-beta.1 or cime5.7.9-0.0.1 "Pre-release versions have a lower precedence than the associated normal version."

[billsacks]

What if we find we need a tag of master in between two existing tags? e.g. we have cime5.7.9 and cime5.8.0

Semantic versions says you go from 9 to 10,11, 12 etc. So cime5.7.10 would be created. I feel strongly about this.

Sorry, that was a bad example on my part. We happened to go from cime5.7.9 to cime5.8.0 for intentional reasons, but in general I completely agree that we should go from 9 to 10 in the main tagging.

Thanks for your explanation of "archive". That makes more sense now. Again, I'm not clear on whether you're arguing for archive/ over branch_tags/ for cime; I'm fine either way.

Regarding in-between tags: Of the two options you give, I prefer cime5.7.9-0.0.1, though honestly they both seem needlessly more complex than something like cime5.7.9-1. But all of those beg the question of what you would do if you later needed a tag between cime5.7.9 and cime5.7.9-0.0.1: would you make cime5.7.9-0.0.2, living with the fact that the 0.0.2 tag comes earlier in history than 0.0.1?

[rljacob]

Those were just a couple of examples from semver. I think we can put anything after the dash. What is forbidden is adding another ".N". So no 5.7.9.1.

In your example, if you need to put a tag before cime5.7.9-0.0.1, make it cime5.7.9-0.0.1-01. Keep adding dashes to indicated its prior to the tag ahead of it in the git log. I'm really not worried about this. normal version tags on master or maint are supposed to be planned. There is a reason hashes between the normal tags were not tagged and I don't think we're going to have a ton of cases where we need to tag hashes like this.

[billsacks]

@rljacob I have taken a stab at documenting these conventions here: https://github.com/ESMCI/cime/wiki/CIME-Tag-Naming-Conventions . If you're happy with what I've written, then can we close this issue? Alternatively, we can continue to iterate on this if you don't feel I have captured this correctly.

[jedwards4b]

@billsacks thanks for the wiki page, I think that will be a great help in consistency moving forward.

[billsacks]

Closing this issue since it is now documented on a wiki page.