Conversation
|
I believe RFC's should outline what features (if any) they supercede, the strategy and timeline by which the old functionality is transitioned from and should thoroughly consider and explore the impact of the potential transition. I do not believe RFC's for individual deprecations outside of the feature/work that provided the supercede functionality are of much value, as the context as to why the change occurred should already be embodied in the originating RFC. In-fact this would appear as bandaid on the symptom, rather then the problem. If the originating RFC does not embody the resulting deprecation(s), the originating RFC did not correctly convey its impact on the system, and could not have been properly evaluated. This will also help close the loop, on "why" a deprecation or change in API occurred. The resulting deprecation guide, or blog post should be able to link back to the originating RFC which could contain all relevant context and discussion. |
|
@stefanpenner It is certainly true that the Road To Ember 2.0 failed to give us a good feeling for the pain we are experiencing now. In fact it promised a lot of "stability". I don't think we truly understand the scope of the effect of a deprecation on our apps until we see the proposed text for the deprecation guide. If an originating RFC contains the text of the deprecation warning and the deprecation guide(s) for all the warnings it proposes, I would consider the originating RFC acceptable as the RFC for the deprecations. |
|
I think there is some merit to this somewhat. I raised something similar at some point mentioning that it would be good if there was some public place to point out the upcoming deprecations or 'icky' bits of the framework that need some developers to think about and are likely to change. |
Sounds like the path forward, is to ensure impact of an RFC is more accurate. If it doesn't include API transitions, that it should not result in them. Maybe just some amendments to the RFC template / guidelines to encourage this. If outliers exists and the deprecations that do not fall into ^, maybe they belong as standalone feature RFCs. As they do change the public API. please note: these thoughts are just my own, and do not represent all of core – I am merely trying to explore the problem space right now |
|
An example of an more or less trivial RFC that outlines the migration: https://github.com/emberjs/rfcs/blob/master/text/0011-improved-cp-syntax.md |
|
@stefanpenner It fails to even mention that the old syntax will be deprecated, never mind providing proposed deprecation text and a guide for transition. |
|
|
@stefanpenner I didn't even see it just reading that now and specifically looking for it. |
|
@Gaurav0 Thanks for opening this PR. It addresses a very real pain point that many of us have been feeling, and that many members of the community have been talking about. I want to be totally clear: we all feel that, in retrospect, we did not handle the messaging and cadence of the deprecations leading up to 2.0 very well. This was the very first semver-breaking release that we have done as a project, and we learned a ton doing it. While we successfully followed our policies about deprecation before removal, and ensuring that we only deprecated features with viable replacements, we did not do a good job of distinguishing between different kinds of deprecations, and too many of the deprecations landed very late all at once. These factors combined made the entire process feel overwhelming. There are a number of process changes that we have in mind for the 2.x series, based on the experience of 1.10-2.0. Some of them include LTS releases, mandatory docs for new features, mandatory better information (including transition docs) for deprecations, improving the deprecation tooling to help with understanding the urgency of a deprecation, and svelte builds, which let you remove deprecated features from your builds. @Gaurav0 I have been following your comments on #56 (the RFC about 2.x release cycle improvements that I opened in May), and found them to be fairly constructive.
I agree.
That is my goal as well. |
I think if that RFC also included at the very least the goal of the deprecation text (remember sometimes, when the solution is being implemented the deprecation may change or improve). The implementer @cibernox would have had an a really nice friction free path to implement. So added bonus. |
|
This is a good discussion to have. But I want to point out that one of your opening premises is backwards:
This is not true. Adding deprecations is a massive pain for framework developers, and we spend hundreds of hours trying to do it correctly, and in the short term it makes our lives much harder, not easier. The easy path for framework developers is to just rip out old code. But that would be harder on users, so we add deprecations instead. The deprecations make our work harder, because all the old functionality must remain undamaged, even as we try to add new things. I suspect that the real problem here is not the presence of deprecations, which are -- by definition --harmless to your application. It's just the need for improved tooling so that you can choose when and how to deal with each deprecation on your own schedule. We have already accepted an RFC that makes this whole process much nicer, and @mixonic and @rwjblue have already implemented the feature and backported it to all of Ember 1.x via an addon. It is understandable that a hard-to-control spew of deprecations made people unhappy. But the problem is not that there were many deprecations, it's that they were hard-to-control and redundant. |
|
@ef4 The premise of a deprecation, true, is that it should still work as before. However, bugs in deprecated features are given low priority when addressed at all. And when asking for help on a deprecated feature, the response is invariably "x is deprecated, use y". Yes, you do spend lots of effort to try (and fail) to maintain semver. But this is insignificant against all the time spent by all of your users updating all of their code. Most of whom will never hear of this RFC. Please do not try to compare the two just because you know about the former. |
I am sorry. |
Let's be careful not to treat the Ember project and the core team members as if this section of computer science is an old and carefully honed art and any discomfort on the part of devs is due to incompetence. Client apps are a very new concept in the grand scheme of things and the fact that Ember does as well as it does with semver while handling browser compatibility and the rapid rate of innovation is pretty admirable. An initial read of this RFC strikes me as being strong enough that it would hobble core developers / halt forward progress. I would instead push for a "documentation culture" where docs and guides are versioned and code can't be merged unless a documentation draft is written by the developer who wrote the code. If deprecations can be managed via something like this and there is clear documentation including guides for development versions then it seems like the path for userland devs is fairly clear and painless. |
|
@jerel The goal is not to "hobble core developers / halt forward progress". But we need to put the needs of users ahead of the needs of core developers. I don't think that giving the users a chance to comment need stop anything. And there is a difference in my mind between API changes and forward progress. |
|
@Gaurav0 You can comment on a deprecation at any time. What's holding you back? |
|
From my point of view as ember user, a relatively involved collaborator and also as someone who works helping other to get on their feet with the framework, I've felt the pain too in those three roles. But didn't felt that deprecations by themselves were a big problem, other than being overwhelming when displayed in hundreds in the console during the 1.13 cycle. Most of deprecations related with new features were already mentioned in the RFCs of the feature replacing the old one. Other than giving more visibility to them I don't think there is much we can do to advertise them in advance. Telling people that something is going to be deprecated before an alternative way of doing the same thing is provided would cause more harm than good, because people will want to stop using that when perhaps there is no alternative yet. One example of this is controllers. Most people knows that controllers are going away, and i've seen a lot of people asking how to not use controller when routable components are not ready yet. It makes more sense to me to land both the deprecation and the new feature together. Besides, I even if an RFC is created for every deprecation warning (which I feel it would be falling in over-bureaucracy), I don't think that would drag much more people to the subject. The main pain point to solve about how deprecations and new features land is documentation. The 1.13 cycle is a good example of how to fail on documenting the new idioms or features. For example, as of today no mention to the new lifecycle hooks exist on the docs or on the guides. If as @wycats mentioned, documentation is a mandatory task of each new feature, as it is to add tests to it, the friction that everyday ember devs that don't have time to go though every pull request and RFC will reduced greatly, apart from give a better onboarding to new users. |
|
@mmun Not knowing about it until the pull request, which is usually too late. The decision has been made. |
|
@Gaurav0 Too late for what? If you don't agree with a deprecation you can open an issue. You have until Ember 3.0 to make your case. Deprecations are the way we communicate to developers that we intend to remove something!!! And not just the ones that read the RFCs repo. |
|
@Gaurav0 Have you given your input on that topic anywhere? I agree there are problems. Specifically the issues I see are
|
I think it's clear that the quantity of deprecations was too high, and resulted in mistakes like these. I'm sorry. In 2.x, deprecations won't land if they don't already have a transition guide, and they will land first on Canary. This will give you the normal 6-12 weeks to raise an issue with a change, and once the deprecation lands, it is far from actual removal. If you object to a deprecation that has made it all the way through the Canary->Beta->Release process, there is still an opportunity to object, and we can still decide not to remove the feature. I think a lot of the frustration is based on the very real fact that we are very close to an actual breaking release, and we landed many deprecations very close to that release. A deprecation in 2.1 is far less "final" than a deprecation in 1.13.7 that was already removed in 2.0. |
|
@wycats It's more to it than that. Every day I have to try to explain to my coworkers why something was deprecated, and simply do not know, and can't even find out. I bet the reasons are good, but where is the justification documented? They feel you are changing things unnecessarily, and I am trying to defend Ember from coworkers and management that see all the wasted man hours in keeping our codebase up to date. Secondly, I was using @each in the last few weeks to try to remove observers from my codebase. If I had some inkling it was going to be deprecated, I would have looked for another solution. Apparently, "the core team has wanted to deprecated this for a long time". (runinspired on slack). |
|
I have found as noted that the sheer number of deprecations from 1.12 to 1.13 was overwhelming in our large app that we started pre-1.0. Luckily, we had the last two weeks pretty light and were able to take care of them all. I took it as a learning experience, digging into what the deprecation meant and why I should change what was deprecated. It could have been easier with some sort of guide (which it seems like will be a requirement). This is one big bump, and I am okay with it. It doesn't happen every minor release, and let's hope it doesn't always happen in the last minor of a major release. |
|
note: if some of the following material is missing from other important sources (docs guides etc, that is in error and I invite the reader to report or submit the fix accordingly) For those reading along, I would like to take this opportunity to be sure no confusion exists with the
|
|
For the apps I'm working on, I'm giving us around 4 months to upgrade to 1.13. We have a series of deprecations and refactorings that need to be done to get 2.0 ready. These changes will make it easier for new developers to get onboarded, but it's tedious and is time consuming. The major change is moving from CoffeeScript to ES6. This unto itself is a major undertaking. A portion of the chores that I have for getting 2.0 ready is the following:
And so on. I'm only halfway done with this list, which has been a month's worth of work so far. It's tough work getting everything up to date with the large amount of changes and restructuring that's being done in Ember. There's other tasks that aren't mentioned here, like using This might seem like a lot of belly aching, but I'm actually very happy about most of the changes being made. Ember is becoming simpler and more powerful, which is great. The path to 2.0 has been very rocky, and hard to track. http://emberjs.com/deprecations/v1.x/ is super helpful, but it's super difficult to find, since links are buried in the website. I hope this helps! |
|
Thank you @tim-evans for sharing your story. Unfortunately I have shared my own similar story in the past and it has not made much difference. I have been advised to be constructive and come up with a solution. I feel sad to get so much negative feedback again. Thanks for making me feel not quite so alone. |
|
@Gaurav0 I'm sorry you feel that the feedback is so negative. Just to give a little bit of insight into my own thinking, I have been following your feedback for many months, and have taken it extremely seriously. Your initial feedback led to some of the ideas in the release process improvements post. I took your comments on that post very seriously as well, and they led to some of the further ideas I mentioned in a previous comment. This RFC correctly points out that the cadence of deprecations was way too fast in 1.13, and that there wasn't enough opportunity for the community to provide feedback about those deprecations. All of us are very invested in making sure we avoid making a similar mistake in the future. Far from ignoring your feedback, it has been very significant in shaping our approach to the release process and deprecations in 2.x. I think I can speak for others on the core team and other major contributors in saying that your feedback has made a huge difference. |
|
@wycats I have to feel like my feedback has been ignored based on your inaction. I raised the red flag as loudly as I could in June and yet this 1.13.x debacle continued. How is it no one even tried to put the brakes on all the deprecations then and prevent all the removal from 2.0? How can I ever feel like I can "trust us because core team members feel the same pain you do"? Edit: I realize this is harsh and not constructive. My apologies. I feel really frustrated. |
I can understand why you feel that way. Our original plan for 2.0 was a much more aggressive pruning, but we realized after landing Glimmer in early May (later than we hoped) that we were going to have to pare back our plans significantly. When you raised the alarm in June, you were right: our original 2.0 plans were way too ambitious. We pared things back in part by abandoning a number of expected deprecations that we had talked about in the original 2.0 RFC, and by creating compatibility plugins for a number of other deprecations. In retrospect, we still did too many deprecations, and should have pared back even more. I am serious when I say mea culpa. All of us are committed to avoiding this amount of disruption in the future, and we've put our money where our mouth is: a big part of the 2.x planning has been about avoiding a repeat of 1.13. |
|
@wycats Thank you for taking the time to talk to me, despite my harsh comments. I really appreciate it. If you feel this proposal is not the right way to go about it, do you have any other ideas on how to:
|
|
@Gaurav0 No problem, and thanks for enumerating your list of concerns. It's actually pretty close to the list of the concerns we've been thinking about, so that's a good sign. One of the biggest problems with deprecations appearing first in pull requests in 1.13 is that that effectively meant that they were on a fast track for removal. If you missed the pull request, you might have missed your chance. In 2.x, even deprecations first submitted as pull requests will first land on Canary, then eventually make their way onto Beta, and only 6 weeks after that land on Release. And even then, the feature will not be removed yet (until 3.0, at the earliest). We will also treat the requirements that new deprecations have guides as mandatory. I encourage you to raise the flag if deprecations make it onto the Beta branch without documentation (which should absolutely include both transition guidance and an explanation for why the deprecation is happening). In an ideal world, mechanical changes (like the Generally speaking, we intend to maintain support for deprecated features in 2.x as long as there is still substantial usage of those features, especially if transitioning away from the feature is non-trivial. If you feel that isn't happening for a given deprecated feature, please let us know. When features are deprecated because they are inconsistent, buggy, or incompatible with other features, we do our best to maintain compatibility, but it may not be possible to continue to fix bugs in those features. A good example of this is ReduceComputed, which we eventually realized had bugs we would never be able to fix. Also, rather than improve performance as it did in 1.12, ReduceComputed is often slower when used in 1.13+. My feeling is that the issues you targeted will be addressed in various ways through our plans to improve the release process. I would like to take some time to implement those improvements, and then circle back around to see what we can do to address any issues that still remain. How does that sound? |
|
@wycats It sounds pretty good, although I hope you give more thought to issues (1) and (2). I have raised an issue in emberjs/website regarding justifications. emberjs/website#2307 |
|
@Gaurav0 Deal. |
|
I was asked by @Gaurav0 to reply to this. I am sorry for being late to the party, but I think I might have a small idea that might work. It might be a nice idea to do something like the tc39 on keeping track of deprecations. We could put this on the top of the deprecations guide for 2.X (not sure if worth it for 1.X). The table would kind of look like the following:
|
❤️ That would help a ton I think. Edit: sorry, had this tab open from last night and didn't realize it was closed. |
|
@martndemus thanks so much for this. I think it makes sense to have a new-features/deprecations dashboard for all feature flags and deprecations. I'd been already thinking about this for new features and think it makes sense to also do the same thing for deprecations. |
11 participants
Rendered