Feature - Implemented ASH directive to enforce a minimum mafia version

roippi

Developer
Pretty straightforward idea. A lot of neophytes have this as their first post on the forums:

hey im getting this error, no idea how to fix plz help

invalid foo: 'bar' (baz.ash, line 1234)

They of course simply need to update their mafia (and perhaps to be told that there are releases other than point releases).

I propose that we add some ability to specify a directive near the top (like script/notify) of an .ash file - like

Code:
since r14600;

If we encounter this while parsing, we check this against the current revision number - and if not greater than the current revision number we drop out with Some Helpful Message. The current status quo is that we just merrily parse until we hit some undefined function (or something other than a function, we could add new operators, whatever) and then bomb out with a foo not found message that is quite cryptic for lay users. It would be better if it just said "update to r12345+, knucklehead."

There would be some maintenance burden on scripters who opt in to this feature to keep the value up-to-date but 1) I don't think it's too bad, and 2) I don't think this can be avoided.
 

fronobulax

Developer
Staff member
I like the idea. A couple of things jump to mind:

Could/should this be tied into the dependencies option used by some SVN hosted scripts?

How do we handle the fact that scripts can reference other scripts and thus there could be multiple "sinces"? Do we roll them all up or report all or just stop parsing the script at the first one that fails?

Finally what is the meaning behind "since"? Specifically if someone says "since xyzzy" should the user understand that to mean the author has tested it with xyzzy and it is expected to work with xyzzy or newer or does it mean the author knows it won't work with earlier versions? The distinction seems important if only because not everything is updated at the same time and sometimes my preferred solution is to roll something back rather than edit something that appears broken.
 

roippi

Developer
Could/should this be tied into the dependencies option used by some SVN hosted scripts?

I should have mentioned that feature request too. I never got around to implementing it because in the end it was only going to amount to a warning message that occured after you svn-updated. That still might be worth doing but I think this idea is better overall (I prefer a fail-fast useful error message rather than a one-time warning message), and implementing them both is probably clunky - making scripters update a value in two different places means at least one of those places will get neglected.

How do we handle the fact that scripts can reference other scripts and thus there could be multiple "sinces"? Do we roll them all up or report all or just stop parsing the script at the first one that fails?

It's a compile-time error so basically by definition we can't continue parsing once we fail a version check - any lines after that may be "invalid" (to our current version of mafia's knowledge) syntax.

Finally what is the meaning behind "since"? Specifically if someone says "since xyzzy" should the user understand that to mean the author has tested it with xyzzy and it is expected to work with xyzzy or newer or does it mean the author knows it won't work with earlier versions? The distinction seems important if only because not everything is updated at the same time and sometimes my preferred solution is to roll something back rather than edit something that appears broken.

I don't really grok what the actual difference is there. But basically I envision the error message being something like:

Code:
since r12345;
      ^
UpdateYourMafiaException: 'foo.ash' requires revision r12345 of kolmafia or higher (current: r10000).  Up-to-date builds can be found at http://builds.kolmafia.us/.
 

fronobulax

Developer
Staff member
Ok. Thanks.

On the last point, if I am lazy and a casual script writer then I am going to just set xyzzy to be the revision that I used when I self-tested a script before releasing. If I am a pseudo-professional software generator with a goal of maximizing (or not inconveniencing) my user base then I want to set it so that my script works for version xyzzy but not version xyzzy-1 or earlier - in other words the oldest working version. To do the latter properly imposes a burden on me since I need to record, or rediscover, when features my script uses were introduced. In a sense, I am looking at "since" as a contract between the author and user and trying to determine how both sides interpret that.

On a practical basis I think what will happen with me is I will not introduce the since keyword unless I explicitly know I am using something that got changed in KoLmafia or one of the handful of people actually using something I wrote tells me something is broken.

So it looks like the transition is they keyword gets added and then script writers opt in to using it when they know it is needed. That should work. Thanks.
 

Theraze

Active member
Personally I'd say that setting since to the last tested version is actually a good thing. What are the chances that you'll remember to check every item, function, and everything else that goes into a complicated script? Bumping the 'since' version number every time an item breaks BCA, for example, means that we know that it should work if you're at LEAST on this version. Do you NEED that version? Maybe. Maybe not. But if you're running that or newer, it shouldn't punt.
 

Bale

Minion
On the last point, if I am lazy and a casual script writer then I am going to just set xyzzy to be the revision that I used when I self-tested a script before releasing.

You're wrong. If you are a lazy and casual script writer then you won't use the "since" line at all. It would not be mandatory any more than script and notify are mandatory. These lazy and casual scripters just won't use it at all.


If I am a pseudo-professional software generator with a goal of maximizing (or not inconveniencing) my user base then I want to set it so that my script works for version xyzzy but not version xyzzy-1 or earlier - in other words the oldest working version. To do the latter properly imposes a burden on me since I need to record, or rediscover, when features my script uses were introduced. In a sense, I am looking at "since" as a contract between the author and user and trying to determine how both sides interpret that.

Sucks to be one of those people. I hope that they won't punish themselves with such an obsession.


On a practical basis I think what will happen with me is I will not introduce the since keyword unless I explicitly know I am using something that got changed in KoLmafia or one of the handful of people actually using something I wrote tells me something is broken.

Yup. That is exactly how I would use it. "OOOOoooh! That's a neat *new* feature I want to use it! I'd better add a 'since' command." Or if it references items that were just added to the game/mafia. I imagine this as the proper use of the command and most of us are going to use it this way.


Personally I'd say that setting since to the last tested version is actually a good thing. What are the chances that you'll remember to check every item, function, and everything else that goes into a complicated script? Bumping the 'since' version number every time an item breaks BCA, for example, means that we know that it should work if you're at LEAST on this version. Do you NEED that version? Maybe. Maybe not. But if you're running that or newer, it shouldn't punt.

Or there will be people like this. I don't hate the idea.
 
Last edited:

fronobulax

Developer
Staff member
On the last point, if I am lazy and a casual script writer then I am going to just set xyzzy to be the revision that I used when I self-tested a script before releasing.

You're wrong. If you are a lazy and casual script writer then you won't use the "since" line at all. It would not be mandatory any more than script and notify are mandatory. These lazy and casual scripters just won't use it at all.

*snicker* I often use lazy in a positive sense - for example I almost want to hire a computer systems administrator who is lazier than I am because she will automate things rather than do the same thing over and over again, and her automation has benefits for both her and the organization. That said, I suspect it would be easier to put since in a script than answer a forum post that says something doesn't work.

But yeah, give me enough rope and I'll over-engineer a safety net for someone whose feet don't even leave the ground.
 

Winterbay

Active member
Yeah, I'd mainly use this to force people to update when I add a new feature that is new to Mafia. If the script is on SVN it may be friendly to inform them that they can downgrade the script in order to get it to work with the current version perhaps, but that is maybe a bit overkill.
 

Bale

Minion
Actually, that is not a horrible idea.

How about an optional parameter for script which is simply a string enclosed in quotes. If this is present it will be printed after the default message for since.

So, if the script starts with...
since r12345 "If you are morally opposed to downloading recent builds from our website, then you may downgrade the script to the previous version with 'svn dec WHAM'";

Code:
since r12345;
      ^
UpdateYourMafiaException: 'foo.ash' requires revision r12345 of kolmafia or higher (current: r10000).  Up-to-date builds can be found at http://builds.kolmafia.us/.
If you are morally opposed to downloading recent builds from our website, then you may downgrade the script to the previous version with 'svn dec WHAM'

Another person might prefer
since r12345 "This is because a new mafia feature is so awesome I needed to include it.";
 

zarqon

Well-known member
This is a lovely idea. I am a fan of this feature and see the simplest possible implementation as being the best.

"since <revision number>;"

I see it reducing both user confusion and needless forum posting by a large margin. I'd use it for ZLib for sure (there were at least 6 messages/posts that I know of about "water_level" errors), and probably everything else. I don't see any particular reason why a person could not update mafia if they get that message (maybe they are playing the game offline? oh wait...), and so see no need to pander to non-updaters.

If an informational message about "svn dec" to revert an update is to be added anywhere, it should probably be something mafia prints after "svn update" for all SVN updates. Any given script is not necessarily connected to SVN (even if it may have been acquired via SVN), so adding SVN-specific messages to a separate requirement (mafia version) is not the place for it.

Next, we'll want "until" for when mafia updates break our scripts. <-- joke

^ joke ^
 

ckb

Minion
Staff member
Sucks to be one of those people. I hope that they won't punish themselves with such an obsession.

This, Bale, made my day. Thanks.
And even better, from a guy who wrote an 'OCD' script. That is beautiful.
 

Veracity

Developer
Staff member
My guess about the intended/expected use of this feature:

1) The vast majority of scripts use features that have been in ASH for years. They don't need a directive. But, to be safe, they could do something like:

