Ipstenu (Mika Epstein) 5:05 pm on March 16, 2021
Tags: release ( 2 ), svn ( 3 ), tags ( 4 )

Trunk vs Tags? Which is Better? (Answer: Tags)

tl;dr – We strongly recommend you use tagged folders for your releases of your plugins. Future you will thank you.

While we have always advocated for people to use a tag folder with their plugins instead of trunk, it persists that a number of developers like using the “Stable TagTag Tag is one of the pre-defined taxonomies in WordPress. Users can add tags to their WordPress posts along with categories. However, while a category may cover a broad range of topics, tags are smaller in scope and focused to specific topics. Think of them as keywords used for topics discussed in a particular post.” of trunk. There are logical reasons for this. Having your stable tag be trunk feels like it’s one less thing to keep in mind when you update your pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party for a new release.

The problem with that setup is that you suddenly made it harder for everyone else to keep tabs on your plugin, to make sure they downloaded the correct version, and worst of all … you made it nearly impossible to roll back to a previous release. And with the advent of automated plugin updates, that last one is going to be damaging to you in the long run.

In fact, here’s what you’re making worse:

No easy way to download older versions to debug compatibility issues
Translators cannot work in ‘advance’ of a release, meaning as soon as you push your code, the translations are out of date until volunteers can work on it
You increase your risk of an accidental release
No way to allow people to download the ‘pre-release’ version from official WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ sources
No ability to ‘roll back’ versions

So what’s the right way?

Make sure your readme.txt has the stable tag to your stable version in the main plugin file (those need to match)
Put everything into your trunk folder on your local checkout (use svn add and so on as needed)
Run svn cp trunk tags/1.2.3 — this will copy from trunk to the tag folder
Run svn ci -m "Releasing new version" — this will push both trunk and tag

That’s it. You’re done. Now you can upload and edit trunk all you want, for a dev version, and as long as the readme points to the proper stable tag, your users won’t get any updates.

Okay, but what if you want to have a trunk version for testing? Do not edit the stable tag in the trunk readme! It’s that value that tells WordPress which version is ‘stable’ and if you’re working on 1.2.3, keep stable as 1.2.2 in trunk and no one will get the new code until you’re ready.

#release, #svn, #tags

Arnan de Gans 5:09 pm on March 16, 2021

I don’t really care for trunk, but that’s just my workflow.
I can see the need or use for either.

For the sake of not-keeping-too-much-old-stuff you could introduce a prune function where older versions are removed from tags. Say everything older than 5 years. Or all the previous versions from a large release. So only 4.18 gets kept, but all 4.x version sbefore it get removed.
- Ipstenu (Mika Epstein) 5:16 pm on March 16, 2021
  
  As part of the ongoing ‘make the directory better’ plans, that comes up from time to time. It’s not as bad as it used to be since we don’t rebuild all the zips for every release (yes, we used to), and disk space itself is cheap. But having the ancient versions easily available could help some future dev who wants one small part of a complex pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party 🙂 There are merits to both sides of that one.
Pascal Casier 7:22 pm on March 16, 2021

@Ipstenu I’m a bit lost with “Make sure your readme.txt has the stable tag to your stable version in the main pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party file (those need to match)”
1) I thought that the stable tag in the trunk/readme.txt needed to point to the correct folder under /tags. Not sure it has anything to see with the real version you put in your plugin main file (although we all tend to keep that the equal of course)
2) It might be good to clearly indicate that especially the readme.txt in trunk needs to point to the correct version. Some put the correct stable tag in the readme.txt in the /tags folder but forget to update the trunk/readme.txt
- Ipstenu (Mika Epstein) 7:43 pm on March 16, 2021
  It’s a lot of ‘Both’ there…
  
  1. If your readme says stable is 1.4, then you use tags/1.4, and that’s a pretty obvious connection. However … WordPress itself doesn’t read your readme for the version, it reads the main pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party file. Which means if you leave the main plugin file at 1.3, and put that in the 1.4 tag folder, well you will generate a fun loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop. where people will keep updating and updating and never getting 1.4. So. If your readme says the stable tag is 1.4, then you really do need to have the plugin main file ALSO say 1.4
  
  So basically, you really do want them to match, if your goal is always getting your users the right version.
  
  2. Not really but sort of … If the trunk version is not the stable release, then you absolutely do not want the stable tag in the trunk readme to be the version you’re working on.
  
  Some put the correct stable tag in the readme.txt in the /tags folder but forget to update the trunk/readme.txt
  
  Yep, and that won’t download the new version. It’s not actually all that common a problem anymore, though (the first issue — the main file being out of sync — actually causes a lot more drama in plugins emails).
  
  It should be the same in both if and only if that really is the stable version you want to release. That one is a little more ‘it depends on your workflow.’
  
  tl;dr?
  - trunk/readme.txt controls what tag gets downloaded
  - tags/VER/main.php controls what version WP thinks you have
  - tags/VER/readme.txt needs to match main.php, but that may not match trunk/readme.txt
