How can I automatically update Perl modules' $VERSION with Git?

Question

Let's say, a team of programmers is doing a web application in Perl and uses git to host their code. Now they have a small problem with versioning their modules:

• Perl::Critic and PBP both recommend a RCS-backed $VERSION variable in code
• git explicitly recommends against using replaceable revision numbers in code (with good reasoning)

I understand why git doesn't do keyword expansion. However, I can perfectly understand the need for revision numbers for a bit of code:

• You do need a separate versioning for each module, since you might want to use versioned use
• You probably don't want to change those version numbers for rapidly-changing module manually

A global product version for packaging and testing can be easily implemented with tags and git describe, but I still don't see a way to introduce automatic versioning for single modules.

Do you have any solution for me?

Answer 1

Forget what Perl Best Practices says. It's not the bible, and it merely suggests using RCS keywords because at the time it was written no one was thinking about other source control systems. Your goal should never be compliance with PBP's particular implementation, but adapting the ideas in PBP to your own situation. Remember to read the first chapter of that book.

First, let's fix your assumptions:

1. You don't need a separate version for each module in a distribution. You only need to give each module file a version that is different from that in previous distributions. Every module in the distro can have the same version, and when they do, they can all still be greater than the version from the last distro.

2. Why not change the versions of a rapidly changing module manually? You should have defined points where your code becomes something that people can use. At those points, you do something to say that you've made the decision that your work product should be distributed, whether as a test or stable release. You change the versions as a way to tell people something about your development. When you let the source control system do that merely because you committing, you're losing your chance to denote cycles in your development. For instance, I typically use two place minor releases. That means I get 100 releases before the collating goes out of wack and I need to bump the major version to restore a proper sort order. That's not enough version space if I let the VCS handle this for me.

I used to use RCS keywords to link the versions of my modules to their checkin or revision number, but I never really liked that. I make many commits to a file before it's ready to be the next version, and I don't need $VERSION changing merely because I fixed a documentation typo. There would be big jumps in version numbers because I had made a lot of little changes.

Now I just change the versions of all of my module files when I'm ready to release a new distribution. I use the ppi_version to change all the versions at once:

ppi_version change 1.23 1.24 

All of my module files get the same $VERSION. I don't need to use $VERSION to tell them apart because I use normal source control features to do that. I don't need $VERSION to tie it to a specific commit.

If I'm working toward a new distribution from version 1.23, I start making development versions 1.23_01, 1.23_02, and so on, but only when I'm ready to let people try those versions. I change the version at the start of the cycle, not the end. All of my commits leading up to the next release already have their next version. I also make notes about what I want that cycle to accomplish.

When I think it's the start of a new cycle, I bump the version again. When I think I have a stable release, I change the development $VERSION to a stable one, like 1.23_04 to 1.24. Whenever I release something, I tag it in source control too. I can see where my major points of development line up with source control quite easily.

Everything is much easier this way for me. Nothing is tied to the source control that I decide to use, so I don't have to redo everything if I change what I use.

Answer 2

I'd go for manually bumping versions when introducing incompatible changes, because, certainly not every change justifies the bump.

You may also want to checkout the 'gitattributes' manpage for the filter attribute — perhaps you will want to introduce your own filter for doing the substitutions based on 'git describe' output automatically.