Draft versioning spec for discussion #16

jaustin · 2017-01-19T00:21:26Z

We need to balance a number of different factors when deploying
the online python editor for the micro:bit Foundation and this
is a first draft at outlining what they are and how we could
provide users with stability while allowing development to be
tested.

This is a PR so we can use GitHub's features to discuss the spec
and the deployment @carlosperate @ntoll @whaleygeek

We need to balance a number of different factors when deploying the online python editor for the micro:bit Foundation and this is a first draft at outlining what they are and how we could provide users with stability.

carlosperate · 2017-01-19T18:16:47Z

docs/deployment/microbit-deployment-draft.md

+
+Anything that could stop a script that previously worked from working must be considered a breaking change. In the case of MicroPython this means that things increasing memory consumption or reducing the flash available for a users’ script are likely breaking changes.
+
+{<< what other things should constitute a breaking change, and should we allow certain kinds of breaking change inside a version of the editor? IE can we support more than one MicroPython version for a particular deployed version of the front-end?>>}}


I think we should assign a micropython version to each editor version. This way is simpler and avoids any inadvertent or obscure incompatibilities. Most obvious example is that API changes will cause block changes. We could could define somethin that works it all out, but it just feels like unnecessary overhead.

Just to be clear, when you say "assign a micropython version to each editor version" you mean each minor version. So, for example, if the only update is a new micropython runtime and we're curently on version 2.1, then we're releasing version 2.2 where the only update is a non-breaking update to the micropython runtime.

I think this is a good idea.

Yes, exactly what you said, I should have been more clear about that.

I think this makes sense, though raises the question of whether we'd like to make older editor (even minor) versions explicitly available (eg for memory increase scenarios).

raises the question of whether we'd like to make older editor (even minor) versions explicitly available (eg for memory increase scenarios).

I think so, specially based on the conversation a couple of lines below, we just offer access to all versions, including minor.

carlosperate · 2017-01-19T18:20:19Z

docs/deployment/microbit-deployment-draft.md

+
+`python.microbit.org/v<major version>/editor.html`
+
+Because the use of semantic versioning ensures that things will not break for the user when upgrading minor versions, there will not be fine-grained control over which minor version a user gets. 


Is there any reason not to allow /v2.1/ access? Minor change can still include ui additions or new minor functionality, so I am assuming some people might want to stick to minor versions too?

I think such fine grained versioning just complicates matters in a "please don't make me think" sort of a way for the end user. As a teacher, I might be using version 2 of the editor with my resources and we, as well behaved developers, guarantee non-breakage between the different minor versions as specified by Jonny's criteria above.

Users could still use the simpler /v2/ versioning and not worry about it, while anybody with the knowledge to know the difference between /v2.2/ and /v2.3/ could still access each one.
Say, a micropython minor change has introduced a new non-breaking feature, there could be reasons to stick with the previous one.
Alternatively say we inadvertently introduce an issue with a minor release, we can easily check if it works with the previous version, even users are would be able to confirm this themselves before submitting a github issue (and yes, here I am assuming users familiar enough with github are probably savy enough to easily understand this versioning concept).

As long as /v2/ serves the latest minor without changing the URL, I really cannot really see any disadvantage in making minor versions available.

Upon reflection, I think you're right. :-)

Agree with Carlos. v2 needs to be the "don't make me think" version, and resources should always use that form of URL and 'share' should always create that form of URL. The minor versioned ones should be available but 'under the hood' - does that work for you both?

and 'share' should always create that form of URL.

Don't quite agree with that last part. Let's say version 2.9 is the latest, if a user goes to /v2/ it should internally resolve and serve version 2.9, but the URL stays as /v2/, it doesn't redirect to /v2.9/.
Now, if a user is intentionally using a minor version of the editor, they will have had to access the specific URL with the minor version included, so a user trying to share a script from the /v2.7/ URL should have their "share URL" pointing to the same explicit minor version.

carlosperate · 2017-01-19T18:22:37Z

docs/deployment/microbit-deployment-draft.md

+
+### Versioning in hex files
+
+When the user is provided a hex file, the full semantic editor version must also be embedded into the hex file at a known location so that when unpacking the hex, any version of the editor can offer to load the version that the script was created in.


