Alan underlines the attractions of one kind of strategy in this area with his customary cogency and clarity. He nevertheless understates its disadvantages by not mentioning any.
There is a more detailed discussion of various possibilities at
http://www.stata.com/support/faqs/lang/version2.html
What follows is in part more personal, although I think not contradictory to anything in that FAQ, which happens to bear my name.
In putting various Stata programs into the public domain over the last 15 years I have noticed the following, without implying any order of importance. This is all despite StataCorp's best endeavours, as their work on maximising compatibility between stuff written for different releases while allowing continued major and minor improvements is quite outstanding.
I particularly want to underline that the situation of StataCorp -- whose reputation and market value depends at least in part on stuff continuing to work as far as possible with as few hiccups as possible -- is not analogous to that of the typical user-programmer, who is donating stuff to the Stata public out of pure altruism, or at best with the faint prospect of some marginal enhancement to some rather nebulous reputation.
1. Help files have changed in suffix and within SMCL there have been numerous changes. None of this is fatal but it can prove challenging especially for naïve or inexperienced users.
a. Stata 9 and below expects .hlp while Stata 10 and above expects .sthlp. That implies either maintaining parallel help files or instructing users to use -view- or -type- on files not found by -help-.
b. Stata will not fail given SMCL it doesn't understand, as it will echo such mark-up literally. The effect in older versions reading help written for later versions induces varying degrees of noise or irritation.
2. Maintaining ado files that will work across multiple versions is increasingly challenging.
a. New commands appear without older analogues, and old commands disappear, become undocumented, or (most likely) increasingly are by current standards limited or unattractive in what they do or present. For example, if I enhance one old program using Mata to do what is now possible with Mata but was previously difficult or impossible, the chance that I will write parallel code so that people still on Stata 8 or less can use that new feature is essentially zero. This is in essence Alan's kind of example viewed the other way.
b. Thus the difficulty is not segregating code that worked under Stata # in the way that Alan identifies. The difficulty is how new features or even quite different syntax for a program can be supported for older versions without undue strain on the programmer, already under time pressure for all the standard reasons. The value of such effort diminishes rapidly as the number of likely users diminishes, while the difficulty of maintaining and testing programs that will work regardless of the user's version increases across the range between oldest and newest versions. To be concrete even though mundane, I work in an institution where new machines every couple of years are standard, yet I am one of a few who have permission to install other executables. The cost is that my IT people take no responsibility for re-installing old software which I ever had on previous machines. Thus I do not ever have many old versions of Stata on my machine: while in principle I could easily rein!
stall them, in practice there are too many other important or interesting things to do.
Thus without disputing the value of the strategy which Alan identifies I find it usually easier to peal off old programs as say -foobar10- if -foobar- is much revised under 11 and I lack the time or the incentive to maintain support for users 10 within -foobar-. (Indeed I suspect that this particular convention that the number indicates Stata version required, rather than version of the program, was introduced by me.) -foobar10- is then announced as "frozen as was" and the implication is that people on Stata 11 should not download the new -foobar- as the old -foobar- is all they can use.
I realise that this practice may be problematic but I am old-fashioned enough to think that users should take some responsibility for what they download.
Alternatively, people who don't upgrade may not do so for very good reasons, such as not having the funds, but I can't let them be much of a drag on my programming, particularly as they are not paying me anything and never did. Everyone's generosity has to have some limits.
Nick
[email protected]
Alan Riley
Richard Williams ([email protected]) asked about -adoupdate-
and ado-files downloaded from SSC for Stata 11 vs. Stata 10:
On Mon, Jun 29, 2009 at 04:06:25PM -0400, Richard Williams wrote:
> I wonder if -adoupdate- becomes potentially dangerous for people who
> don't update their Stata version. Suppose you have Stata 10, and you
> have a routine you downloaded from SSC that works with Stata
> 10. Then, the author updates the program so it requires Stata
> 11. When you run -adoupdate-, won't the version that works with
> Stata 10 get overwritten by the version that requires Stata 11?
>
> Most authors will probably keep a renamed version of the earlier
> program available, but it might be nice if adoupdate warned you when
> you were about to update to a program you can't run.
It is true that -adoupdate- will seek out the newest update to
a given package which has been -net install-ed, no matter what
the version number is in the ado-files in that package. So, Richard
is right to be thinking about this.
It would be possible to modify -adoupdate- to take note of a version
comment within the text of the package file it is checking, but even
better than that would be for this to be a feature understood by
Stata's -net- command. It is too late for such a feature to be
added to Stata 11, but we may add it in the future.
However, Richard's email leads me to want to talk about version
control in user-written programs. Over the years, I have seen
authors of user-written programs put out a command named, say, 'x',
which runs under Stata 11, and put out another command, say, 'x_10',
which is known to run under an earlier version of Stata. End-users must
decide whether to install 'x.ado' or 'x_10.ado' and must remember to
type -x- or -x_10-.
There is a simple, and better, solution, for authors of user-written
programs who wish to implement version control in the way developers at
StataCorp would do so. This solution lets users of Stata 11 type
-x- to access the Stata 11 version of x.ado, and it also lets users of
Stata 10 type -x- (NOT -x_10-) to access the Stata 10 version.
The author of the program still creates x.ado and x_10.ado, but
x.ado has a few lines of code in it which allow it to be smart
so it can call the older x_10.ado if a user is running under
version 10:
----x.ado--------------------------------------
program x
if _caller() < 11 {
x_10 `0'
exit
}
version 11
// the code for the Stata 11 version
// of 'x' goes here
end
----x.ado--------------------------------------
----x_10.ado-----------------------------------
program x_10
version 10
// the code for the Stata 10 version
// of 'x' goes here
end
----x_10.ado-----------------------------------
This takes no more work for an author who was going to create
both x.ado and x_10.ado anyway, but it is cleaner for end-users.
It also means that even if a user installs an updated version
of the 'x' package, as long as they have used version control in
their own do- and ado-files, the appropriate version of -x-
will be executed.
*
* For searches and help try:
* http://www.stata.com/help.cgi?search
* http://www.stata.com/support/statalist/faq
* http://www.ats.ucla.edu/stat/stata/