since <13.4>

assuming that 13.4 was the major version in which they released the script into the wild. They could leave this out, since, as I said, most scripts don't use cutting edge features.

2) When a new feature is added to ASH - frequently because a particular user asks for it - someone who changes their code to use it would add

since <14721>

to the script to require users to have the revision that added the feature.

3) most likely, script authors would pay no attention until somebody reported "I keep getting xxx is undefined. Help?" and the response here would change from "upgrade mafia" to "upgrade mafia and the script needs "since <14721>"")

In other words, conscientious script authors might use 1 and will definitely use 2, and lazy script authors will be prompted to do 2 when the first bug report appears here and are given a non-lazy response.

I like this idea a lot.
 

lostcalpolydude

Developer
Staff member
That also brings up the fact that this should support both point release values and subversion version numbers probably.
 

roippi

Developer
r14659

Things I did: handling for both version/revisions

Things I didn't: optional error message field after the revision argument. I'm not philosophically opposed to adding it, really, but the API seems cleanest without. I don't think that users should in general be told to downgrade scripts to keep things running, really - upgrading mafia itself should always be preferred. There are some corner cases where we break something/cause massive performance regressions but I don't think those merit the feature.
 
Last edited:

zarqon

Well-known member
Awesome! Amusingly, I am hesitant to use this feature because of the bug reports it will inevitably bring.
 

Veracity

Developer
Staff member
Do it after we release the next point release (which I hope will be shortly after we support the next IOTM, whatever it is - no more 5 months between releases!), since if people can't be troubled to upgrade when KoLmafia itself tells them to upgrade, that's not YOUR problem.
 

Veracity

Developer
Staff member
Things I didn't: optional error message field after the revision argument. I'm not philosophically opposed to adding it, really, but the API seems cleanest without. I don't think that users should in general be told to downgrade scripts to keep things running, really - upgrading mafia itself should always be preferred. There are some corner cases where we break something/cause massive performance regressions but I don't think those merit the feature.
I agree with this.
 

Bale

Minion
Do it after we release the next point release

That is exactly what I was thinking. Let's not make any use of this feature until the next point release because it just won't do its job until then.

I've really got my fingers crossed about spinning the next point release in early October. I'm particularly excited that you're working on finally getting mafia chat to play nice with KoL's tabbed chat. Yay!
 

roippi

Developer
Awesome! Amusingly, I am hesitant to use this feature because of the bug reports it will inevitably bring.

Well it's no different from any other new feature in that regard - other than it being the last one you need to be hesitant about, of course ;-)

Marking implemented.
 
Top