What does -version- guarantee?

[Nils Enevoldsen]

Last week, I thought -version- was a tool for backward compatibility and forward compatibility. But it's not, is it? It's a tool for forward compatibility only.

Let me explain. I am using Stata 18, but writing -version 14.0- at the top of my do-files, under the assumption that my colleagues who use Stata 14 will get the same results I get with Stata 18. This mostly works. But an issue arose when I used the system variable _r_ub, and it didn't show up for a colleague on a previous version of Stata.

How should I consider the fact that _r_ub is available in Stata 18, despite specifying -version 14.0-?

1. A bug?
2. Not exactly a bug, but an undesirable side-effect, which the developers can minimize but will never stamp out completely?
3. Not at all a bug; working as intended?

A week ago, I would have thought (1) or (2) were true, but after reading the manual more carefully, I now think (3) is true. The only guaranteed usage of -version- is (a) when it is set to the version used to author the do-files, and (b) that do-file is run on an equal or later version of Stata.

Clearly this isn't the only way that -version- is used in practice. In particular, I think most ado authors deliberately specify "old" versions despite authoring on "new" versions, which is conceptually not so different from my own use-case.

So I have two questions:

1. Do I understand -version- correctly now? That is, is it correct that -version- makes no guarantees of backwards compatibility?
2. What are best practices for authoring do-files compatible with older versions of Stata? The two main alternatives I see are to actually use an old version of Stata, or to [mis]use -version- and simply be vigilant for the occasional neologism that -version- permits.

(Pinging Robert Picard because I feel like he might have something useful to say.)

[daniel klein]

To me, version is all about the future, not the past. When you write a do-file or ado-file, you specify the version that you are using. You can then be sure that your do-file or ado-file continues to work in future versions of Stata. Well, there's this thing called user-version and some minor details, but basically, that's it.

Generally speaking, version will not reproduce bugs; what is and is not considered a bug is for StataCorp to decide. Also, version will not disable improvements. There are exceptions to this. Howver, generally, in Stata 16 or higher, you can have frames with version set to 14. And, you can refer to _r_ub. Stata 14 cannot do the same because at the time Stata 14 was written, there were no frames and there was no _r_ub. Quite frankly, I find it hard to understand why you would think your version 14 statement in Stata 18 could change the source code (or even an ado) of a Stata 14 distribution released almost a decade ago.

[Nils Enevoldsen]

Quite frankly, I find it hard to understand why you would think your version 14 statement in Stata 18 could change the source code (or even an ado) of a Stata 14 distribution released almost a decade ago.

I didn't! I had expected that specifying -version 14- in Stata 18 would cause references to _r_ub to fail in Stata 18.

[daniel klein]

I didn't! I had expected that specifying -version 14- in Stata 18 would cause references to _r_ub to fail in Stata 18.

I see; that's a quite common misinterpretation, too. Basically, it has to do with the idea of not disabling improvements. When you set version 14 in Stata 18, Stata 18 would continue to do whatever Stata 18 would do -- unless there is a conflict, meaning that both Stata 18 and Stata 14 would produce valid answers; then and only then would Stata 18 act as Stata 14 did.

In terms of code, version really just changes a c() macro that other commands could access. That is, version control is implemented in selected commands in a command-specific way. It does not affect all of Stata. A command under version control (built-in or ado-based) would have lines similar to these:

if _caller() <= 14 {
    
    do_it_the_Stata_14_way
    
}
else {
    
    do_it_the_modern_Stata_way
    
}

You can have a look at merge.ado. At the very top, it implements version control for the old merge syntax.

The online help for version includes a comprehensive list of what to expect when you set version to less than #. Type

help version##summary

[Nils Enevoldsen]

Yes, this is a good explanation of my current understanding. My mental model was previously that -regress- in Stata 18 would internally reference -regress-v18.ado- (I'm making up names here), and -regress-v18.ado- would then store things in _r_ub, but by specifying -version 14- Stata 18 would divert to -regress-v14.ado-, which would not store things in _r_ub. But as you say, this isn't how it works. (Also, it wouldn't surprise me if -regress- were especially thorny and deeply integrated.)

When you set version 14 in Stata 18, Stata 18 would continue to do whatever Stata 18 would do -- unless there is a conflict…

Yes, I think this was the root of my confusion. Is this described anywhere in the manual? I don't see a statement to this effect in -help version-.

Instead, I see more general statements like "version # sets the interpretation of all language elements and commands to be the same as it was in version #", which doesn't mention exceptions.

BTW, I remain interested in any advice regarding my second question:

What are best practices for authoring do-files compatible with older versions of Stata? The two main alternatives I see are to actually use an old version of Stata, or to [mis]use -version- and simply be vigilant for the occasional neologism that -version- permits.

[daniel klein]

Is this described anywhere in the manual? I don't see a statement to this effect in -help version-.

I thought it was there but I cannot find it either. Perhaps in an older version of that help-file? No, seriously, I think this is from informal conversations at Stata Users Meetings.

What are best practices for authoring do-files compatible with older versions of Stata? The two main alternatives I see are to actually use an old version of Stata, or to [mis]use -version- and simply be vigilant for the occasional neologism that -version- permits.

Your first alternative is the only way to be sure that your (a)do-file really works as intended with older versions of Stata. I wouldn't recommend setting an outdated version. Doing so might give you unexpected results and it will be less obvious to those with older versions that the code was not actually developed for their version.

In your situation, let your colleagues who have Stata 14 write the do-file and confirm it works with your Stata 18.

This might also be a wishlist item for StataCorp: Give us remote access to run our commands on older versions of Stata.

[Nick Cox]

The FAQ


FAQ . . . . . . . . . . . Community-contributed programs and Stata version
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . N. J. Cox
7/11 I have a certain version of Stata and have come across
a community-contributed program that is apparently
written for a later version of Stata. What are my
options?

https://www.stata.com/support/faqs/p...stata-version/

was, as documented, released in 2011. As a result the version numbers used as examples are unlikely to be much in use now, but it's my understanding that no principles have changed since then.

[Nils Enevoldsen]

That's helpful. Thanks, Nick.

It is difficult (impossible, really) for you to be certain that what you have within Stata 12 will work exactly as it would in Stata 8.2 unless you test it by running a physical copy of Stata 8.2.

This seems to be the crux of it. Alas.

[Nick Cox]

I would be interested to hear of any serious software that was different in this respect. Fact is that changes from version to version are taken pretty seriously by Stata.