I need to cite a specific revision of CABLE-POP for an upcoming publication.
I used the revision #1ad0998 which is on the BLAZE_9184 branch and provided the following link https://github.com/CABLE-LSM/CABLE/commit/1ad0998.
Reviewers are asking for a stable version, but perhaps instead we can provide a tagged version? Is that possible - or what is the recommendation in this case?
Thanks.
Until the various CABLE development branches are merged, we could allow tagging of specific commits that are used for publications? Perhaps a tag with some identifier for the publication (does it get a DOI while in review)? I wouldn’t consider anything originating from the CABLE-POP_TRENDY branch to be a stable version, but the tag may be sufficient for the reviewers.
Yes I think the idea of a tag has been posed before - I’m not really familiar with how they work, but in the absence of stable releases maybe that is the best option?
The publication doesn’t get a DOI until its accepted I don’t think. But there will be a doi provided by the CSIRO DAP when I prepare the associated data and scripts which is required prior to resubmission. Using that DOI does makes sense since the CABLE software directly associated with that data.
@AlisonBennett , I would go with a tag. Now the question is which tag? For releases of CABLE, we will (likely, still need feedback) go with a CalVer type. That looks like this: YYYY.MM.xx, or year and month the tag is created (4 and 2 digits), then an increasing number starting from 1 to indicate the number of releases within the same month.
In this case, we could maybe add a “pub_” prefix to indicate it isn’t a stable version but just a tagged version for publication. So for you, it would be “pub_2026.05.01”.
Anyone with a better idea? I would prefer the tags to follow a common pattern to understand they are needed for publications and need to be kept. And then we can add a ruleset on this tag pattern so they are not moved or deleted.
@AlisonBennett , to add a tag, use git tag -a pub_2026.05.01 1ad0998 -m "Message here" in your local repository. The message is optional (if not using the -a option) but it would be useful to have to identify who needs the tag and what for.
To push the tag to the CABLE repository on GitHub, git push origin pub_2026.05.01.
I think using a CalVar here opens up the possibility of duplicate tags? What happens if someone tries to push a tag with the same name to the repo?
It gets rejected and they have to change their tag locally. Especially if we put a ruleset on we can prevent them doing a force push.
We can have some docs that tells people to go and check the list of tags before creating theirs. I know we could become very busy and have people creating the same tag at the same time. But the likelihood of that is so limited, it’s not worth worrying about it.
@clairecarouge Okay, tag it is. I’m happy to go with whatever the common pattern you decide on. A couple of thoughts on this convention though.
But, happy to go with whatever you decide.
That’s going to be the same with stable releases. I don’t have a problem with that considering it will be part of the paper. That is, the tag shouldn’t be a way to discover publications. The publication has the information to identify the code version. So it’s a one-way discovery path, which is fine.
About adding the name of the journal, is there any chance a same commit might be used for several publications in several journals? In that case, you want to use a single tag and not one per publication, so adding the journal name would be weird.
In short the tag should simply say: “this code version has been used in one or more publication. Work towards the first publication started at this date”. Obviously, the work on the publication may have started a lot earlier but the date is mainly here to have a better identification than 1, 2, 3, …
Hmm, yes two good points. There is excellent chance that same commit is used in more than one publication and the date doesn’t really matter. Just a way of generating a meaningful UID really.
See that is why you the boss 
Thanks, but not everyone is convinced. There are a few internal discussions here about the format of the tag. One sticking block is whether we want a pattern that looks way more different from CalVer so there is no confusion on what is an “official” release and what is a version used in a publication. We’ll let you know once we have landed on something we all agree on.
Goodo. Whatever you decide, I suggest to keep it simple so that boffins like me who create the tags get it right!
@AlisonBennett , we decided! But we also decided to restrict the tag creation to the repository admins. It’s mainly because we will restrict the deletion of these tags to admins, so restricting the creation means admins only have to clean up their own mistakes.
The decision is to use pub-SHA where SHA is the short commit hash (first 8 characters). It was decided that using the date would make it too much like a full release.
Anyway, we will create the tag for you tomorrow morning (because it’s a bit late now). I’ve already set the rules on the repository to restrict creation and deletion.
@clairecarouge, that’s a good way of creating a UID but also keeping it separate from the full release. I appreciate your working through this. Thanks.
@AlisonBennett can you send me the title of the paper please? If I have it when creating the tag, then, I don’t have to update the tag a few days later.
@clairecarouge the title of the paper is:
“Source or Sink? Precipitation shapes future terrestrial carbon uptake in Australia”
@AlisonBennett , your tag is ready: Release pub-1ad09981 · CABLE-LSM/CABLE · GitHub