Revamping Branch/Tag naming conventions - our ONE chance for a clean switch!

sdboyer's picture

The branch and tag naming conventions are kinda old and crusty. Thanks to a feature of the migration script we'll be using to move to git, we have the option of changing our branch and tag conventions, and renaming all of the old crusty ones at the same time. That means we could actually do a clean migration to a new naming convention - and that we'll probably never, EVER have another opportunity to do so.

So if you think we should switch up the naming system, speak up! Let's start with something simple: GET RID OF THE 'DRUPAL-' PREFIX ON ALL BRANCHES AND TAGS.

Discuss :)

Comments

Yes, please -- but all the way: tags should match releases

dww's picture

This is already proposed at Prototype: Git reference guide for module maintainers. I think it's a lovely idea. I'd much rather see our branches and tags as closely as possible match the version strings of the releases associated with them. The only reasons we have our existing conventions are:

A) legacy goo from random decisions made 8 years ago (e.g. "DRUPAL-*" in a Drupal-specific repository seems redundant).

B) the technical limitation that CVS tag names (and therefore branch names) can not contain periods.

Since we're already moving to Git, and since we're already going to have to update all the documentation, and everyone is going to have to learn new commands to do everything, we might as well fix this while we're at it. We're not going to get another good chance for this. I think it'd be a win for self-documenting names and less confusion if the branches and tags were named exactly what the releases were, instead of having to do the weird mapping that both humans and code have to do now.

Instead of "DRUPAL-6--2" == 6.x-2.x-dev, let's just call the branch 6.x-2 or 6.x-2.x or 6.x-2.x-dev. (I'm not exactly sure which I prefer, I guess by my own argument, it should be "6.x-2.x-dev".

For tags, it seems obvious -- the tags should exactly match the release versions strings, e.g. 6.x-2.0-alpha2 or 6.x-2.1. I see no reason at all to have any convention beyond our version string naming convention.

I still think it'd be worth forcing release tags to match our version string conventions, e.g. to enforce only -(unstable|alpha|beta|rc)(\d+) for releases with "extra", etc. But, we should probably allow other, non-release tags if people want to use them (they just won't show up as available tags to create release nodes from)...

Plus eleventy billion!

webchick's picture

If branches and tags exactly matched the file names of the release tarballs, that would save us from so many support requests, not to mention would allow us to remove several reams of severely confusing documentation. Yes, yes, yes, please!

I also like the idea of enforcing our existing branch/tag naming conventions and not allowing a whole lot of creativity here. The system is predictable and works well (once you remember for the 11th time that it's alpha2 and not alpha-2). The only potential downside of this is that I don't know how that would work for the dww-project-issue-views-hackathon feature branch of views. But I guess that question remains to be answered over in the sandbox thread, and might end up being git.drupal.org/sandbox/dww/dww-project-issue-views-hackathon, in which case our naming conventions wouldn't really matter at all.

version string, not full release tarball names

dww's picture

Part of what annoys me about our CVS conventions, the big nasty "DRUPAL-" in front of everything, is that, well, duh, we already know it's Drupal. It lives at cvs.drupal.org. Similarly, I wouldn't want to duplicate the project short names in the branch or tag names, since you'll also already know exactly what project it is based on the repo. If the repo itself is: git://git.drupal.org/contributions/modules/views.git (or whatever), it's pointless for the tag names to be views-6.x-3.0-alpha3 (even though we definitely want that to be the basis for the tarball filename). I'm just proposing that the branch/tag match the version string portion of the release filename, which is the same value you see in the issue queue, etc. So, in the above example, just 6.x-3.0-alpha3. Make sense?

Sorry! That's what I meant...

webchick's picture

Right, that's what I meant: "6.x-3.0-alpha3". And "6.x-2.x-dev". As opposed to "6.x-2" or "6.x-2.x" or some other variation. Make it match what's going to be on the download link. :)

Yay, agreed ;)

dww's picture

Cool. Great minds think alike... ;)

can we drop the .x now?

adrinux's picture

Drupal core obviously still needs 6.x- to account for point updates. But unless I'm missing something pretty much all contrib modules just have 6.x.-2.1 or similar. They're never tied to a specific core point update, just to the major version (even if they need a core update to work around a bug I don't think I've ever seen that point release being used).

So can we consider a different release tag structure for contrib? 6-2.1, 7-1.0 and so on? That .x just seems superfluous.

Or is there something I'm missing?

The point of .x and why we should keep it

dww's picture

.x isn't about Drupal 4.7 -- the earliest releases with called 4.7.x-1.0 or even 4.6.x-1.0...

the .x is about the fact that a given release of contrib, say views 6.x-2.8, is compatible with all versions of core 6.x, whether it's 6.0 or 6.15.

this has nothing to do with CVS.