I don't see a reason to do this. Specially if we keep a 1 to 1 mapping of micropython and editor versions we could resolve this internally.

I agree with @carlosperate on this point. Also, I believe such changes would require the input of @dpgeorge.

Indeed this is something that maybe needs to be discussed in the proper microbit micropython repository as well, as at the moment even adding the micropython version to a known hex location is not as simple as it might seem.

I think if we have 1:1 mapping of MicroPython version to editor version that does work BUT, what happens if we start to do things like PXT packages where we have in-editor assembly of modules - this isn't out of the question and I think means we could do with a way to say "this editor version created this hex file". Also, it means that third parties (say Mu, MS) won't have to go and look up the MicroPython version that maps to an editor version in order to redirect a user correctly. (IE if I drop a hex file from PythonEditor into PXT, PXT should be able to redirect me to the correct location!)

One way to do this would be to maintain a mapping of MP version to editor version (can be many:1) in the 'latest' version, so if you open a hex in /latest?mpversion=ABC it can redirect you to the right editor version?

what happens if we start to do things like PXT packages where we have in-editor assembly of modules

We would have to pack these in the internal filesystem, so either the filesystem files has been added by the user and we just read these (and maybe display them as well if they are python files?), or they are modules packed by the editor, so they would be under our control and should have pythonic versioning, which in essence is just plain data that can be parsed by the editor.

Also, it means that third parties (say Mu, MS) won't have to go and look up the MicroPython version that maps to an editor version in order to redirect a user correctly. (IE if I drop a hex file from PythonEditor into PXT, PXT should be able to redirect me to the correct location!)

If a third party editor encounters a micropython hex, they should only have to send it to the main python editor without any further processing. It would then be the main python editor responsibility to figure out the MicroPython version and redirect/load the correct editor version.

carlosperate · 2017-01-19T18:25:52Z

docs/deployment/microbit-deployment-draft.md

+
+When the user is provided a hex file, the full semantic editor version must also be embedded into the hex file at a known location so that when unpacking the hex, any version of the editor can offer to load the version that the script was created in.
+
+The hex file must also contain some editor unique identity, so that any hex can be related to the appropriate editor, perhaps automatically (e.g. MP signature at known location).This could be part of the version number?


Is the goal of this one to be able to differenciate between micropython, pxt, touch develop, etc hex files?
Micropython starts reading the script right after MP at a known address. This is packed together by the editor, so changing what goes after MP would break compatibility with older versions of any micropython editor.

This is my concern too. Also, how should we handle hex files generated by uflash, Mu and non-official languages / runtimes?

Okay, that's important if it breaks backwards compat but it's also really nicetohave as a feature. We can use UICR for this, we have some unused registers there and I'd like to make DAPLink UICR and editor version aware so we can do things like only updating the flash that contains the script file not the whole hex when drag/dropping.

carlosperate · 2017-01-19T18:56:03Z

I think we are making the Release cadence more complex than it needs to be just for the sake of "keeping order and managing change", when in reality there will be little to manage.
I do think it's a good idea to have a "july" changeover, but I think should only be reflected in the version displayed when accessing http://python.microbit.org .
If we just keep semantic versioning for stable versions, and a "beta channel" (something like python.microbit.org/beta) for unstable I don't see why we need any more process. When a beta feature is stable it goes into a new version, which can be accessed through a versioned URL, while the default http://python.microbit.org is anchored to a specific version through the year.

ntoll · 2017-01-20T12:29:13Z

docs/deployment/microbit-deployment-draft.md

+
+When a script is published or shared, it must be published including the major version of the editor (and therefore the MicroPython stack) that it was created with so that anyone following the link will be taken back to the version the script was created with.
+
+If a user visits python.microbit.org/latest/ and is working on the editor there, the URL published should still be versioned, such as python.microbit.org/v1/. 


If a user visits python.microbit.org/ or python.microbit.org/latest they should be redirected to the latest major version? Thoughts?

I agree that python.microbit.org/latest/ should redirect to whatever the latest stable major, that would be a lot more clear than internally resolving URLs etc that might surprise the user in the future when things don't work (I barely read the URLs I copy paste, I would not expect teachers and students to it, or to look at them to figure out what might have happened when things go wrong).
This would also make it clear that "latest" is a "shortcut" that will change with time.

