Release cycle improvements

[wycats]

Rendered

[stefanpenner]

LGTM.

One question, often we run into scenarios that are hard / quite difficult to actually deprecate. Something like timing changes or a more concrete example, removing chaining of .set(.

In-which part of the release cycle would those sorts of changes fit?

I suspect minor or major release coupled with a blog post?

[rtablada]

Makes sense to me. Not sure about major version ELTS (Enterprise LTS) for security updates and if that should be addressed in this RFC?

[mixonic]

Some thoughts:

Svelte and Private API Deprecations

Given Ember 2.3, there will be several builds:

• Debug has deprecations enabled, and deprecation flagged code remains
• Production has deprecations stripped, but deprecation flagged code remains
• Svelte development build (configurable? how? item by item or with a version target?) has deprecations enabled, but deprecation flag code is stripped. The code removal may remove some deprecations, but others would remain.
• Svelte production build (again, configurable. Can it differ from svelte development? I think no) has deprecations stripped and deprecation flagged code removed.

This makes sense, though it does make my head spin. The minimum time for a deprecated private (heavily used) API to exist would be:

1.13	2.0 (LTS)	2.1	2.2	2.3	2.4 (LTS)	2.5
deprecation
	deprecation
		deprecation	deprecation	deprecation	deprecation
			deprecation	deprecation	deprecation
				deprecation	deprecation
					deprecation
						deprecation

Or put less visually:

release	contains deprecations since
1.13	?? (no policy for private APIs)
2.0	2.0
2.1	2.1
2.2	2.1
2.3	2.1
2.4	2.1
2.5	2.5

Having a formal cycle for private APIs may make the flags and messages difficult to distinguish from public API deprecations and flags. I propose we have a source-code-level way to distinguish a public and private deprecation (Ember.deprectate vs Ember.deprecatePrivate or some LTS term), and possibly report this removal date/plan with the deprecation message. This will make them easier to reason about and automate the removal of.

Public API Changes

If we formalize the LTS cycle and private API cycle, it seems reasonable to formalize the public API cycle as well. In fact, formalizing the private APIs and leaving the public API changes to chance seems poor prioritizing. @wycats is probably feeling the private API pain acutely with Glimmer, but 2.0's crunch has really been about trying to remove major public APIs like controllers. Two ideas come to mind:

• LTS release every 24 weeks (4 minors), Major release every 48 weeks (2 LTS).
• LTS release every 18 weeks (3 minors), Major release every 54 weeks (3 LTS).

Lastly, it would be excellent for this RFC to address concerns that have been voiced about difficult or impossible to deprecate behavior changes. For example:

• Moving to event capture
• Async observers

These are the only two that come to mind today, but the list will not shrink of its own accord. We should have a plan for making these behaviors opt-in or otherwise available in releases before they become default.

[pangratz]

I propose we have a source-code-level way to distinguish a public and private deprecation (Ember.deprectate vs Ember.deprecatePrivate or some LTS term), and possibly report this removal date/plan with the deprecation message. This will make them easier to reason about and automate the removal of.

I like that idea. We could use Babel transformations to transform Ember.deprecate(xxx) into Ember.deprecatedSince("1.13", xxx) when a new release is cut and also remove all Ember.deprecatedSince calls which have a version < X.Y.Z. This would give us finer grained control on what deprecations should be removed in a build.

[mixonic]

To what extent are libraries like liquid-fire or ember-data beholden to the same rules (private API deprecations, svelte builds etc)?

[MiguelMadero]

The goal of the train release model is to eliminate big-bang releases and the attendant stress on releasing particular features by a given date, and the 2.0 release has been far too disruptive to that goal.

That and some of the other problems outlined here would be solved if we had another train coming soon for major releases that we could decide to board or not. Maybe a 24 week cycle would make sense, aligned to LTS and for every 4 releases, there would be an option to break backwards compatibility if needed.

[eccegordo]

Some of the deprecations in 1.13 caught me off guard.
emberjs/ember.js#11492

Makes wonder if there should be some plumbing to categorize or classify deprecations in the future.

Maybe something like:

PRIVATE    --> Your code uses private API and is subject to change, don't say we didn't warn you
URGENT     --> Your code directly uses API that is being removed next release
IMPORTANT  --> Framework change, or your code relies on API behavior that will change eventually in long term support release
SUGGESTION --> Your code triggers legacy feature or is suboptimal for performance, no change immediately required but you might want to look into it.

At the very least some ability to toggle certain deprecations off to ease the process of cleaning up.

Anyway, it looks like you are planning to make the experience about private API warnings better. So good changes all around.

[wycats]

@eccegordo nice! I like those levels 😄

[Gaurav0]

In browsers, if even 1% of web sites are using an API, prefixed, private, whatever, it won't be removed. Doing so would be considered "breaking the web". In Ember 2.0, you are removing APIs that were public and not deprecated in 1.12, and that every single large enterprise app that has been around for more than a few months is still using. How anyone can call that "Stability Without Stagnation" is inconceivable.

At my company, we are now almost 5 months from when we first started trying to migrate to Ember-CLI. We've even employed some very expensive consultants for almost two months now, and we are not even close to having completed the migration. We are still on Ember 1.8. The rate of change is just too high for us. You have left us so far behind we can't even see you any more.

It doesn't matter how long your release cycles are or whether you have LTS releases or not. We need you to actually not deprecate so many things. We need you to not remove APIs we are still using. We need you to SLOW DOWN!

/end rant

[jmurphyau]

Is the delay or converting to Ember CLI because of the frequent changes/depreciations?

Are you trying to move to Ember CLI and upgrade Ember at the same time?

[jmurphyau]

Also, remember that Ember 1.13 should (correct me if I'm wrong someone) have basically the same things as Ember 2 but will have depredations - allowing you to sit at Ember 1.13 with the depreciations and remove them at your own pace

[pixelhandler]

@Gaurav0 what you say is true. I've seen similar pain over the past couple years as well. For those who build big apps the cost to track the current release may not be as valuable to the business stakeholders who need to bring a project to market, then maintain it while continuing to deliver user stories for iterative work. I've seen the bigger apps fall behind as far as six months or a year. And, if behind a year that app is mostly frozen for new features.

I really like where Ember is headed, and have been an early adopter - but for the 'ambitious' promise to developers that comes with a price which product owners need to accept. As developers we need to provide alternatives, e.g. tell them in advance that if the budget doesn't include 1-2 weeks of maintenance per 6 week cycle then the 'Ambitions' app will be an ambitions prototype that will only live a short time and should plan for an end of life or rebuild.

In 1 year everything will change. I hate to admin it, but that is the only real definition of the "Ember Way" that I have experienced, everything is in motion and changing – on a yearly basis. Other enterprise software targets a 3 year major version bump. But this is the Web. So yeah, the enterprise may need to embrace start up mode – if they want to build ambitions apps the way Ember works, which is fine. "Start up mode" equals "breaking things". I've been part of a few big apps built that way. But unfortunately, bringing those apps into sustaining development is more like freezing them or re-writing them; especially if the app lives 1-2 years or more.

[Gaurav0]

@jmurphyau Some of the delay is because of the following:

1. Third party libraries that are still not compatible with Ember-CLI
2. Differences in the behavior of Ember APIs between running in globals mode and in Ember CLI in the same Ember version
3. Errors thrown in Ember public APIs when running in Ember CLI (such as View.create/append)
4. Changing from globals to ES6 modules
5. Changing our build system from grunt to broccoli
6. Changing our continuous integration tools

... and other factors I can't think of at the moment.

But the largest factor of all is that our app has 892 classes.

No, we are not trying to upgrade Ember versions. We are staying with 1.8.1 while migrating to Ember-CLI. It has to be 1.8.1 because the latest stable version of Ember Table still only works on 1.8.1 (there are unstable branches for 1.9 and 1.10. If you are on 1.11 or later you are completely out of luck).

[jmurphyau]

@pixelhandler

ExtJS is the web framework that would suit enterprise management.. It's major releases were:

• 2.0 in 2007
• 3.0 in 2009
• 4.0 in 2011
• 5.0 in 2014

It has enterprise licensing and support - at enterprise cost..

On paper - to a non developer - it's likely ExtJS would win over Ember if most enterprise management had to decide.. It's a hard job trying to sell it to them too

[pixelhandler]

@mixonic @wycats - re: "A recent survey of the Ember ecosystem, which had close to 1,000 respondents, showed that the vast majority of Ember users are using one of the past three versions of Ember." I recall taking a survey and was one of those that could track to the current release. The changes after 1.9 have been much more aggressive so I'm curious if that is still true, also if that metric should be broken down to the lifetime of the app and perhaps the size of the app (lines of code) I'm thinking that the bigger and older apps will not but able to move quickly to the 2.0-beta releases. But that may be OK. It's just that with the tagline "ambitions web applications", developers need to learn to count that cost of keeping up on a 'grand scale', when picking Ember.js that isn't well advertised yet. Honestly over the past year I've been trying to build smaller 'less ambitions apps' so they can survive.

[pixelhandler]

@jmurphyau agreed. A pitch developers need to be prepared to make - is about the size and scope of a project over time, a plan for LTS and possibly end of life for a project.

Ember moves fast, and in reality that means it's better to build smaller less ambitions apps so some can fall behind if needed and others can stay current. And the alternative is to make it known that building an "ambitions web application" will likely change completely in one year. For example, I have a pet project that I fiddle with keeping up to the current beta or canary and test new features on - that is not ambitions at all. But over the past 15 months just fiddling/experimenting I have stats like so: 193 commits / 29,990 ++ / 24,177 -- Thats a lot of change for staying current and experimenting in a trivial app. But a big non-trivial and ambitions app would need a similar percentage of churn to make it from pre 1.x to 2.x.

[workmanw]

I too am sympathetic to the frustrations that @Gaurav0's voiced. I work for a startup that builds enterprise software. We've got quite a bit of code and a pretty complex app that makes use of a lot of Ember APIs. Being small and lean it's not always easy for us to get the cycles to upgrade being so small. In fairness, that's really our problem, not Embers. But I don't think this scenario is unique to us. I think the constant churn can make it tough developers working on a product. Features being introduced and deprecated a few releases later can be a blow when you spend the time adopt them.

I'd also like to point out that "upgrading" doesn't mean just removing the deprecations (at least not to me). Upgrading means refactoring to replace old patterns with new ones (Ex replacing controllers with services where applicable in 1.10).

All that said, I do really appreciate the effort that has gone into 2.0. It's shaking out to be really quite awesome.

[jmurphyau]

Yeah that makes sense.. I think recently the fact that the features being released have been so appealing and rather large (e.g HTMLBars and Glimmer) - changing a lot of the code and subsequently removing the need for a lot of other code - it would have played a large part in the pain being felt when trying to keep up with a Ember versions of late (which I admit I also have)..

I think @mixonic is on the right track mentioning major releases which I couldn't see covered by the RFC.. Searching the page for '3.0' returned nothing...

[stefanpenner]

3. Errors thrown in Ember public APIs when running in Ember CLI (such as View.create/append)

@Gaurav0 we spoke about this was WGE, these are in-fact not public apis, please note @private reference https://github.com/emberjs/ember.js/blob/master/packages/ember-views/lib/views/view.js#L1049-L1066

2. Differences in the behavior of Ember APIs between running in globals mode and in Ember CLI in the same Ember version

You have mentioned this before, It would be great to see a detailed example. It is in-fact true that the behavior will be different, since the resolving strategies are entirely different. Some features really do not translate between the two approaches.

[Gaurav0]

@stefanpenner Yes you are correct. The fact that they were in the guides as the way to instantiate a view in order to test it is completely irrelevant. Same thing with container. And transition. How nice for you. /sarcasm

Actually append was not listed as @Private back in 1.8. https://github.com/emberjs/ember.js/blob/v1.8.1/packages/ember-views/lib/views/view.js#L1397 And doesn't have an underscore.

Edit: My apologies. I should not have reacted with that tone. However, I was already very frustrated and being told by core team members I can't be helped because something is private has become one of my hot buttons.

[stefanpenner]

I am empathetic to many of the above concerns. Unfortunately many/most of the pain points mentioned have been (or aim to be) addressed by the changes that themselves are the pain points being mentioned.

It's a sticky wickit, freeze the world and don't address the current concern or evolve and address the issues.

Both paths have there costs, for those uninterested, freezing the world is available to them. The second path, fixing problems and evolving is available to the rest. Each change ember has and continues to make is considered quite thoroughly. The pros and cons are weighed, a large number of applications are referenced and In the end, if change is overwhelmingly net positive it is accepted.

Each step forward, aims to address of the pains of the past. Obviously mistakes are made, trade-offs occur. I believe @Gaurav0 may have noticed a few.

–––––

We believe strongly that stagnation isn't an option, so this RFC aims to help solidify a sensible path forward. So far, much of this discussion has been focusing on mistakes of the past, not the what this RFC is lacking to improve the next iteration.

[stefanpenner]

Actually append was not listed as @Private back in 1.8. https://github.com/emberjs/ember.js/blob/v1.8.1/packages/ember-views/lib/views/view.js#L1397 And doesn't have an underscore.

Ya this appears to have been somewhat unfortunate, lets prevent it going forward!

In Ember 2.0, you are removing APIs that were public and not deprecated in 1.12

@Gaurav0 if you can open an issue with a list of these APIs. Please do, lets be sure to deprecate and provide the appropriate upgrade guides! We can use your help!

[Gaurav0]

@stefanpenner OK, let's focus on the future. Proposals:

1. A public or widely used private API should be deprecated for at least one year before being removed in a new major version. This will give time for large ambitious apps of the type that is Ember's mission time to refactor.
2. An API which has been exposed in official documentation shall be considered public, regardless of whether this was unintentional. Such an API is likely to be widely used, especially by newcomers.
3. No minor Ember version shall deprecate more than one public or widely used private API. Again, this will allow large, ambitious apps of the type that are Ember's mission the ability to refactor one issue.
4. Each deprecation shall be separately labelled and a public API will be provided to turn them off and on individually. This will allow large ambitious apps of the type that is Ember's mission to deal with each deprecation one at a time instead of all at once.
5. No version shall be released until guides and versioned API documentation is ready. This will allow newcomers the ability to understand the latest release.

This is not stagnation. You may add as many new features in as short a timeframe as you would like. This is solely to allow for stability.

[stefanpenner]

@Gaurav0 thank you for a constructive response.

@Gaurav0 are you also able to open those issues for API's removed in 2.0 but not deprecated in 1.13.x?

[KTKate]

No version shall be released until guides and versioned API documentation is ready.

This x1000000. The documentation and guides should be an integral part of the release. Not just deprecations but additional/better patterns,syntax, etc should be explained.

[stefanpenner]

No version shall be released until guides and versioned API documentation is ready.

This x1000000. The documentation and guides should be an integral part of the release. Not just deprecations but additional/better patterns,syntax, etc should be explained.

Ya I like this one, but we lack people-power on this one. If someone can aid, or has ideas on how to reduce the over-head. We would love to ensure doc parity.

[MiguelMadero]

Going forward, can we use an underscore for  privates? That makes it easier to inspect, avoid in the guides and in our code. 

—
Sent from Mailbox

On Mon, Jun 22, 2015 at 9:36 PM, Stefan Penner [email protected]
wrote:

No version shall be released until guides and versioned API documentation is ready.

This x1000000. The documentation and guides should be an integral part of the release. Not just deprecations but additional/better patterns,syntax, etc should be explained.

Ya I like this one, but we lack people-power on this one. If someone can aid, or has ideas on how to reduce the over-head. We would love to ensure doc parity.

Reply to this email directly or view it on GitHub:
#56 (comment)

[eccegordo]

...

Ya I like this one, but we lack people-power on this one. If someone can aid, or has ideas on how to reduce the over-head. We would love to ensure doc parity.
@stefanpenner

I am wholly sympathetic to this. From the outside it feels like the documentation lags more than it should. What I see is an effective and focused core team with loosely affiliated extended network of willing and capable contributors. Everybody is focused on pushing big initiatives forward, Ember CLI, Glimmer, HTMLBars. This has all been great for the framework. But in all this churn casual users are not able to keep up. And it is not for a lack of code quality it is documentation.

Most of the important bits of info are around just a bit scattered in blog posts, relevant PR discussions, and actual diffs in source code. But unfortunately not everybody is able to keep up with this. Also some stuff is just really obscure like the integration: true mode in the ember test helpers, because it is really new and has no documentation or much publicity.

I think a lot of pain would be solved if the core team would be willing to gate releases to the completion of more documentation. After all code is not complete until it is documented. And by gate I mean not that there is some documentation but that it is "complete" by whatever metric the core team wants to hold it to.

Now on the people power thing. Perhaps there needs to be routine and well publicized calls for action for helping in the documentation. A check list of tasks and todos, but done on a regular cadence. The core team is most capable of doing this because they are closest to the changes.

Whatever happened to the core team meeting minutes? Maybe that should be revived and bookend with calls for action.

I think this could also dove tail well with the need for better testing of releases as they move through canary and beta stages. Have the people doing active documentation actually testing the code and API changes.

A lot of work is just reading existing documentation and QA for gaps and lack of clarity.

Now if this documentation effort holds up the releases people are going to grumble. But so be it. The challenge will be to effectively parcel out the effort and relieve the core team to do what they do best. No single person should be a gate. But lack of good documentation should gate releases. That way a lot of eyes are forced to focus on the problem. We can't get the great new toys unless everybody can enjoy the toys.

Perhaps one strategy is to tie specific deprecations, API changes, and features to a call to action which might include the following:

• A discrete git issue with links to relevant PRs and source code and brief primer on feature and what is needed (checklist). Give people a concrete place to start research and effort.

Deliverables could include

• Coherent code sample strictly correlated to feature or API change
• Review and sign off of code comments in PR (make sure API documentation is up to date. I believe every method (public or private) should have a YUIdoc statement and code example/commentary.
• Some commentary that positions the change, upgrade path, reason for change, etc. Funnel this to release blog posts and actionable updates to guides and API docs.
• Review of guides and existing documentation to catch inconsistencies.
• Specific and actionable asks:
  • write a guide for XYZ
  • write a code sample for XYZ
  • review existing source code in PR 123

I think if this is baked into the release process a lot will get done. Many people are eager and willing, most just need a little direction, permission and gentle prompting.

By the way @stefanpenner I must say I always appreciate your unflappable tone in these threads. You tend to just take this stuff in stride and gently remind everybody that contributions are welcome. Never snarky, just patient and encouraging no matter how frustrated people get. I am always impressed.

Everybody else, let's roll up our sleeves and pitch in. When a lot of people get involved great things happen. There was a big documentation push in the run up to 1.0 in 2013. Then in 2014 there was a big push to fix testing guides.

Now we have the opportunity to make 2.0 guides and documentation world class. Now's your time to get your name in lights. 😄

[green-arrow]

+1 to @eccegordo

If we could capture all of that information and put out that call to action for documentation, I would love to chip in. Sometimes it's difficult to know where to start. If we can publicize exactly what needs to be done, it would certainly help.

[trek]

@eccegordo the plan starting in 2.0 is to not allow any features in that don't have associated documentation and guide update PRs.

[stefanpenner]

One thing worth noting, until somewhat recently we didn't have versioned api docs. Although it had been attempted several times until the recent push all past attempts never hit completion.

I suspect some of the doc pain described, is actually already no longer a thing, or at least already on the path described. Ultimately unlocked by the somewhat recent website improvements.

As for total doc coverage, and very specific release gating. Let's move that to another issue, as I believe it should be tackled separately. If done correctly it will benefit the LTS by virtue of existing.

And finally, we should in-fact revive the meeting minutes. I do believe that will help close the loop, and the extra context it could provide will likely further enable the success of the community. I'll take minutes this week.

[rwjblue]

Addressing a couple points from #56 (comment) by @Gaurav0:

A public or widely used private API should be deprecated for at least one year before being removed in a new major version.

The major pain point here (that I have felt quite acutely just like all of y'all) is that having a deprecation available in a single release makes it extremely difficult to update addons and apps. This RFC has a similar perspective it chose to go with a somewhat simpler rule: a deprecation must have existed in an LTS release prior to removal of private API's (public API's already have to wait for the next major release due to SemVer requirements). Perhaps we should modify the language slightly to make it clear that the rule also applies to public API's, this would clearly only apply to the end of a major version, but it might be nice to have it specifically spelled out...

No minor Ember version shall deprecate more than one public or widely used private API. Again, this will allow large, ambitious apps of the type that are Ember's mission the ability to refactor one issue.

To me, this seems to boil down to the fact that deprecations should be steadily done over time, instead of a whole mess of deprecations all at once (I could be misinterpreting your intent though). I definitely agree that 1.13 has a massive number of deprecations that should have been released over time in multiple versions.

However, I do not think that it would be possible to limit each release to "a single deprecation". It is common to have multiple related things that need to be deprecated at once essentially making a "group" of deprecations (for example deprecating Ember.View also requires deprecating Ember.ContainerView).

An API which has been exposed in official documentation shall be considered public, regardless of whether this was unintentional. Such an API is likely to be widely used, especially by newcomers.

Unfortunately, we didn't have very good requirements about adding API documentation. I recently added a rule to our CI system that required every documentation block to be explicitly labeled as @public or @private to make it extremely clear if a thing is public or not:

• If it is documented and labeled as @public it is public.
• If it isn't documented or is labeled as @private it is private.

It is likely that I messed up a few specific API's when I did that sweep (and accidentally labeled things @private when they shouldn't have been), but once discovered it should be easily fixed with a documentation PR.

These changes should make it much easier to ensure that things ending up in the guides are in fact considered public API (this was not previously true).

Each deprecation shall be separately labelled and a public API will be provided to turn them off and on individually.

Completely agreed, this is is the exact point of #65. I am actively working on an addon that allows an app to "blacklist" specific deprecations via ember-cli build time configuration, and deal with them one at a time. I hope to have that addon ready for folks to test out in the next week or two.

No version shall be released until guides and versioned API documentation is ready.

We have already started gating new features on guides/api docs, and I think that @eccegordo has some good ideas in his comment above. We will continue to get better thanks to y'alls feedback.

[rwjblue]

@eccegordo (from #56 (comment)):

There was quite a lot of information there, most of which I think I agree with, but it is not directly related to this RFC. One thing to keep in mind is that mustering a large group of people can often be as much or more work that just doing it yourself. In the end, community engagement is very valuable for us so it is very likely to be worth it, but I figured I throw it out there as a potential issue.

Would you mind opening an issue here in the RFC's repo with your suggestion? I think it has lots of merit and we should iterate on the idea in an issue then someone can RFC the specific proposal once we have narrowed in on it...

[rwjblue]

@stefanpenner (from #56 (comment)):

One thing worth noting, until somewhat recently we didn't have versioned api docs.

Technically, we still do not have versioned API docs. There is huge start located at https://github.com/emberjs/api, but it isn't deployed yet. At this point, we still release API docs to the main website (and there is only a single copy).

We do have versioned guides, and they are helping quite a bit already IMHO.

As for total doc coverage, and very specific release gating. Let's move that to another issue, as I believe it should be tackled separately.

Agreed.

And finally, we should in-fact revive the meeting minutes.

Agreed.

I'll take minutes this week.

Thank you!

[2468ben]

Technically, we still do not have versioned API docs. There is huge start located at https://github.com/emberjs/api, but it isn't deployed yet. At this point, we still release API docs to the main website (and there is only a single copy).

@rwjblue Thanks for starting on it. Once you're all up and running on that repo, can they get git-tagged with the version numbers as they're updated? That ability to view an "official" git diff between two api versions would be the missing gear in my upgrade treadmill. And then we have a really precise list of changes we can add and check off in our own respective issue trackers, instead of just "PRIORITY: shut the console up" :)

edit: not belittling the guides, release notes and changelogs, they're all great, but an API diff would be for anyone needing the complete level of details.

[rwjblue]

@2468ben (from #56 (comment)):

Once you're all up and running on that repo, can they get git-tagged with the version numbers as they're updated?

They will likely not be tagged in that repo (that is the actual ember-cli app and doesn't contain the "real" docs), but the docs will definitely be in a repo somewhere (likely github.com/emberjs/api.emberjs.com when we are ready to go).

Also, as a side note, you can see the diff of each version via components/ember@1.12.0...1.13.2 (though that is for code and docs not just the docs).

[eccegordo]

@trek good to know that this documentation process is going to be more formalized in 2.0

@rwjblue I agree, there are definitely implementation details to consider, and we all want a process that scales. Someone has to review documentation PRs for accuracy. I will see about getting an RFC started to discuss the finer points.

I think my main take away is that there needs to be more publicity around calls to action. With well defined actionable deliverables. We get that right a lot of the other details will take care of themselves. At least that is my hope.

Obviously sometimes setting up a request and delegating tasks can be more work than just fixing and closing a specific issue. So a balance has to be struck.

[davidgoli]

@eccegordo:

I think a lot of pain would be solved if the core team would be willing to gate releases to the completion of more documentation. After all code is not complete until it is documented. And by gate I mean not that there is some documentation but that it is "complete" by whatever metric the core team wants to hold it to.
...
Now if this documentation effort holds up the releases people are going to grumble. But so be it. The challenge will be to effectively parcel out the effort and relieve the core team to do what they do best. No single person should be a gate. But lack of good documentation should gate releases. That way a lot of eyes are forced to focus on the problem. We can't get the great new toys unless everybody can enjoy the toys.

YES ++

The fact that 1.13 was released without updated guides is really discouraging to me as an Ember adopter. It may be much faster, the features may be much cooler, but to me, they don't exist unless I can learn how to use them from documentation. Documentation IS feature work.

[stefanpenner]

YES ++

The fact that 1.13 was released without updated guides is really discouraging to me as an Ember adopter. It may be much faster, the features may be much cooler, but to me, they don't exist unless I can learn how to use them from documentation. Documentation IS feature work

This doesn't appear relevant to a discussion on LTS. Although clearly an issue, this isn't the correct venue.

[KTKate]

I think is relevant to a discussion about improving the release cycle... unless only collaborators are intended to actually use Ember. The 'lockstep' of Ember Data only confused things even more since 1.13 in Ember Data is a breaking release while 1.13 in Ember is supposedly not. (ArrayControllers seem to have been broken.)

Both, Ember/Ember Data 1.13's seem to involve deprecations that were never warned. How this can be avoided in the future OR how can people be sure they know what they're getting into when they update are important factors to consider in the release cycle imo. If there was documentation (and to me the guides are part of the documentation) involved in every release then things would be so much more user friendly. The question of "is my project not working because something is different in this release of Ember or because I'm doing something wrong?" would not be so difficult to answer.

[harbulot]

Just a quick note on the topic of migration to Ember-CLI raised by @Gaurav0 and documentation: as discussed in ember-cli/ember-cli#3100 (comment), I still think it would be better to merge back the CLI and non-CLI documentations together, to avoid the extra effort required by keeping in sync the two sets of documentations (since it's likely one would lag behind the other, which may itself lag behind the actual code).
(Part of that discussion was also about LTS and integration with larger pieces of software.)

[Gaurav0]

I'm very glad to see the core team has admitted in their meeting that "there are real issues" and that an LTS release is not really a solution. Notes here: https://github.com/emberjs/core-notes/blob/master/ember.js/2015-06/june-26.md . I'm sorry though that they see this as something they should keep in mind for 3.0 rather than considering if they can do anything about the pain we are experiencing now. I'm also sorry there was no mention of my proposals given here: #56 (comment)

I hope to once again emphasize that API churn, not a fast release cycle, is the real problem. Lack of documentation in time for a release is a huge, visible symptom of that problem.

[stefanpenner]

I'm very glad to see the core team has admitted in their meeting that "there are real issues" and that an LTS release is not really a solution. Notes here: https://github.com/emberjs/core-notes/blob/master/ember.js/2015-06/june-26.md . I'm sorry though that they see this as something they should keep in mind for 3.0 rather than considering if they can do anything about the pain we are experiencing now. I'm also sorry there was no mention of my proposals given here: #56 (comment)

I think you misread. That point was strictly about LTS, not about additional concerns people have raised here. What was mentioned was that we should also need keep this in mind during the 2x to 3x phase, which doesn't preclude or stop the continued effort on making 1x to 2x as nice as possible.

As we upgrade apps, we keep finding things to improve and smooth things out.

For some reason this conversation keeps getting off topic. LTS is the topic, not all potential pains with release or API churn.

––––

My thoughts, partially extracted from core team conversations. (We are still working on better minute taking, I hope the meeting minutes will get better over time). it is worth nothing there are 42 comments in this thread, and our meetings are very time limited.

A public or widely used private API should be deprecated for at least one year before being removed in a new major version. This will give time for large ambitious apps of the type that is Ember's mission time to refactor.

An API which has been exposed in official documentation shall be considered public, regardless of whether this was unintentional. Such an API is likely to be widely used, especially by newcomers.

Sounds very reasonable, we have tried to make this be truth. Any deviation from this pattern has been either don unintentionally (which we depend on community issue reports to report) or as a last resort. Which requires a very detailed and well thought on transition path.

As mentioned deviations must be reported as issues, or we are unaware.

No minor Ember version shall deprecate more than one public or widely used private API. Again, this will allow large, ambitious apps of the type that are Ember's mission the ability to refactor one issue.

This I do not believe I can get behind, at least not in the way it was written. In-order to phase out concepts we explicitly provide fine grained deprecations to aid in incremental transitions.

For example: In ember 2.0, IE8 is not longer supported, so ES5 polyfils have been removed. As such each direct reference polyfill is deprecated individually, this enables clear and concise deprecations. If the proposed mandate is followed, it would take several years to make this transition.

Something seems extremely funky about that.

Maybe something I could get behind is, no removing multiple truly foundational concepts but unrelated concepts at once.

Each deprecation shall be separately labelled and a public API will be provided to turn them off and on individually. This will allow large ambitious apps of the type that is Ember's mission to deal with each deprecation one at a time instead of all at once.

Yup, this is actually covered by another RFC #65

No version shall be released until guides and versioned API documentation is ready. This will allow newcomers the ability to understand the latest release.

Yup this is a good one, we still lack some infrastructure (like version API site, although guides is versioned). Docs and guides are likely the hardest thing, as such we are in the process of assembling a docs sub-team.

We hope the more dedicated effort, weekly stand-ups and community involvement will enable some really great docs.

[Gaurav0]

Thanks for replying, @stefanpenner ! I really appreciate it.

For some reason this conversation keeps getting off topic. LTS is the topic, not all potential pains with release or API churn.

LTS is justified on the basis of helping us enterprise users better deal with exactly these issues. As I have said, an LTS release is not going to help if the pace of API churn is the same. I am asking for us to seriously consider the problem itself, and not paper over it.

Maybe something I could get behind is, no removing multiple truly foundational concepts but unrelated concepts at once.

I am trying to start a conversation with my proposals. A compromise is indeed possible. What I'm trying to get at is not to repeat the experience people are having trying to upgrade to recent Ember versions, and especially 1.13.

[stefanpenner]

As I have said, an LTS release is not going to help if the pace of API churn is the same.

Then lets assume it wont be the same. As you pointed out, @wycats mentioned that we will be using these upgrade transitions as a template for future transitions.

If we look closely at the 1.x -> 2 deprecations, they are all geared towards removing hazards and the continued effort to carve out a stable sustainable core. Which I would argue, is where you would like us to be.

That leaves us with a transition. Luckily, this transition is of upmost importance to everyone involved.

It does require issues to reported. @Gaurav0 can you report the issues you mentioned above?

In the interim, as new upgrade hazards are discovered, they are dealt with quickly. As more and more of us upgrade more apps, we catch unexpected hick-ups fix them, and others benefit.

I am trying to start a conversation with my proposals. A compromise is indeed possible. What I'm trying to get at is not to repeat the experience people are having trying to upgrade to recent Ember versions, and especially 1.13.

Yes, but this appears in-favor of LTS. (Making minor releases more and more seamless)

Additionally, please report issues you have upgrading. We cannot fix them, if they are not reported.

[2468ben]

The compatibility matrix at https://github.com/Vestorly/torii is a great example to me for helping communicate an addon's support while someone transitions from 1.x -> 1.13.

Let's say in a few months the addons all have 2.0-compatible versions; there are still going to be LTS's and rolling features/deprecations/etc as 2.x rolls on. What's your ideal for how addons should follow along these release cycles? It seems like it would be addons releasing something for each Ember LTS with a README matrix to list the version "pairs".