Should we specify the format for versions?

[davegraham92120]

The current example includes:
@version 1 intial working rev

Should we include the date and a list of changes in a consistent way, or just include after version number?

Should we adopt/recommend a specific version methodology?

Go!

[jbante]

Here's an exercise I'm trying to do more often that might inform an approach: Try implementing the next feature in an app that doesn't use the practice you're thinking about adopting. If the practice is worthwhile, something will be a pain in the ass. What information do you find yourself looking for?

My own experience has been that a complete listing of the version history and changes made to a script in a header comment mostly just takes up space. It's satisfying to be comprehensive while making a change, but I just never find anything useful when I actually read it. I find SeedCode's approach increasingly compelling.

Version numbering: What do we gain by different apps (especially written by different groups) using the same version numbering scheme? Do we need more information than (1) distinguishing between different versions of the same thing and (2) what order they go in (which one is current & stable or alpha/beta)? The benefit within an app and within a workgroup with a consistent workflow is obvious enough. If you do want to recommend one, there are plenty of methods. I think 3 of them make sense:

• Major.Minor.Patch ("Semantic Versioning", popular, but doesn't actually work when you want to treat it like a number directly.
• Serial numbering: just move up to the next integer for each version. It's less informative, but it covers the most important information (order), and there's no room for interpretation or ambiguity about what the next number should be.
• The date is the version number. The date the code is written and the date the code is released are both plausible candidates.
  I prefer either of the latter 2, but I don't have any particular preference between them at the moment.