Nothing’s stopping someone who wants to intentionally implement an old, unclear, buggy, and incomplete specification. But I don’t think we should go out of our way to support that use case. If that’s not what you meant, then could you explain more?
If the standard was rigid enough in the first place, then we could consider how we might want to freeze it in place. But it’s been an incomplete work in progress from the beginning.
My proposition was if something in 1.0 or 1.1 is unclear in a minor way, then it should go into 1.0a or 1.1a. I take it that you don’t think this proposition is a good idea. My reasoning is that if a later standard introduces new things, some interpreter writers might not want to implement them, but be able to rely on clarifications and bug fixes
How is 1.1a functionally different from 1.1 (2023-09-15)?
Maybe we can avoid editing the older standards if we focus on addressing those issues in 1.2?
Perhaps set a fixed period for introduction of proposed changes, followed by a discussion and possible implementation period, then final acceptance? Changes could be subdivided into clarifying: (no intended functional change), defining: addressing undefined behavior (possibly to make some behavior legal, or clarify what is undefined), and finally extension: new behavior. Each category should probably have a different level of required consensus and can be removed from the process if it is lacking. If there are enough desired extensions, then perhaps 1.2 should specify a V9 format?
I feel like the idea of the document version is getting mixed up with the standard version.
To reduce this to a trivial case, it’s never wrong to fix a typo. (It might not be worth the effort to fix typos in old documents, but you could.) You could also clarify confusing passages, add new historical information, or correct blatant errors.
For that stuff, you’d want to update the document version – whether that’s a letter or a date – but it’s not a new standard. A new standard changes what interpreters are responsible to handle.
I think that historically, we’ve used the standard number (“1.0” and “1.1”) to indicate new standards. This goes along with, say, the way the spec uses header field $32/33 to indicate what standard the interpreter claims to obey. (Which is a gnarly concept in itself, but the point is you wouldn’t want to use the header to indicate document changes like typos and clarifications.)
Another example: I would like to add the ZIL spellings of opcodes to the opcode tables in section 14. (E.g., Inform opcode @set_attr is ZIL opcode FSET.) This has nothing to do with interpreter behavior; it’s new historical info that’s come to light since 2014. Anybody who is delving into Z-code history wants to know this. But it’s not a new standard version. We could perfectly well add that info to the 1.0 and 1.1 specs right now, and I’d argue that we should.
A “living” standard (to borrow the language from HTML) is much better than a frozen standard. The only advantage I can think of of a fixed period would be the extra attention it might generate. But there’s no guarantee that we’d find all the things that need clarifying. And I doubt it would really get that much attention.
Every few months someone new starts to implement the standard for the first time. That doesn’t always result in a viable interpreter that gets used, but it does mean someone is looking at the standard with fresh eyes. They will have questions other people haven’t had, and they could see ambiguities no one else noticed. It would be much better to be able to update the standard as we go, so that it continually gets better.
The archive doesn’t seem to be tracking all individual revisions of the standard document. That would be good to start doing. And maybe for extra clarity, we could use a point version for the standard document revision. It it could be like “1.1.1”, but I’d say “1.1.20230915” would probably be better as it’s really just to track when the document was revised.
I don’t think we should really be planning extensions any more. Despite the possible doing so, it’s been many years since anyone I know has even had a clear need to do so (the original pre-Glulx version of Vorple). I’m even considering removing the gestalt opcode I added to ZVM.
The text of the 1.0 Standard has been corrected a few times already, but always to fix mistakes or make text clearer. The actual Standard hasn’t changed.
Anyone who looks at the specification for Standard 1.0 ought, ideally, to be able to implement an interpreter that runs all Infocom Z-Machine and the vast majority of later Z-Machine games, without having to look at a separate document.
At the same time, any currently compliant 1.0 interpreter shouldn’t become non compliant because we updated the spec. This means that undocumented behaviour needs to remain undocumented (except maybe in the notes).
If we want to add features or codify currently undocumented behaviour, that needs to go in a new 1.2 version of the Specification.
I don’t think there’s much that’s undocumented in the spec, rather the issue is things that are underspecified. Rare edge cases that make a difference for only one or two games.
For those cases, I stand by what I said before: if there’s a de facto understanding (ie, most or all interpreters already do the same thing) then we really should just clarify that and put the details into the spec. If the interpreters differ, then we can weigh the arguments, see if there are actually reasonable arguments for both understandings of the spec, and document in the spec what the different options are. With possibly a note saying to avoid it because of the lack of consensus.
Neither requires a 1.2 spec. Only new features need 1.2, and there’s no real community desire for that now.
Okay, so, I think I’ve properly reverted the changes I wasn’t happy with (I haven’t used git in four years), and now I just need to figure out how to transfer ownership of the github repository.
It’s on the repository’s main settings page, at the bottom. It might be easier to just transfer to Zarf’s account (erkyrath) and he can transfer it to the IFTF organisation, because I don’t think you can transfer to an organisation unless you already have the ability to create repos in that org.
That works.
Do you want to continue to have edit access to the repository?
Yeah, that would be nice. I always intended to work on it, I just don’t want to hold everyone else up while I’m busy.
Okay, should be done now.
RIght. https://github.com/iftechfoundation/Z-Machine-Standard exists now. DFillmore has write access.
So, who else am I adding? What is the discussion protocol we’re sorting out? Who else should we contact who isn’t already in this thread?
Okay, so, my thoughts on discussion and consensus and such:
First, if we add tags to the repository denoting when a version was considered ‘final’ enough to be uploaded to the inform-fiction website, it will be relatively easy for people to see which changes have not been finalised.
As for the actual discussion, sometimes the issues are raised on this website first, sometimes they’re just added as issues on the github repository. For the second case, either a thread here for each issue, or a thread for the issues as a whole to which each new issue is added as it comes up. I think one thread specifically for all issues raised on the github repo is the better idea, although it might end up with people talking about several different issues at once.
All serious discussion should be done here. Issues could be raised at Github but be referred to the relevant discussions here. Housekeeping issues could be handled entirely at Github.
I see that @OtisTDog already linked to it in the List of I6 Documentation, but I just stumbled upon this by web search and it seems to not have had much mention on IntFiction:
The Z-machine Standand 1.1, annotated by Jared Reisinger, reformatted for the web (including turning internal references to other sections into links). It’s more navigable (and more attractive) than the official Z-machine Standard. Otis called out this improvement in particular:
I see you’ve created a thread for spec editing discussions.
To repeat the concrete question: who gets Github commit privileges? Currently it’s David F (and me, because I’m an IFTF admin). If we let that stand, then David is in charge of admitting all changes to the repo. Which is fine, if that’s what people want! I just want to make sure everyone agrees on the procedure.
Well, while I’ll probably have a bit more time now to work on this stuff (and I’m happy to do so), it does seem like it’s a good idea to have someone else with commit privileges as well, given my habit of getting distracted for four years at a time.
I’m interested.
I think we’re not yet close enough to a consensus though. We at least need to agree on what sort of changes we want to make to the spec. I’ll make a poll to gauge interest.
In terms of procedures, I’d like us to make having a test for each proposed change the new expectation. Some of which could also be incorporated into Praxix. And if we put Praxix and other tests into the repo, then for every commit/PR we could also run each of the interpreters against the tests to check they pass.
Another question is whether it’s worth still maintaining a distinct 1.0 version of the spec. I don’t really see the point of that when all 1.1 features are clearly marked, and can be ignored by someone only working on a 1.0 interpreter. Maintaining only the 1.1 version would be less work.