However, I disagree that python.microbit.org should do that as well, only for the argument I was making before about keeping python.microbit.org anchored to a version for the academic year.

Carlos, can I check I understand your comments here:

You think
visit http://python.microbit.org --> get the current 'stable' version and the URL bar reads 'python.microbit.org'
visit http://python.microbit.org/latest --> get the current stable version and the URL bar reads 'python.microbit.org/v2/'

As long as the embedded data in the hex file and the 'share' and 'publish' buttons in the first case will point to python.microbit.org/v2 then that's all good. If not, I think we risk breaking things under people's feet

Yes, and just to clarify, from my point of view we would have:

visit http://python.microbit.org --> get the current 'stable' version (the academic year stable version) and the URL bar reads 'python.microbit.org'

ntoll · 2017-01-20T12:29:36Z

docs/deployment/microbit-deployment-draft.md

+
+Because we must commit to maintaining and fixing versions that are deployed on python.microbit.org it is desirable to make a small number of major release. 
+
+We propose an annual cadence for major releases, with an RC released early in the year so that a stable release can be made in July after the school year ends. This gives teachers time to become familiar with it before the school year start. The previous year’s version will remain available after this but will no longer be redirected to via python.microbit.org/latest or python.microbit.org/


I don't like this at all.

While I understand the need for stability, it means development is constrained to a glacial pace of release. Furthermore, it'll encourage others to just update to the latest version and host it themselves.

Why not make the cadence three times a year to reflect the cadence of the school year: Christmas holidays, Easter and Summer holidays.

I want to stress that the wider Python community won't follow these cadences (herding cats etc...). This will be a major source of pain for me personally as people tap my shoulder asking where / when their contribution / fix will land.

Once a year also means all the effort and rush for a stable release happens over the summer when people want to go on holiday.

My biggest concern is the King Canute argument - you may say you're going to do X, Y and Z (and I may agree with you on such points) but if the wider community doesn't agree they'll just find ways around them and/or fork, thus making it hard to coordinate efforts. I.e. the tide will come in no matter what you say. Welcome to my world!

When I talked to some teachers about Mu, one of the things that was mentioned is that one of them liked the fact that the same version could be installed in all computers and stick with it for the rest of the year. In the same session, some of the teachers I was talking with were apprehensive to even consider PXT at all because they had already lessons planned with the original blocks editor.
This is only a personal anecdote, but this limited feedback was from the teachers with the initiative to attend a local networking sessions on their own time, I imagine (and this is only a assumption from my part) that the "fear of change" might be more prevalent in the wider teaching community.

I want to stress that the wider Python community won't follow these cadences

If the front page at python.microbit.org makes it clear that there are modern versions available at the python.microbit.org/latest or versioned URL I'd be surprised if we have this problem.
We cannot really count on toasts or modals/pop-ups to be read and action correctly by the average classroom user, but I think we can count on this to spread the message of "shiner things" to the people with a personal interest.

I do agree that the way this "release procedure" is described here kind of puts all the effort (which we should remember is coming from a community of volunteers) into a specific time of the year, and as much as we all love working on this project, life happens and there are other priorities.
If we continuously develop through the year, once we get closer to this July time-frame we can consciously decide if we can push a little harder towards a specific goal. If we have been releasing features in their own versioned URLs through the year, then they should be stable enough to make it to the main release, and we can then decide which version has been "hardened" enough to be released as the next academic year release.

@carlosperate totally get all this.

Hmm... I like the difference between / and /latest (the first is anchored for the academic year, the second is updated more often).

I think we should try to offer choice. There will be teachers who want stability, some who want to keep up to date and developers who want cutting edge. If at all possible we should be able to support all three and ensure each group knows where to find the version they need.

This reminds me of the pioneer, settler, citizen distinction between users.

The whole point of this scheme and work is to offer choice ;)

By having a 'beta' or 'rc' always running we get the advanced teachers helping us test the latest stuff, too.

I'm really convinced by the fact we need a stable, annual main experience. Nicholas, as a book editor, don't you also want this? One of the common reasons we have for this is printed resources, etc!

ntoll · 2017-01-20T12:29:40Z

