Updating extensions in the GitHub repo for Inform7 v10

OK, so I’m actually ready to start updating my extensions but I want to keep the 6M62 versions around, off to one side. What system/best practices has been decided upon? I really do want to have separate files for the v10 version and for the 6M62 version, as I do not want to carry around adaptations for both versions in the same file.

I think we might be about ready, but to try to ensure we think we’re ready for the same thing, my understanding of the plan would be:

We create a 10.1 branch on the repo. That will shortly become the default branch displayed on the web.

Releases committed there have a comment underneath the rubric(s) but above the main code saying:

[ Targeted release: 10.1 ]

(or at least I’m suggesting that as standard placement, not that I think anyone should get huffy if it’s above the rubric. I would strongly recommend we keep it above the code for visibility’s sake, though.)

A thing we haven’t discussed, but I’ll suggest now:

Things for 10.1 should have a semantic version number, and authors should aspire to follow the semantic version spec regarding future changes to the extension and its version number. And to always change the patch version for any code change no matter how trivial. (I’d prefer people did it for doc changes too, but I’ll save my discouragement for code changes.)

Filenames should follow the inbuild manual’s filename description:

a filename (or pathname) which ends with -vN, where N is semantic version number but with any dots replaced by underscores. Thus, we can have e.g.:

Extensions/Emily Short/Locksmith-v3_2.i7x
Extensions/Emily Short/Locksmith-v4_0_0-prealpha_13.i7x

Extension filenames are now arbitrary, but for sanity’s sake we should stick to a scheme. (I expect the IDE will impose that automatically and it’ll be a non-issue for IDE users, but I’m sure I’m not the only command-line iconoclast among extension authors.)

And while we’re engaging in an upheaval, any chance of switching from “master” to “main”?

After we have things hashed out, I can slap version numbers and targeted release comments on those 6M62 extensions that compile and are believed to work and commit them to 10.1.

1 Like

Oooh, you found something in the Inbuild documentation regarding putting the extension version into the filename. And it’s refering to a semantic version number…

The thing is, we were previously versioning extensions according to the rule here:

http://inform7.com/book/WI_27_6.html

A version number must be a whole number 1, 2, ..., 999 (version 0 is not allowed, and nor are decimal points), optionally followed by a slash '/' and then a six-figure date, in the form YYMMDD: so 040426 means 26 April 2004.

Is this inoperative in 10.0.1, or is this still getting enforced? I’d hate to have a different version number on the file and in the file.

v10 can tolerate old version numbers and also incomplete semantic version numbers without a patch version – and the former of the two Locksmith examples above implies that Version 3.2 of Locksmith by Emily Short would be saved as Locksmith-v3_2.i7x.

The version of “Writing With Inform” which I just compiled from the master Github repo, which shows up in the IDEs, still has the same text specifying the “old-style” version numbers. I just checked.

If we’re going to change the extension version numbering system, Graham Nelson needs to change “Writing With Inform”.

FWIW, my Extension Style Guide was already recommending using the major version number as a major version number (change for any backward-incompatible change) and the date as a minor version number (change for any change), matching the Semantic Version Number Standard well enough.

I commented on the state of the doc updating previously. Though the raw text of a version of WI that’s been updated in places is in the repo, I feel certain that it’s well-understood that it needs further revision. I don’t think that it’s a coincidence that the intools docs have been publicized while only perusers of the repo know WI is there. (I’ve submitted some tiny pull requests for WI changes and reported some missing things as bugs.)

I think it’s a safe bet that when it’s up-to-date, there will be shiny new automatically generated HTML and an epub at inform7.com and we’ll all know about it.

I never like to assume people will fix bugs unless they’re pointed out, because they usually don’t. Has someone reported the version number bug in Writing with Inform to Mr. Nelson? Maybe someone who’s made an account at the new bug tracking site? I guess you did mention it in the relevant thread here, so we can hope.

We have two main ideas, but didn’t seem to reach a consensus yet, so I thought I’d make an informal poll. If you don’t care at all you can vote for both, but it would probably be more helpful if you can try to decide which one would be easier for you to work with :wink:

  • Commit to master branch with release information in comments; system will automatically replicate extensions into the branches they support
  • Commit directly into release branches; master branch is for WIPs

0 voters

In both cases we would make the default branch of Github be the latest release, so that people who just go to the repo can get working extensions for the latest release. But the master branch will still exist so old links won’t be broken.

I can handle either, mostly. What I’m worried about with “commit to master branch with release information in comments” is actually getting my old stuff replicated properly into the 6M62 branch. I’m not going to be making further commits to the 6M62 versions and they will not have release infromation in comments.

