[policy, no patch] Beta-to-beta upgrade path and data model stability

The following issues are fixing missing items or shortcomings of the schema system and/or data structure. Most are not beta blockers. While most would not change data structure, it would be good to have a stand on whether the description of the data structure changing is considered change of the data structure. For SQL it would sure be because you cannot store data without describing the structure properly. For config, you can freely do it the other way around. Although schemas are not mandatory we are making a commitment to describe all our data structure in core. So would be good to have a stand on these vs. the beta:

• Several missing or broken config schemas: #2268975: Fix named schema elements missing when installing Drupal
• Missing schema for migrations: #2183957: Provide configuration schema for Migration module
• Incorrect schema use on language overrides: #2224887: Language configuration overrides should have their own storage
• Missing config schema for content_translation.settings: #2224761: Add a generic way to add third party configuration on configuration entities and implement for field configuration

These are all the major ones we know about but there may be smaller ones lurking.

We might want to take into consideration the impact of the schema change. For example, a simple addition of a database column that is automatically populated is not very disruptive.

One concrete example: #2265847: [PP-0.5] Regression from D7: default titles of customized menu links aren't translated is currently a critical beta blocker postponed on #2256497: [meta] Menu Links - New Plan for the Homestretch, which is not currently prioritized as critical. If we get down to 0 other beta blockers and that latter issue still isn't in, we'll need to decide whether to implement #2265847: [PP-0.5] Regression from D7: default titles of customized menu links aren't translated by adding a 'default_title' column to the {menu_link} table prior to releasing the beta. My vote would be no, unless at that time we're 99% convinced that we're giving up on #2256497: [meta] Menu Links - New Plan for the Homestretch, because I don't see it as in any way disruptive to add that db column closer to RC.

PS: this is not the issue in which to discuss whether #2256497: [meta] Menu Links - New Plan for the Homestretch should be critical. I only bring #2265847: [PP-0.5] Regression from D7: default titles of customized menu links aren't translated up as an example of something that I think can go in after beta, if it needs to, without causing disruption, even though technically it's a schema change. There might be other examples too. In general, I think our "stable data model" criterion for beta is a good one, but it's ok for core maintainers to use their common sense in making exceptions.

In general, we allow data model changes where necessary to resolve critical issues.

Does this imply that we do not allow it if it's only a major issue? I don't think it should imply that; rather, like in all other areas, I think core maintainers should be able to approve a major issue for a data model change if they believe the benefit of the issue outweighs the disruption of the change.

we need to go back to the idea that changing the data model is something we do judiciously. So I would support "officially" restricting it to only criticals, or criticals and majors perhaps

Right. I agree it should be judicious. But I think Major issues approved by core maintainers would still qualify as judicious. So I'm concerned about the statement "we allow data model changes where necessary to resolve critical issues" being interpreted as "we allow data model changes only where necessary to resolve critical issues". Perhaps that's not a valid concern, since it's not what the sentence says :)

The worst thing about the 18 months of Drupal 7 was trying to fix critical bugs that required an ugprade path, let's not kill ourselves again. So a looser approach for the first beta releases sounds very sensible.

For upgrade path testing,we could dump a snapshot database of a beta install, and test updating that to the latest code base (with a few basic assertions after the upgrade has completed), that ought to flush out complete site breakage - but we should only add that once we're planning to actually fix every upgrade issue that gets thrown up by that, not before.

Major bugs/tasks that affect schema probably have to be case by case. How major the issue is vs. how much of a schema change it is. Dropping/adding columns and indexes is a lot less disruptive than changing types/lengths etc. or updating values. Also whether not doing it means postponing to 8.1.x or 9.0.x.

However if possible we should try to triage the major issues prior to beta and get known schema changes tagged correctly - there could be very disruptive updates in there lurking (thinking particularly of postgresql/sqlite indexes etc. which would require an upgrade path or reinstall once we fix that).

There has to be an upgrade path from the final beta release to the first release candidate, whatever happens prior that seems 100% required.

If it turns out sites are desperate for a more stable upgrade path than we're managing to provide in core, then there's the option of opening major issues for changes that went in without an upgrade path, or reviving http://drupal.org/project/head2head or both.