docs/deployment/microbit-deployment-draft.md

+
+There should be a mechanism to deploy versions of the editor that are not yet considered stable. These will not be widely exposed to the majority of visitors to the site, but will be published for enthusiasts, developers and other interested parties to help test the editor.
+
+It should be very hard for a naive user to wind up using a beta by accident. (Think, about:config warning in Firefox, etc)


I think it should be fine for anyone to get to any version of the editor so long as they know what version of the editor it is they're using and understand the caveats involved.

I think those statements are compatible :) I think we need to allow ourselves to kill versions that were either

never stable

released more than 3 years ago

Otherwise things might get a bit hectic!

ntoll · 2017-01-20T12:29:52Z

docs/deployment/microbit-deployment-draft.md

+An unstable beta/RC branch, once retired, should redirect to the latest equivalent branch, or if it can be determined by the version of the branch, the stable version that this version became
+
+Experimental branches can and will be destroyed with reckless abandon.
+


All of the above feels over-complicated. Why not just three versions a la Debian (it's beautifully simple):

stable - what you get when you visit python.microbit.org/latest;
testing - what'll end up as the next major stable release at the next termly cadence;
dev - the "anything goes" and "use at your own risk" version for those wanting to try new features.

That's it.

For something from dev to get to testing it must meet various criteria such as unit tests, integration tests, evidence of a code review from not-the-developer and evidence of feedback from some sort of user test.

Once in test, things are tested and bugs are fixed but the fundamental behaviour of new features mustn't change.

If people want to do anything more complex they probably have the technical chops to clone the repos and play around without having to bother us.

The reason not to have 3 versions a-la Debian is because Debian has a built-in package (and therefore composition) system. I can be on latest and then install XYZ if I want it. We don't have that same kind of configuration/composition here, so if we want to test a feature, really it needs a branch.

I'm trying to describe something a bit like git-flow here.

We have 3 primary versions
Latest (annual)
RC (will be the next annual)
beta (accrues features over the course of the year, ready to be next annual, becomes RC at some point)

And then we have feature branches, which may or may not get merged into beta.

For example, I'd like to start with Blockly on a 'blocks' feature branch at the next deployment.

ntoll · 2017-01-20T12:29:57Z

docs/deployment/microbit-deployment-draft.md

+
+Not every build will be the same as every other, and it should be possible to turn on/off features without forking the codebase using a config file.
+
+A named deployment could also enable pre-rolled, version specific frozen modules pre-imported. This would help for hardware specific or branded activities that require simple and fast engagement times.


Again, this will require changes in upstream MicroPython and @dpgeorge's involvement.

Yea, this is a long way up the road I think :)

ntoll · 2017-01-20T12:30:02Z

docs/deployment/microbit-deployment-draft.md

+
+### Storing the config for each deployment
+
+The config for any deployment should be stored alongside that deployment so that it can be queried by other versions.


What do you imagine being in the config that other versions would want to query it.

Sounds complicated.

Give me a compelling use case. ;-)

ntoll · 2017-01-20T12:30:09Z

docs/deployment/microbit-deployment-draft.md

+
+In these cases, it seems desirable not to prompt the user to move forward.
+
+ {<<I’m up for discussing these workflows, I don’t really want dialogues in front of people, but I also don’t want to move versions under their feet. >>}}


This all feels overly complicated.

All this redirection is likely to be, a) ignored, b) confusing c) over engineered for little actual usefulness (see a and b).

I know some really awesome UX people - let me pick their brains, they have a bunch of patterns an tricks we may be able to re-use.

In any case, my feeling is ^^^ is too complicated and I believe we can probably find a better solution.

Suggestions welcome, but honestly, those are things that have come out of thinking through the detail of this with PXT and teachers and the MBF :)

ntoll · 2017-01-20T12:30:15Z

docs/deployment/microbit-deployment-draft.md

+ * A list of all supported versions `”supported”: [ “1.3”, “2.1” ]`
+ * A list of deprecated versions (not sure this is necessary?)
+
+ {<< This seems very MVP, might be better to instead have every version listed and a status for each one? >>}


I like this idea of every version of the editor including the single source of truth.

