WordPress, Git, PHP and Rockstar version numbers

Most of us developers have one or multiple plugins or themes in the public and free wordpress.org repository. One of the nice features of this repository is the automated update notification that tells a user right inside her/his admin user interface that there’s an update available and that it should get installed. The internals of WordPress work (simplified) this way: The WP core does a HTTP request to the wp.org servers every hours and then does a check if there’s a version with a higher version number available. If so, the user gets told that s/he can update the plugin or theme with a simple mouse click.

Now most of us also have their plugins hosted on GitHub for multiple reasons: simpler handling, web view with a nice syntax highlighter, the possibility to use git submodules, etc. And at least, as explained in another article, the wp.org repository is only meant for distribution and not for development.

And here come git tags into the game. Tags in git serve a simple purpose: It allows us to snapshot our code history. Or, in other words, we can set milestones. This means we don’t need to remember when we decided to release our code as a new version that our users can install/update to, as searching and remembering where exactly we released a version is hardly possible. So let’s get to the basics of (commented) git tags. Note: You can add tags at and to any point of your commit history.

# First we want to check our commit history
git log --pretty=oneline
# We need to take the 7 first characters of our commit name
# Example: 0123e45 
# Even simpler (with less details) is using only "--oneline"
# as this only outputs the first 7 characters
git log --oneline

# To exit the log you need to hit the following keys
# ESC > ENTER > SHIFT + (2x) Z 

Now we’re ready to add the tag to your repo.

TAG NAME would be something like 1.5 and the 7 characters are the one we remembered (or wrote down) from our commit log/history.

# Lets add a tag
git tag -a [TAG NAME] [7 characters]

# In case you added a wrong tag, you can always remove it.
git tag -d [TAG NAME]

Finally we want to push them to our remote source. But before doing so, we want to be sure that we’re pushing to the right repository. To list your remote sources simply enter the following.

# Check if we got the correct remote source(s) set
git remote -v
# We can also use the slightly easier to remeber alias
git remote show

# If we got the wrong remote source, we can simply
# remove the current source...
git remote rm origin 
# ...or rename it in case or a typo
git remote rename prigim origin
# Then add a new one with the same name
git remote add origin git@github.com:your-username/your-plugin-dir.git 

Then you can push the tags to your main repository.

# List our tags to see if everything is alright
git tag -l
# If you want to be more specific and only list for e.g. tags
# that have a version number below 1
git tag -l "0.*"
# To get a list of our tags including the annotation, use "-n=INT"
# where INT is the number of lines we want to show from each tag msg
git tag -n2
# We can also combine those
git tag -l "0.*" -n2

# Push our tags to our "origin" remote source
git push origin --tags

Now you’re ready to add tags to your plugin or theme. This way you don’t have to misuse branches anymore and start using your branches for the thing they’re meant for: Trying things out and playing around.

A last note about version numbers

There are several known concepts on how to hand out numbers tagging your versions. The most common is simply version.feature.patch, where feature can be bugfixes, new features, etc. A somehow “better” is to use date and time in reverse order: 2031-04-28.1876 where the last four digits are the time. This system allows full version comparison as well as telling you when exactly you wrote an update. It also tells the user how much time is between the last and the current version. But not everybody gets that and most users will just see some long number separated by dashes and dots.

From my experience, users understand normal version numbers best and trust versions above 1.0 most. They can most likely follow the process, so a normal version numbering system is what I recommend for your releases. Hint: Never start releasing below a number of one. Users tend to not trust those.

Sometimes plugins need those version numbers themselves. The best example would be a database update task. To check if you updated from an older version and need to perform that task, you would do a version_compare(). And here goes the pro-tip: You don’t have to stick to numbers. PHP comes with an (partly) alphanumeric version numbering system. That’s the hierarchical order of strings inside version numbers:

  1. any string not found in this list
  2. dev (Development)
  3. alpha / a (Alpha state – closed test)
  4. beta / b (Beta state – public test)
  5. RC / rc (Release Candidate)
  6. # (Version)
  7. pl / p (Patch/Patchlevel)

Time to go out, release your “0.8-beta” Plugin to your beta testers group and become a Rockstar coder.