Given we're already 3.5 years into the development of Drupal 8, I'm happy to explore ideas to remove barriers to core developers and help it get released sooner. Only worrying about the upgrade path during the final transition from beta > RC would be completely fine with me, personally. Beta-to-beta upgrades was not something we did in Drupal 7 and the two big sites that built while still in alpha/beta—Examiner and Drupal Gardens—were able to function fine without it. I consider it a "nice to have" for Drupal 8, one that we hope would result in more people building on D8 sooner, but that seems like a very big gamble against the mountain of data we have that shows that once we do require X-to-X upgrades, everything gets a lot trickier to solve.

One thing I'd add to the proposal. I've resisted so far putting either a dev tarball or the alpha releases on http://drupal.org/project/drupal.

Let's continue to not have those releases on the project page until we're making a decent effort to support the beta-beta upgrade path. Breaking sites between betas will annoy some people who get core via git, but it will almost certainly annoy a higher percentage of people who get core via a tarball.

+1.

Should we move this here? I haven't seen any huge opposition to anything being proposed yet.

List looks good. I'd probably say 'beta 2 or 3'.

I'd also add we're not going to do anything special for service renames or similar which would require a container rebuild. Similarly anything like adding additional configuration dependencies which might involve updating active config. That can mean either mean (fixable but annoying) fatal errors after pull, or that the site is inconsistent with how it would be had there been a fresh install.

edit: that might already be covered under 'schema changes' since these are more minor, but longer list of 'things we will not fix' means less chance of issues getting opened maybe.

A "best effort" upgrade path seems a poor compromise to me, if it means we're going to end up doing most of the work, but people still won't be able to actually use the upgrade path because a key issue or two is missing. Have we got any idea of how often a beta-beta upgrade path would end up being used?

The main advantage I see of a beta-beta upgrade path is to force us to test the current upgrade path and uncover any bugs sooner rather than later. But I don't think the sort of bugs we'd be likely to find would be difficult to fix closer to release.

• "Best effort" means that there are circumstances where we will knowingly commit a patch that could break someone's data. Rare circumstances that we will try to avoid, but it might happen.
• "Best effort" implies a continuum to something that's binary: Either there's a commitment to a supported upgrade path, or there isn't.
• As an expert employed to advise content creators who are making potentially expensive decisions, right now, I need to know when it's going to be safe to start entering data into a Drupal installation.
• In the post quoted in the issue summary, Dries himself says that was beta1, which will occur when there are no critical issues in the queue.
• This proposal is backing down from that very clear and highly publicized statement.

Instead, I need to wait for the 'final beta'? What does that mean, and when will that happen? What's the definition of 'beta 2'?

In the post quoted in the issue summary, Dries himself says that was beta1, which will occur when there are no critical issues in the queue.

Please find that sentence in the post and quote it. Beta1 is when there are no 'critical API/data model changes', not when there are no critical issues at all - that's RC1. There's currently ~15 beta blockers and ~85 other critical issues in the queue.

We won't knowingly go into the beta with known critical data model changes left, that's why #2183231: Make ContentEntityDatabaseStorage generate static database schemas for content entities and similar issues are tagged as beta blocking.

However, once an upgrade path is properly supported, this means that those 85 critical issues (and the 100 or so more that will likely be opened and fixed before we get to RC1 that aren't even known about yet) have to do double if not quintuple the work in order to support it - write the upgrade path, write tests for the upgrade path, generate data sets that are realistic enough for the tests to be useful - sometimes for changes that would otherwise be a one or two line patch. Hence, prematurely announcing a beta/stable upgrade path has serious potential to delay the release as a whole, as well as the fixes for individual critical bugs.

This issue is trying to deal with the fact that there are two criteria for the beta:

1. You can reasonably expect to port a module and not have to deal with far-reaching API changes again - at least with 'critical APIs' that are required to build most modules.

2. You can very carefully start building sites and we won't go out of our way to break your data.

#1 is a lot easier to guarantee, and with much less consequences if something unexpected comes up than #2.

If Drupal.org supported it, I'd happily do gamma releases for the head2head upgrade path.

Going to go ahead and mark this fixed. We'll need to be very clear with the initial beta 1 release announcement what's happening.

Er. Shouldn't Dries sign off on this before we mark it fixed? While I think it completely makes sense, it's nevertheless a pretty large departure from what was previously communicated out.

@webchick I failed to mention this in my comment, but I marked it fixed while on the phone to Dries and alexpott. Which explains but does not excuse the very short comment...

catch: Oh, cool. Thanks. :)