Well, the idea was actually that the manifest was a level up from the versions, so not included in them, as to do it in them we'd have to update every version at every release of another version which is suboptimal. But maybe we're crossed wires?

ntoll · 2017-01-20T12:30:18Z

docs/deployment/microbit-deployment-draft.md

+    “stable”: “http://python.microbit.org/“,
+     …
+
+{<< Should I use JSON schema for this bit?>>}


Not sure any of this is useful.

ntoll · 2017-01-30T08:57:16Z

Ping @jaustin. I'm anxious to get the blocks work out ASAP. The sooner this happens the sooner we get feedback and can make quick improvements.

Any response to the feedback above? What are the next steps?

jaustin · 2017-05-10T14:10:50Z

@microbit-matt - tagging you here as it's probably time to pick this up again :)

Draft versioning spec for discussion

b99dccc

We need to balance a number of different factors when deploying the online python editor for the micro:bit Foundation and this is a first draft at outlining what they are and how we could provide users with stability.

carlosperate reviewed Jan 19, 2017

View reviewed changes

ntoll reviewed Jan 20, 2017

View reviewed changes


		Anything that could stop a script that previously worked from working must be considered a breaking change. In the case of MicroPython this means that things increasing memory consumption or reducing the flash available for a users’ script are likely breaking changes.

		{<< what other things should constitute a breaking change, and should we allow certain kinds of breaking change inside a version of the editor? IE can we support more than one MicroPython version for a particular deployed version of the front-end?>>}}


		`python.microbit.org/v<major version>/editor.html`

		Because the use of semantic versioning ensures that things will not break for the user when upgrading minor versions, there will not be fine-grained control over which minor version a user gets.


		### Versioning in hex files

		When the user is provided a hex file, the full semantic editor version must also be embedded into the hex file at a known location so that when unpacking the hex, any version of the editor can offer to load the version that the script was created in.


		When the user is provided a hex file, the full semantic editor version must also be embedded into the hex file at a known location so that when unpacking the hex, any version of the editor can offer to load the version that the script was created in.

		The hex file must also contain some editor unique identity, so that any hex can be related to the appropriate editor, perhaps automatically (e.g. MP signature at known location).This could be part of the version number?


		When a script is published or shared, it must be published including the major version of the editor (and therefore the MicroPython stack) that it was created with so that anyone following the link will be taken back to the version the script was created with.

		If a user visits python.microbit.org/latest/ and is working on the editor there, the URL published should still be versioned, such as python.microbit.org/v1/.


		Because we must commit to maintaining and fixing versions that are deployed on python.microbit.org it is desirable to make a small number of major release.

		We propose an annual cadence for major releases, with an RC released early in the year so that a stable release can be made in July after the school year ends. This gives teachers time to become familiar with it before the school year start. The previous year’s version will remain available after this but will no longer be redirected to via python.microbit.org/latest or python.microbit.org/


		There should be a mechanism to deploy versions of the editor that are not yet considered stable. These will not be widely exposed to the majority of visitors to the site, but will be published for enthusiasts, developers and other interested parties to help test the editor.

		It should be very hard for a naive user to wind up using a beta by accident. (Think, about:config warning in Firefox, etc)

		An unstable beta/RC branch, once retired, should redirect to the latest equivalent branch, or if it can be determined by the version of the branch, the stable version that this version became

		Experimental branches can and will be destroyed with reckless abandon.


		Not every build will be the same as every other, and it should be possible to turn on/off features without forking the codebase using a config file.

		A named deployment could also enable pre-rolled, version specific frozen modules pre-imported. This would help for hardware specific or branded activities that require simple and fast engagement times.


		### Storing the config for each deployment

		The config for any deployment should be stored alongside that deployment so that it can be queried by other versions.


		In these cases, it seems desirable not to prompt the user to move forward.

		{<<I’m up for discussing these workflows, I don’t really want dialogues in front of people, but I also don’t want to move versions under their feet. >>}}

Draft versioning spec for discussion #16

Are you sure you want to change the base?

Draft versioning spec for discussion #16

Conversation

jaustin commented Jan 19, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carlosperate commented Jan 19, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ntoll commented Jan 30, 2017

jaustin commented May 10, 2017

carlosperate commented Jan 19, 2017 •

edited

Loading