The new versions will not work for 6M62 and the old versions do not work for v10. I do not intend to maintain versions of the files which work for both, although I know it is theoretically possible; they’d be too ugly.

More importantly for my workflow questions: are we going to start commiting the extension files with version numbers in the filename, as Zed suggested? (I did just verify that Inform 7 does support that.) Because that’s going to be a somewhat different workflow.

I think it has a fair amount of merit to it, but it also has downsides: older versions of extensions may start to clutter the release branches as well as the main/WIP branch. If we want to keep the release branch looking “clean” we may want to avoid it and keep the filenames “plain”.

Basically, am I going to be uploading “Tab Removal.i7x” or “Tab Removal-2_0_220520.i7x”? I think the decision on that has a significant influence on how to do the branches.

(Oh, yeah, I just fixed Tab Removal for v10, in the spirit of working from simpler to more complicated changes)

Well before we shift I was thinking of asking Zed if his smoketesting results could be used as the basis for filling out the release branches, including possibly putting in the comments.

Versions in filenames, I’m not sure. If we use the system to replicate extensions then probably yes, we can automate that. But if people are just committing to branches themselves then it would be on them to do it if they want.

We could have a compromise of only major versions in the file names. That would help people find compatible versions while not cluttering with every minor and patch version. But on the other hand, it would be rare for someone to make so many updates that it really does feel cluttered.

So if we go with “commit to the master branch, automated population of the release branches”, then it seems like I have to do the version numbers in the filenames in order to have both the 6M62 version and the v10 version around.

Then I feel like the git workflow gets worse: every time I update a file, I have to rename it. I don’t like it.

I think some degree of clutter is inevitable. But I’d be totally ok with a scheme of: have filenames include versions that may not exactly match the contents but don’t contradict the contents, i.e., we can count on _v2.i7x being something with major version 2, that _v3_1.i7x begins 3.1, etc.

I have a strong preference for avoiding plain unversioned filenames in the v10 world, 'cause there’ll probably eventually be another version, and then someone would be looking at

Exciting Extension.i7x
Exciting Extension_v3.i7x

and having no idea which is the higher version until looking in both of them.

I see your point, though looking into the files is not difficult.

If you don’t make updates to the 6M62 version, then you don’t have to do anything. If you do want to make updates to the 6M62 version then you would just make them directly to the 6M62 branch. Just as you would without the automated replication.

Putting versions in filenames is only for the version of your extension, not of the I7 release. And of course it’s only for 10.1, you can’t do that for 6M62.

Good point. My script will need updating to support this, but I think it’s definitely the way to go. Question is whether to do major version only or also minor and patch.

1 Like

OK, so basically, one implication of all of this is, I can’t commit any v10 fixes to “master” until the 6M62 branch is branched. Can we, um, branch the 6M62 branch ASAP?

The reason I’m thinking this: My v10 fixes will invariably break my extensions for 6M62, so I have to make sure the 6M62 versions get pulled off into the branch before I start introducing the v10 versions. Though maybe if the 6M62 versions have no version number in the filename and the v10 versions do have a version number in the filename, the automated scripts creating the 6M62 branch can be smart enough to sort this out?

Nevertheless I want to eventually remove the 6M62 versions from the master, Work In Progress, branch. So I’m waiting for the 6M62 branch to be formed before doing so.

and that’s a good point I wasn’t thinking of. so now I’m just going to suggest using the extension major version in the filename.

2 Likes

That might be a good compromise…

…though I may have to get a little less strict about the definition of backwards-compatible API changes. My extensions in particular seem to have a tendency to make small backwards-incompatible API changes (probably due to their nature). One of the unfinished (!) ones is already on version 5. I probably would have kept the major version on that one 0 if we’d been using semantic versioning at the time.

@Zed How would you feel about turning your research into branches now?

If you create the 10.1 and 6M62 (or 9.3, whatever we’re going with) branches, I will populate them this weekend based on what compiles successfully with the respective compilers (omitting a couple of things known to not work despite compiling, or per author’s wish as @bg expressed above), tagging them with the appropriate [ Targeted Release ], and, in v10, adjusting the filename to include the major version number. (I don’t think I need more permission than I have to create the branches myself, but I’m not sure where we are on exact names. I like 6M62 but don’t consider it a big deal.)

Do you also have any data for the older branches?

You don’t need to put in any comments yet. We may not decide to use that system.

And it’s probably easiest for you to just create the branches. You can’t actually create branches without anything to put in them, and I don’t really have anything yet. Unless I was to copy the readme.