Either the changes are too big to be documented in time, or the release cycles are too short, or perhaps both.
If I were to start this topic again, I’d probably re-title it “Issues with the release cycle” (or something). I suppose my point is that, the framework has gone through some pretty drastic changes in it’s short lifespan. Whilst the API has been developed in accordance with semantic versioning, it hides the difficulties in experience of developing Ember application. This is addressed by @wycats in the release cycle RFC section: Problems with the 1.x Model:
While the SemVer guarantees promise that your code will continue working, they do not address changes to idiomatic Ember usage, which can change over time. In practice, this means that there can be churn in the experience of using Ember without actual breakages.
This is exactly what I’m getting at, so it’s great to hear it being addressed. I probably go a little further and rather than calling it “idiomatic Ember usage”, call it “core Ember concepts”. Ember is looking like quite a different framework to what it was a couple of years ago. Take Components for example. Components did not exist in the framework until 1.0 RC6, almost a year after 1.0 pre, and therefore weren’t considered to be central to the core concepts. Now they are set to take a much larger role. (Granted, this was pre 1.0, but it demonstrates the issue.)
I think this hits the nail on the head. The problem isn’t necessarily churn intrinsically, but rather that we are shipping features without meeting all of the requirements for a new feature. Documentation is one big area where we have skimped too much.
What I think we need to do (and this is something I have privately advocated for a while), is to give the documentation a feature flagging infrastructure that maps documentation feature names to their associated Ember feature. That way, people can write documentation before the feature has landed, and we can flip a switch once the feature is ready. This would also make it easier to mandate documentation as a condition of "Go"ing a feature.
A side benefit is that it would be possible to build a “Canary” version of the guides with all of the in-progress features, or maybe even a tailored set of guides with just the features you are interested in.
Totally disagree. The problem is definitely API churn. That is the major cause of pain while upgrading. When you have 25+ (counting all 1.13 Ember releases together) classes and methods deprecated and then removed just six weeks later, more documentation cannot fix the upgrade pain by itself.
Can you help me to understand here? You talked about 25 releases, but the only releases that should have removed public APIs was 2.0 (which hasn’t yet been released!).
There have been a number of private APIs that have changed throughout the 1.x series, which is what caused us to acquire the “heavily used private API” policy and the proposals around a longer deprecation cycle for them for LTS releases.
Are you mostly talking about private API removals, accidental public API breakage, or breakage in the 2.0 release itself?
Is not 1.13 not kind of a special case though? As the last of the 1.x
series, I think it’s been stated elsewhere that 1.13 will continue to get
patched for a while longer to minimize the pain of hopping over to the 2.x
series, which also gives people a more time to clear their deprecations
while getting long(er) term support for security, etc. I’m not sure what a
better way to handle that would have been?
Yes. 1.13 is the only release so far that has included deprecations to public APIs that will be removed in the next release. The next time that will happen will be in the lead-up to 3.0.
@guarav has some reasonable critiques about the exact details of what we have done here. Keep in mind, though, that Ember 2.0 is the first time a major library on a six-week-release cycle has bumped a major version. We’re still learning a lot, and definitely expect to make fewer mistakes in the 3.0 major release.
Part of our strategy has been to aggressively communicate what we’re doing and our plans. While that has not eliminated the pain, it at least has made our plans clear, and has given people an opportunity to weigh in as we have progressed.
Going forward, I really recommend that people who care a lot about improving the process contribute to other ongoing proposals to improve things in the 2.x cycle like Release Cycle Improvements and Deprecation Warning Handlers. If you feel like the process isn’t going well for a specific significant change (like, say, ES6 modules), please raise the alarm.
Great conversation. My two cents, expanding on some points others have made:
I get the point that developers can choose how often to upgrade. Let’s say I’m on Ember 1.11 and want to wait a year to upgrade. Where do I find a consistent set of 1.11 docs for me and my devs to look at?
The deprecation strategy is cool. However, even with watson and Ember inspector, it’s still underpowered. I can’t see where the deprecations are in my code. I am also too stupid to figure out how to turn off the ones I don’t want to see.
I can’t help but feeling that there is a bit of a self-reinforcing cycle going on in the six-week release plan. The releases have more bugs than they should. It’s not really quite good enough to say well, then, report them. The docs and migration guides aren’t ready, as others have mentioned. Not all the features are there, so people who want some of the features have to upgrade and then upgrade again.
I don’t know if there’s such a thing as best practices in upgrade cycles. But I have to agree with the great majority of points made by @domchristie pointing to the notion that six weeks is too fast.
So I’m thinking… What would motivate app developers to participate in some kind of beta feedback program?
I work on an app that has been around for 1-3 years (actually a group of apps with one API). Early on the team was able to use beta during development and on releases ship stable, and when building new apps use canary. Over time the code base grew. The amount of code is now around 45K lines of code for client apps about 35K for API and another 30K-ish for core libs used across the apps.
We we able to keep various apps at different versions until HTMLBars came along; then had one template compiler to rule the platform. This is when we no longer could keep up with beta testing. And, since we still had an old build pipeline (ember-rails) we run into a lot of difficulty with compatibility during an ember upgrade (ember-cli was not stable until 1.13.x which is very recent history).
We were not able to make to the 1.13 release at all. We made it to the 1.12 after 1.13 already shipped.
Personally I am very motivated to participating in testing beta and providing feedback. But I’ll need to re-factor a large chuck of work into Ember-CLI to decouple the build dependency on the template compiler and re-think if I want templates at all in the core libs; those will become addons. I imagine that I will be able to participate in testing the Beta release channel again, toward the end of the 2015.
It was a great experience to be able to participate in the beta release cycle (for us that ended when template compiling becoming coupled to all the components in the system). For a small team it will take time to decouple all the parts of the system to again enjoy the privilege of participating in the beta releases. It was well worth it and soon it will be well worth it again for our team. It’s really amazing to be able to build great apps with a small team and a great framework.
I encourage everyone to get involved with beta testing and give feedback to the core team. Maybe there could even be some official beta feedback channel for beta testing to become more attractive to developers who build a product.
Please don’t ever do this again. Wait at least one full release.
When I try to discuss issues on topics such as these I am repeatedly told I am “off topic”.
Being able to keep up is a necessary precondition to being able to participate in a beta program.
Until 2.0, you can’t without an addon.
I don’t know how it is others with larger codebases than mine can keep up. Maybe they have more people to help. Or maybe I’m doing things wrong, but if so I don’t know what it is. But please stop telling me there is no problem. Or that things will be better in 2.0, because it won’t matter if we can’t get there.
As a real old timer I would like to comment on the (frustrations of the ember) release cycle.
brag/
My old-timer credentials:
First computer used vacuum tubes, drum memory and MUCH paper tape.
The OS was a grad student with a cot.
First language was ACT III (a predecessor of FORTRAN).
Have programmed in ACT III, FORTRAN, IBM 360, PDP-10, PDP-11, 6800, F8, 8800 and later assembly languages, JOVIAL, Ada (National Lecturer for
ACM on Ada), C, C++, Javascript, Ruby.
Developed software for:
Testing Minuteman III Post Boost Propulsion System
Testing Lunar Module Ascent Engine
Simulating Radar/Countermeasures interaction (Hybrid and pure digital)
Image Processing software for USAF LANTIRN pod.
Image Processing software for FBI’s Automatic Fingerprint Identification System (have patent). Expert witness on Automatic Fingerprint Identification.
Developed Websites (pure Javascript and Ruby/Rails) for my daughter’s Real Estate Business - couldn’t stay retired forever
/brag
In other words, I have seen a lot in the past 50+years. When I first encountered Ember I was impressed by its scope and capabilities, especially when combined with ember-cli. It sounded just like the tool I needed. That was about 3 months ago. Unfortunately, in that time, I have NOT been able to create a new app on my own. In fact, I have tried a large number of tutorials, etc. to see what a modern (in light of the change cycle) ember app looks like. Of that number, only two have worked - the rest failed because the configuration of ember, ember-cli, ember data and various addons, combined with the Documentation, was out of date.
I have seen a number of posts that say that ember has a steep learning curve. That doesn’t bother me, I’ve been there. The problem I have is that Ember and its environment is changing so fast that the mountain is moving away faster than I can climb it . It is so bad that I have taken to ignoring any tutorials/posts dated before April 2015. The biggest problem I have is that the examples all cover the simple ToDo app (or equivalent), with the exception of many “auth” apps, all of which seem to hide the basics somewhere. I have not been able to find how to implement the less common, but still needed for anything beyond a toy, ember constructs. I need easily findable ways to structure the interface to (particularly) and from the back end. They may be documented somewhere in the adapter/serializer docs, but I can’t find them. The guides and api portion of emberjs.com require a level of familiarity with ember that is not available to the ember noob (even one with 55 years experience). It is like telling someone who never took algebra “That’s easy, just use the quadradic equation”
For those of you who read this far, thanks for listening to my frustrations. I believe in ember, and would like to take advantage of its capabilities in my next apps.
I have one app in particular that is written in RoR that works great on home/office internet connections but is barely usable on 4G cell connections - it needs too much interaction with the server. Ember seems to be the solution to this problem, if only it would hold still long enough for me to learn and use it.
@donz well said, It may get better soon the core team has said a few times that they won’t merge features without docs and there is doc team working on updating the tutorials. But you’re right the only way to understand Ember well is to develop with it and get involved asking questions in the community forum and chat channels, irc and slack. There is some effort also using badges to identify blog/tutorial content so that the reader understands the version of Ember that the article is based on.
I have found a decent, hard-won and mostly manual workflow for updating code and staying up to date myself, and it goes by:
rejecting everything older than 3 months from search results (but as I know a bit of Ember’s feature history, I can gut-feeling adjust the constraint)
Read the blog posts: They are not optional. Most of the contents should end in the guides/API.
Cherry-pick entries from the changelog: a more in-depth overview of the changes.
reproduce with a JSBin or Twiddle: incredibly efficient because Ember is big and Ember apps are ambitious, therefore big(gish).
read the RFCs. You can’t possibly read every PR in ember.js and ember-cli repos, but RFCs are a great way to foresee deprecations and new features.
tl;dr; Spreading the docs between the blog, the changelog, the API, and the guides, plus the forever growing list of outdated resources is the source of all the documentation blur, I think.
. It is so bad that I have taken to ignoring any tutorials/posts dated before April 2015. The biggest problem I have is that the examples all cover the simple ToDo app (or equivalent), with the exception of many “auth” apps, all of which seem to hide the basics somewhere. I have not been able to find how to implement the less common, but still needed for anything beyond a toy, ember constructs. I need easily findable ways to structure the interface to (particularly) and from the back end. They may be documented somewhere in the adapter/serializer docs, but I can’t find them. The guides and api portion of 
) .