Aurovrata Venet 9:03 am on March 17, 2021

I use a combination of both. Every major releaseMajor Release A set of releases or versions having the same major version number may be collectively referred to as “X.Y” -- for example version 5.2.x to refer to versions 5.2, 5.2.1, and all other versions in the 5.2. (five dot two dot) branch of that software. Major Releases often are the introduction of new major features and functionality. (1.0 / 1.1 / 1.2) has a new tags folder added, every minor releaseMinor Release A set of releases or versions having the same minor version number may be collectively referred to as .x , for example version 5.2.x to refer to versions 5.2, 5.2.1, 5.2.3, and all other versions in the 5.2 (five dot two) branch of that software. Minor Releases often make improvements to existing features and functionality. (1.0.1, 1.0.2…) I put a copy in the corresponding tags folder, hence the tags folder always contains the latest minor release in that major version.

However, I stick to ‘Stable tag: trunk’ in my readme file as I develop on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ insead of SVNSVN Short for "SubVersioN", it's the code management system used to maintain the plugins hosted on WordPress.org. It's similar to git.. At times I have used the ‘Stable tag’ to point to a the last major tags folder when the next release (from going from 1.X to 2.0) has fundamental changes that can cause live plugins to break (due to too many changes in the code that presents too many permutations of testing configurations). I then go about releasing a minor release 1.X.x prior to the the next release 2.0 in order to notify website administrators that the next major release will require their attention in testing their setup, making the 2,0 version available for them to download from the official repo and test.

What would be nice is if there was a way for new downloads to get the trunk version while the live upgrades would follow the ‘Stable tag’. So new installations would get the trunk and this would allow for major releases to get tested. Currenlty, using the Stable tag to point to a tags folder means the trunk version does not get downloaded and tested, therefore delaying its roll-out.
- Ipstenu (Mika Epstein) 3:12 pm on March 17, 2021
  
  That would be nice 🙂 And it’s one of the many reasons you should never use trunk for ‘live’ 🙂 In fact! If you keep doing what you’re doing, maybe one day we’ll have a betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. test setup that’ll use it, like it does coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.!
  
  That’s my dream, nothing practical has been written that I know of to make it happen… But allowing ALL pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party devs an easy way to beta like that? Chef kiss!
Marcus 10:39 am on March 19, 2021

For those that maybe don’t want to keep a full SVN checkout on their local work folders, this command is useful:

svn cp “https://plugins.svn.wordpress.org/your-plugin/trunk/” “https://plugins.svn.wordpress.org/your-plugin/tags/1.2.3” -m “tagging version 1.2.3”

This way, I generally work off a trunk folder in wp-content/plugins, and as soon as we commit a stable update (or before we start adding stuff to a stable trunk if we forgot earlier), you tag your remote repo.
aurelienpierre 2:36 am on March 31, 2021

Any plan to support git ? svn is a mess, and pretty much all opensource plugins have some sort of git repo somewhere on /GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/.(hub|lab|*)/ where issues and development handling happens.
- Ipstenu (Mika Epstein) 9:28 pm on April 5, 2021
  
  Not at this time, but that would be a metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. (aka systems) choice. There’s a lot we rolled into SVNSVN Short for "SubVersioN", it's the code management system used to maintain the plugins hosted on WordPress.org. It's similar to git. that would have to be untangled. I do not ency the champion who takes on that one.