xjm: That "best-effort" doesn't start until at least beta2 and possibly much later. Dries's post says it affects "between beta releases," with no qualifier.

And then there's this earlier post: http://buytaert.net/drupal-8-apis-are-freezing-but-not-frozen

"What can I expect from beta releases?
Beta 1 will still be the point at which we encourage any interested site builders to try out the beta and provide feedback on it, so it will include an upgrade path from Drupal 7 for testing."

So while we know that the later post was an "update" to that original one, both the big huge graphic and the text indicate in "freezing but not frozen" indicate that site builders should start using it at beta1. (IIRC Dries's Prague keynote said the same thing.)

So we may want to do another piece of communication about this decision, including when and how site builders who *do* want to build on D8 while it's still somewhat malleable (but don't want to or can't write their own upgrade paths) will know when the core team has introduced X-to-X upgrades. (Read the release notes? Watch for an announcement on Dries's blog? etc.)

Yep this needs very clear explanation on the initial beta release notes.

I am not sure if it needs a specific post before there's a beta or not - maybe something in g.d.o/core pointing to this issue?

One thing worth pointing out, if you are developing a new site (or working on an upgrade from 6/7), beta is still a good point to start doing that in many cases.

It's a good idea if your workflow is to re-install your site after each major change. Every development project (that was not already launched) I've worked on in the past 4-5 years has had this workflow until the last possible moment. Usually anything between the first third and the first 4/5ths of the initial development there is no central database and you just install and/or install + migrate every so often. Custom code + default config entities might need updating occasionally - if you get hit by an API change.

What would not be a good idea would be a personal blog that takes less than a day to get set up then launches - however technically we also shouldn't be recommending that until all known security issues are fixed as well, which will likely be RC.

Yeah, g.d.o/core might work for now. Just anything to get it on the radar of more than 15 people. ;)

Sorry I'm going to re-open this.

#2180389: Switch from item-based to time-based index throttling requires a small change to a static configuration file and schema.

For static configuration, changing the schema and adding/updating a value is an easy change to make, and I think we'll have to do that for performance and usability issues past beta.

I'd be more wary about changing config schema for configuration entities since those can be shipped by contrib/custom modules. Possibly a clarification that changes to static configuration are allowed is enough, but needs sorting out.

The issue summary here is pretty clear about what the data model is: database schema and config schema, right?

It isn't clear about what the policy is for whether this data model can change at all after beta. It sort of implies you cannot change the data model at all, but apparently you can make some changes...

So this policy should clarify:

- Can you add things to the data model? This would include:
- Adding new database tables
- Adding new config entities
- Adding new database table fields
- Adding to config schema
- Adding new shipped config files
- Adding lines to existing shipped config files

- Can you make any changes to the existing data model, and if so, are there restrictions to why/when? [This would mean changing existing database table fields and config schema.]

- If you do make changes to the data model, what do you need to do (like make an upgrade path)?

So for critical issues, you can do any of those things at any time up until RC, or possibly after if there's absolutely no other way to fix. Once we support beta-to-beta upgrade paths, you can do any of those things if you also supply a hook_update_N().

For non-critical issues, I'd say the following is definitely OK:

- changing static configuration files/schema (there's no real benefit to them being locked down, and we're just going to have to change some)
- adding new static config files, config entities, or entire tables (within reason)
- adding columns to tables (within reason)
- adding indexes anywhere

(same rule with hook_update_N() once beta-to-beta updates are supported).

Any changes to configuration entities or content entities we'd have to be a lot more careful with. For critical issues we'll have to do it and provide upgrade path when that's necessary. Non-critical issues it'll probably have to be case by case.

What this doesn't cover is changes to things like lock/queue/cache schema - usually we only change those for critical issues anyway, but since the tables aren't part of the API at all the main issue is a safe upgrade path.

We also need to clarify this for minor vs. patch-level releases, most of these would probably need to be 'minor version target' because we want to avoid any potential upgrade headaches in 8.0.1 etc.

#29 makes sense to me. But everything is with the caveat within reason - once we cut the beta we want do avoid https://socketwench.github.io/portingFlagToDrupal8/#/2/2 as much as possible - and definitely get really good at doing 8.x to 8.x change records.

Now duplicate of #2550249: [meta] Document @internal APIs both explicitly in phpdoc and implicitly in d.o documentation.