this was all debated at length when the "new" [sic] release system was being developed and deployed. sorry, I don't have any links handy now and it's late (and frankly, not that important)...

at this point, I think changing the tags to match the version strings makes loads of sense, but changing the version strings themselves is going to be far more trouble than it's worth.

Fair enough :)

adrinux's picture

Fair enough :)

The .x, as I understand it,

sdboyer's picture

The .x, as I understand it, has a lot to do with backwards-compat for the pre-D5 days, so that our version numbering can recognize 4.6, 4.7, and 5(.x) all as discrete major versions.

If we were to do more than just the prefix, then that's the next thing I'd want to target. However, I suspect that changing that could potentially invalidate a LOT more than just dropping the DRUPAL- prefix - it's such shorthand, and used ALL over the place on d.o (in official places and otherwise), that it could get really ickysticky.

History

adrinux's picture

Yeah, I realise it has some historical significance :) And while we are still using CVS it makes sense, my assumption was that it could be worked around in the move to Git.

I didn't take into account all the stuff outside the VCS though, which is a good point.

On more thought on .x

adrinux's picture

Is it all feasible to bring across the old tags using .x into git, but drop it moving forward?

...Maybe I'm only worrying about this because I find 6.x-2.1 or whatever a pain to type, I'm always making mistakes :) I even managed an extra . in my earlier comment :(

Pretty much any structured

sdboyer's picture

Pretty much any structured transformation of the branch/tag names should be possible. The big question is what those changes will require in terms of making everything still work: Since we're going to be migrating EVERYTHING, not just leaving legacy in CVS, it means that whatever system we come up must still still be able to generate tarballs and do project status for the DRUPAL-4-7 equivalent. As for just switching moving forward? Hmm...maybe. It'd probably mean using two different parsers, or something. But I'd have to think, and dww could probably comment more intelligently.

Ship it? ;)

webchick's picture

Sounds like we have reached consensus here.

Old branch name: DRUPAL-6--1
New branch name: 6.x-1.x

Old tag name: DRUPAL-7--1-0
New tag name: 7.x-1.0

Old tag name: DRUPAL-7--1-2-alpha2
New tag name: 7.x-1.2-alpha2

Yes? If so, we can probably move this back to the infrastructure queue as an actionable task.

Looks good to me. While it'll

sdboyer's picture

Looks good to me. While it'll probably take a little doing when it comes to project*, it won't be more than a single line in the cvs2git config to make this actually happen :)

Should branches include "-dev" or not?

dww's picture

Re:

Old branch name: DRUPAL-6--1
New branch name: 6.x-1.x

That contradicts what you wrote earlier:

Right, that's what I meant: "6.x-3.0-alpha3". And "6.x-2.x-dev". As opposed to "6.x-2" or "6.x-2.x" or some other variation. Make it match what's going to be on the download link. :)

So, which do you want? ;)

Bah! :)

webchick's picture

-dev. :)

I think that 6.x-1.x is much

Hugo Wetterberg's picture

I think that 6.x-1.x is much cleaner than 6.x-1.x-dev, the -dev is kind of redundant

The -beta1, -unstable5 and so

Hugo Wetterberg's picture

The -beta1, -unstable5 and so on, only makes sense for the tags, as they represent a release. The version branch doesn't.

We have dev builds, so I

Dave Reid's picture

We have dev builds, so I think it does make a ton of sense to make our branch tags with '-dev'

Senior Drupal Developer for Lullabot | www.davereid.net | Gittip me!

Yes, we have dev builds. But

Hugo Wetterberg's picture

Yes, we have dev builds. But the branch doesn't represent the dev build. The primary reason the branch exists is to be the HEAD for the 6.x-2.x version of a module. Then dev snapshots might or might not be created for this HEAD.

My semi-noob perspective here

yoroy's picture

My semi-noob perspective here is that the '-dev' part clearly communicates 'use at your own risk, not production ready etc.' I think there's value in keeping that. It might just save module maintainers a couple of issues in their queues (the "My site exploded because of your crap module!!11 plz fix asap kthxbye" ones).

Yeah, the -dev part makes

Hugo Wetterberg's picture

Yeah, the -dev part makes sense for the release, which the noobs probably will go ahead and download anyway, and still be angry for the exploding site. But hopefully those who actually clone the git repo will know enough to know that they're not using a official release.

To me it makes much more sense that if you want to check out what's being done in version 6.x-2.x of a module you actually check out the branch 6.x-2.x. If you want to check out the 7.x-2.1-rc2 release you check out the tag 7.x-2.1-rc2.

Yeah, I'm not particularly fussesd on this point...

webchick's picture

I could go either way. The nice thing about keeping -dev is the name always matches what's on the tarball so our documentation can be consistent. But the distinctions between branches vs. tags makes sense, and from a developer POV, -dev is just extra typing.

IMO, dww, just make a call. ;)

well, bash-completition

CorniI's picture

well, bash-completition supports git, so you can just hit tab and it will auto-complete branch/tag names :D

It's still kinda ugly and

Hugo Wetterberg's picture

It's still kinda ugly and superfluous. I'm just nagging about this because I know that the -dev suffix will bug me almost as much as the DRUPAL- prefix. Of couse it's Drupal, it's at drupal.org; of course it's a development branch, branches are for development.

Naming branches: use "-branch" ?

dww's picture

Clearly, we're all in agreement that release tags should exactly match the version string the release corresponds with (6.x-2.0, 6.x-3.0-alpha2, etc). So, the only open question here is what to call branches.

I agree we don't want "-dev" for the following reasons:

A) It's not necessarily true -- not all branches are being "developed" at all times.
B) It's not necessarily any more self-documenting.
C) We've survived for years where the branch names don't match the version strings, so it's not a regression if we continue to name them differently (if there are good reasons to do so).

However, I'm not sure we just want to call them "7.x-2". I'm open to that, but my counter proposal is to actually put "-branch" in there. We did this in the repository where I worked for many years before coming to Drupal, and I think it was helpful. You always saw explicitly that your workspace or the command you were running was operating on a branch, not a release tag. So, I'd like to propose that contrib branches that look should like this:

7.x-2-branch

Yes, you have to type out that "-branch" all the time, but I think that's a lot more helpful and self-documenting and clear than having to type out "DRUPAL-" all the time. ;) I won't fight this. If there's a major outcry and backlash, we can just go with "7.x-2" for contrib branch names.

Core branches would be:

7.x-branch

Or, if there's backlash against "-branch", just "7.x".

Regardless, the release nodes pointing to contrib branches should still be "7.x-2.x-dev" -- the ".x-dev" part is important to document to end-users "unknown crap, stay away".

When we first did this, I

merlinofchaos's picture

When we first did this, I argued that they should be -nightly because that most closely describes what they are: regular rebuilds of the branch, and thus it's easier to explain what that really means.

Other systems I have seen usually embed the date in the filename, too, so you'd get project-X.Y-ccyymmdd-nightly.tar.gz or something along those lines.

ugh, please not just ".2"

webchick's picture

If we want to save typing, then let's leave it at "7.x-2.x," please.

a) It wouldn't invalidate approximately 80 gazillion pieces of documentation that mention ".x" means "everything under that release."
b) It matches fairly well to what shows up for the end user so it's clear what's being talked about. 7.x-2 or 7.x-2-branch doesn't, and it's something "special" a developer needs to know and breaks down communication between end users and devs.
c) It's visually more balanced and that makes me happy. ;)

On merlinofchaos's point, I'd be fine if the tarballs were generate as -nightly or something instead of -dev, but that's not really related to branch names.

"7.x-2.x" is fine, but what about -branch?

dww's picture

Sure, we can stick with "7.x-2.x" instead of "7.x-2".

But neither of you actually responded to the main point of my comment. ;)

What about "7.x-2.x-branch" for the branch name?

Thanks,
-Derek

Well, the -branch naming

Hugo Wetterberg's picture

Well, the -branch naming feels pretty unnecessary. Especially considering that it will be obvious from the version number whether it is a branch or not. Also because feature-branches probably (I hope) won't be ending with -branch.

...and I don't really see the

Hugo Wetterberg's picture

...and I don't really see the problem that explicitly naming branches as -branch(es) would be the solution to. Of all the people I've helped and supported while they were learning git, nobody has had any problems differentiating branches from tags.

I don't really understand the point...

webchick's picture

The "2.x" at the end implies branch/dev release enough by itself, IMO.

Otherwise we'd have to do something like 7.x-2.x-branch and 7.x-2.1-alpha2-tag to be consistent, and ick. :P

I'm with 7.x-2.x (same as

marvil07's picture

I'm with 7.x-2.x (same as webchick)

You always saw explicitly that your workspace or the command you were running was operating on a branch, not a release tag.

I just want to add that git will notify you if you try to git checkout sometag it will print you:

Note: moving to 'sometag' which isn't a local branch
If you want to create a new branch from this checkout, you may do so
(now or later) by using -b with the checkout command again. Example:
  git checkout -b <new_branch_name>
HEAD is now at <sha1>... <the commit log summary of the sha1>

So, that could be a good reason to avoid worrying about it.

This wasn't clear to me from reading the post...

webchick's picture

But apparently this has been officially decided by our official decider. :)

New core tag convention: 7.1
New core branch convention: 7.x
New contrib tag convention: 7.x-2.0
New contrib branch convention: 7.x-2.x

Hooray!

useful story

nevergone's picture

A very useful story: A successful Git branching model

Issue tracking and software releases

Group organizers

Group notifications

This group offers an RSS feed. Or subscribe to these personalized, sitewide feeds:

Hot content this week