Editions

[davewasmer]

Rendered

[mike-north]

Can we take this to mean that editions will not overlap?

[davewasmer]

Yep!

[mike-north]

programming model

Would you mind unpacking this term a bit?

I'm used to thinking of "programming model" as a low-level concept tied to whatever the program is running on (i.e., all languages that run on the JVM or BEAM share a programming model, despite having very different syntaxes and APIs).

[davewasmer]

I think @tomdale likely has the most articulate version of this in his head, but I'll take a stab.

Ember's features tend to land incrementally and piecemeal. This makes for an easier upgrade path, and ensures that new functionality is backwards compatible.

But sometimes, a set of separate, individual features can work together to produce a developer experience that is greater than the sum of the parts. For example, take angle bracket components, Glimmer, module unification, and some of the other features currently in the pipeline. Taken together, they create a vastly different experience for developers building with Ember.

But because of the incremental progress made to land these features, they might land in different versions, and will almost certainly not land in a major version (i.e. 4.0). So when a minor version ships with just one of these features - do we update the docs? Do we start pushing it as best practice?

If we do, the docs & overall developer experience might feel incongruent (because the one feature was designed to make the most sense with the other features in mind, even though it's backwards compatible). If we don't, when does experience shift? If the answer is "after all the related features ship", then that's basically what an edition is designed to accomplish.

Editions gives us a chance to introduce a higher level abstraction that operates similar to the way most other JS projects use major versions: they mark paradigm shifts in how you use the framework. But because Ember reserves major versions for the strictly technical purpose of indicating the removal of deprecated APIs, we lack such a tool. Editions aim to fill that gap.

Hopefully that clarifies a bit. If not, I'll defer to @tomdale's more articulate writing skills.

[tomdale]

👍 to what @davewasmer said. When I use "programming model," I'm talking about the mental model developers should have of the framework and how different abstractions can be combined and deployed to solve a particular problem.

I think @davewasmer's description of a set of features producing "greater than the sum of the parts" is spot on. For example, the Ember 1.x programming model was driven by two-way bindings. The Ember 2.x programming model is driven more by DDAU. But I think we've done a poor job of communicating that that shift has happened, so it's not always clear to developers when they should use two-way bindings vs. mut helpers vs. passing functions, etc. Bubbling vs. closure actions is another example of where we've allowed the programming model to be muddied. And some features like query params are painful to use if you've fully embraced the DDAU model.

A big part of the goal of editions is to serve as a discrete moment where we can have a discussion as a community about what our shared best practices are, and identify gaps in APIs (like query params) and documentation.

[mike-north]

Comparing your comments here to this earlier statement

Editions are not separate releases, but rather a specific range of releases belong to an edition

I'm a little confused as to whether there's a possibility of an edition that crosses a major release boundary

-------Ember Octane-----|-----Ember Butane---
--3.14----3.15--|--4.0---4.1---4.2----4.3----

[davewasmer]

Yes, editions (as proposed) can cross major version boundaries. That's because, due to Ember's approach to handling semver, major versions do not necessarily indicate a change in "programming model" - only that deprecated functionality has been removed.

[mike-north]

One possible interpretation of what you've proposed here is that an edition represents the important changes that precede a major release. We've seen some of this in Ember's history.

• 1.10 - compiled templates emit DOM fragments instead of strings
• 1.11 - we can bind actions to DOM attributes instead of <button {{action "foo"}}>
• 1.12 - a way of defining settable computed properties without using function arity to decide get vs set
• 1.13 - Ember.View is deprecated
  ---- 🏆 EDITION COMPLETE 🏆 ----
• 2.0 - drop deprecated code, drop support for IE8

Does this align with what you're proposing here?

[davewasmer]

One possible interpretation of what you've proposed here is that an edition represents the important changes that precede a major release.

In the example you gave, yes, that would be good timing for a new edition. But only because (for argument's sake) 1.13 marked the moment when a set of features was sufficiently shipped and documented to make sense together. Not because it preceded a major release.

In practice, I could easily imagine that it's often the case that editions precede a major release, but we shouldn't view it as a requirement. If we ship a new programming model in 4.3, we shouldn't hesitate to mark a new edition just because we are far off from another major release.

[chriskrycho]

I suggest explicitly mentioning the prior art from the Rust community, in part because many of the discussions they had about the Rust Edition process will prove illuminating to people thinking about this here! That process has some major differences from what we are doing here, including around backwards compatibility, but it’s still helpful as a point of reference.

I am 100% in favor of the approach as outlined here.

[davewasmer]

@chriskrycho added 👍

[happycollision]

Regarding exploring names other than "Editions":

• "Focus": It evokes the idea of a particular set of features, rather than a particular release. This would be helpful in NOT confusing people about major semver releases. The main confusion would lie in explaining the difference between "the focus (lowercase f) of this PR is..." and "this release is part of the _______ Focus". Although I have to say that the similarities in what those two phrases are trying to accomplish are greater than their differences.
• "Range": This immediately evokes the idea of spanning several releases. Though, that is about all it does.

Seems to me that a "Focus" should have a range, and not be called a range. But I thought I'd include both.

I also thought about "Landmark" and "Focal Point", but both seemed to suggest the same sorts of things as "Version".

I do like the idea that "Focus" is not something that immediately makes people think of a particular versioned release. In that way, I think it is a term that achieves a major goal: since "Focus" or "Edition" are refer mostly to marketing, documentation, and are signal to the add-on community, the main thing that this term needs to do is NOT confuse people who are just dipping their toes into Ember and the community.

[acorncom]

So I've been mulling this over a bit and have another possible name / concept to throw out here. I like the "epoch" concept (as it gives a sense of time), but agree with your concerns @davewasmer re: it being harder on non-native English speakers (and it seems a tad pretentious to boot 😉 )

How about the term "era"?

Edition
Background sense: books, coins, worked hard on, then put out for the world to use/read/admire, but not necessarily to change

Pros

• might fit nice marketing phrases better (Ember Octane might be better described as an edition rather than an era?)
  Cons
• has a sense of fully baked, once published, no longer going to be changed/tweaked (ie a book has a new edition come out periodically sometimes in more minor form and sometimes more majorly edited)

Era
Background sense: longer time spans, not as long as an epoch, movements of people’s and nations, “the Roaring Twenties”, more often named retrospectively by historians vs upfront at the beginning 🤔

Pros

• gives a sense of time
• Allows for ongoing change within the time period

Cons

• seems more pretentious? may not be good for Ember’s image in the JS world “We hereby declare the establishment of a new era“

As I think about this, I think the question for us to wrestle with is “are we naming the new approach to using Ember itself and that alone? Or are we also naming the use of Ember and its ripple effects on the community and our thinking about things as a whole?”

An edition (at least to me) gives a sense of a release by an author/authors (in this case the Ember leadership) of a new set of ideas and concepts to the world that is now ready and available for use/consumption.

An era on the other hand gives more of a sense of a shared experience over time by a group of people or larger community/nation.

I think both concepts could be useful (you could have different editions or marketing releases of Ember come out during a given larger era that helps succinctly summarize the overarching thrust of the community together) but we should probably clarify which item we’re aiming to name here.

We seem to be entering the JS compiler era (which is what Tom and Chad have been signaling for a few years now) where relative ecosystems will be competing on how well their tools can provide a full development experience that enables increased performance and optimization.

But the new “edition” of Ember (module unification, angle-bracket syntax, @ sigil) is our first major step into that era.

Does that seem accurate? How does that help here? Are we still wanting to have shorter-term “marketing release” names where we bundle up the latest set of changes and release with a snappy phrase? Or are we after naming the larger era where we teach “that’s what we used to do but these are the new best practices in this newer paradigm”?

My impression is the later. In which case phrases like Ember Octane would seem to more closely fit a marketing release concept rather than naming the era (are we going to want to live in the Octane era for the next 2-3 years?)

[Exelord]

NAMING SUGGESTION

Ember Generations

The idea

I got this inspiration from 2 real-world cases:

Humans generations

A generation is "all of the people versions born and living at about the same time, regarded collectively". It can also be described as, "the average period, generally considered to be about thirty years discussed, during which children versions are born and grow up, become adults released, and begin to have children successors of their own".

Source

Cars generations

Whenever new cars generations came up it doesn't mean all cars within this generation have the same version. Very often they get upgrades like liftings, construction improvements etc. They can even differ from each other, on how they look like and sometimes even how they feel. But the whole generation is focused about the same idea (a bunch of features)

SOURCE

Motivation

Based on that I realized that's a perfect case for what we are trying to achieve here. To have a name scoped to some period and at the same time marking as the breakthrough.

The big + of this name is that everyone is familiar with the meaning. If you will say to someone I work on app with Ember 4th Generation, he will imagine a timeline (like with humans generations) --1----2----3----4---> and will know that it's a successor of the previous one (which we are not able to say about Ember Edition), containing a new vision, ideas, features, approaches etc...

If that's argument is not helpful, try to refer to Humans Generations one more time. Imagine the people as the versions living in a specific period of time, constantly evolving and compare this with what we are trying to name. :)

Cheers 🍻

[mehulkar]

I understand the problem space here, but I think Editions (or whatever you call them) will make things more complicated to talk about. “What version of Ember are you on?” “Oh we use Ember Octane, is that still Ember?” “How do I upgrade to Octane? Is it safe?”

I think it’ll be better to align Editions/marketing names with major version releases. I know major versions don’t technically come with new features, but IMO it’s the right time to highlight all the goodness that is now built in. Similarly, it’s fine for major version work to be targeted towards some core things and highlight that in the announcement).

It’s going to be REALLY confusing to talk about editions and major versions as different things—I’m already dreading it.

[averydev]

@mehulkar, I agree that there's a very problematic ambiguity to saying "This is an Ember Octane App" if that could be anything from Ember 4.0.0 to 5.2.3. However, I also agree that Ember deeply needs these rallying cries. HOORAY just released 4.0.1 is just not exciting, regardless of what features landed.

What if we add the following rule: Editions inherit the SemVer from the version of Ember.

For instance: Instead of saying Ember 4.1.0 you would just say:
Ember Octane: 4.1.0
and then later as versions pile up
Ember Octane: 4.1.1

When a New Edition is released, for instance beginning at 4.1.2, it would be Ember Ignite: 4.1.2.

Benefits: It's clear what actual version you're talking about it doesn't add any additional versioning semantics
Drawback: It might be confusing if the first version of Ember Octane isn't v1.

That drawback only matters right when it's released, and we would still market the same by just saying "Ember Octane just dropped!!"

[davewasmer]

I understand the problem space here, but I think Editions (or whatever you call them) will make things more complicated to talk about. “What version of Ember are you on?” “Oh we use Ember Octane, is that still Ember?” “How do I upgrade to Octane? Is it safe?”

@mehulkar I think this is definitely the risk of editions, and we need to be careful with how we manage this. Rust I think avoids some of this confusion by naming editions after years, which I think makes it a bit clearer. Rust 2018 is obviously some evolution of the same Rust language, whereas Ember Octane sounds like it could be something like Glimmer - a separate project entirely (to some extent).

The downside of naming editions after their year is, of course, what if we ship more than one edition per year?

Perhaps we should consider the year naming as an option though - it seems unlikely we'd ship two editions in a single year ...

I think it’ll be better to align Editions/marketing names with major version releases.

I'd strongly recommend against this. Ember's unique approach to semver is a strength. Tying editions to major versions means one of two things, either:

a) We stick to our current semver policy, meaning that we have to wait around for a major version to name an edition, which means waiting (sometimes months!) to rally around a new set of features. This basically defeats point of editions; or,

b) We abandon our semver policy and release new, backwards-incompatible features in major releases. This is what most other framework do: basically, overload the major version of the framework with two meanings (backwards incompatible change indicator, and marketing signal).

I don't think we want either of these outcomes, and editions aims to be the tool we use to avoid this tradeoff by allowing us to decouple the project's major version from it's marketing / documentation / community efforts.

Editions inherit the SemVer from the version of Ember

@averydev not sure I follow. Are you suggesting that editions have their own, separate version number from Ember's package version? Or that we simply be careful to always mention a specific version when mentioning an edition?

there's a very problematic ambiguity to saying "This is an Ember Octane App" if that could be anything from Ember 4.0.0 to 5.2.3.

I'm not sure I'd agree here. I think the goal of editions is to rally around a coherent programming model, making the specific MAJOR.MINOR version you're on less important to talk about.

Part of the problem today is that if you talk about an Ember "3.x" app, that's not enough information to anticipate what that app's codebase looks like. A 3.0 codebase could look drastically different than a 3.4 codebase.

Editions give a name to these different paradigms. So if you're working on an Ember "Octane" app, that's all the info you need to understand what to expect.

Let me phrase it slightly differently. Editions means that:

• Semver major releases continue in their highly specific, narrowly focused role: indicating breaking changes of any size.

• Editions give us a tool similar to what most projects use major versions for (a rallying point around a new mental model for the framework).

[averydev]

Hi there @davewasmer, sorry for the confusion, Editions certainly should not have their own version numbers.

My only point is that an edition name like "Ember Octane" sounds like a single point in time, rather than a range, whereas Rust 2018 clearly represents a range of releases.

My suggestion would just be to recommending appending the version of Ember to the Edition, for instance if Ember Octane were to be released today, since the current version of Ember is 3.4.0, just say Ember Octane: 3.4.0. When the next minor release comes out, you would just say Ember Octane: 3.4.1., then Ember Octane 3.4.2 etc. Whenever the subsequent Edition is released, hypothetically lets say in conjunction with Ember 4.4.0, with the make believe Edition name of Ember Ignite, it would be referred to as Ember Ignite: 4.4.0, then Ember Ignite: 4.4.1 etc.

[Kerrick]

My suggestion would just be to recommending appending the version of Ember to the Edition

• @averydev

So you’re suggesting that Ember 3.4.1 === Ember Octane 3.4.1? Do you just avoid ever saying Ember Octane without including the Ember SemVer number then?

If so, I don’t think that’s necessary. Just like context currently says whether you say Ember 3.X or Ember 3.4.1, context can say whether you say Ember Octane or Ember 3.4.1.

———

Or are you saying that you would never say Ember 3.4.1 without inserting the edition, so you’d say either Ember Octane or say Ember Octane 3.4.1?

If so, I think that’s a good way to make sure the edition name gets included in plenty of official communication and becomes a normal part of the Embereño lexicon.

[Kerrick]

I really like this idea. I think it's incredibly easy to sell to people, too.

• We deprecate features instead of removing features right away. That means major versions last a LONG time.
• Because of the combination of new features + deprecations, an Ember X.0 app looks a LOT different from an Ember X.Y app (where Y is the last minor release of the X series).
• Because of Ember's policy that an X.Y app without deprecations upgrades to (X+1).0 "for free", an X.Y app looks a LOT like an Ember (X+1).0 app.
• Thus, the general architecture, best practices, and commonly-used features of an Ember app don't align well with SemVer major releases.

This is unlike React/Angular. Where a React 15 book is pretty up-to-date with best practices for the entire React 15.N cycle, an Ember 2 book written for Ember 2.0 feels out of date for Ember 2.18.

[mike-north]

As a training-focused developer, I really like this idea, and it would mitigate a lot of my "timing" risk. Currently, I either have to guess or coordinate very closely w/ ember core in order to determine the best time to come out with a new version of content.

If we had a more concrete sense of

• what an edition will contain
• what is the definition of done for the edition (i.e., docs will be updated, ember-twiddle support will be ensured, etc...)
• a quest issue or GitHub milestone showing a burndown of issues

I'd have a good sense of the best time to release a new book, tutorial, video course, etc... and the major changes to focus on.

[tomdale]

I had a few conversations with @davewasmer and @wycats about this RFC and wanted to write down some of the high-level points we discussed.

First, I want to reiterate that, from my perspective, editions are very much about the programming model. For example, Ember and the community shifted from a two-way bindings (2WB) approach to adopting Data Down, Actions Up (DDAU), but we never had a moment where we clearly said "From now on, it's time to start thinking in terms of DDAU and you should generally avoid 2WB."

The result of this has been confusion about the "right way" to do things, and there was never an obvious time to go through the guides and rip out all of the examples that used the older programming model. Instead, we kind of just switched to designing new APIs based on DDAU, but without ever doing a top-down audit to make it clear that this was the way forward and to ensure that documentation, example code and framework APIs were aligned to support that shift.

This is exactly the problem @mike-north is describing above. We have two things in tension: we periodically need to make fundamental changes to the programming model and thus our APIs, but our working style is rooted in incrementalism and backwards compatibility.

One thing @wycats and I have been talking about a lot recently is the idea of "incoherence" in the framework. As we tried to unpack the shipping and communication failures in the past, we came to believe that our own personal discomfort with incoherence was at the root of it.

Specifically, big enough programming model changes can touch almost every part of the framework. Getting those new APIs right while not breaking the ecosystem is an incredibly challenging task. In the beginning, we would try to design and implement those big changes all at once. But because the scope of the work was so large (and big design upfront has well-documented failure modes in software), projects would drag on for years and people would perceive (rightly) a lack of momentum in the framework. In other words, we couldn't deliver any value until the entire thing was done.

At some point, we realized this approach wasn't working. We moved away from mega-RFCs and moved towards smaller, more incremental, more tightly-scoped RFCs. My perception is that this has been an unambiguous improvement, allowing us to regain our momentum, deliver incremental value more quickly, and identify issues early rather than at the end of an arduous, months-long design phase.

However, that incremental approach does mean that the framework is frequently in a state of incoherence. New API may not mesh well with old API. New features may land but with important limitations or caveats. Things may be in the first draft, "Minimum Viable Product" stage rather than where we ultimately intend them to be.

Speaking for myself, I think I was subconsciously embarrassed by this incoherence. It was difficult for me to get excited and tell the world about new features, because I was comparing the imperfect-but-usable reality with the perfect future state I envisioned in my head.

But of course, that future never arrives—the web changes and there is always new, exciting stuff in the pipeline. The result was that we dragged our feet communicating, waiting for an elusive "perfect" moment when we'd made all the changes we wanted to make.

Going forward, it's important that we be comfortable with incoherence. There are going to be times when we are building towards a change, but it's important that we have regular checkpoints to make sure we touch back down to reality.

So, bringing it back to editions: I think this is the major value for me. Editions are a time for us to reflect on the changes we've made and reconcile the whole into the most coherent state we can. There may be imperfections or APIs we don't think are ideal, but documenting those gotchas is a far healthier way to deal with an imperfect reality than going radio silent.

This brings me to my next point. There's been some discussion about whether an edition marks the start or the end of something. I think the answer is both, but it depends on whether you're looking at it from the perspective of an Ember contributor or an Ember user.

From the user perspective, an edition marks the start of a new way to think about Ember. Whenever you pick up Ember, your experience will be driven by whatever the most recent edition is. For example, if the Ember Butane edition begins at Ember version 7.3.0, you'd still be using the Butane programming model if you picked up Ember at version 7.13.1 (assuming no new edition in between).

However, from the contributor perspective, an edition marks the end of a focused push towards a larger change. We will have been building towards that change for many months, incrementally landing new features that get us ever closer. An edition is about us saying enough new features have landed that people can start using them productively—time to end the push, regroup, and think about the next one.

Putting it in terms of incoherence, an edition marks the low point of incoherence, because we're saying that enough of a set of synergistic features has landed that you can now be productive in the new model. The subsequent stable release after an edition is declared can only increase incoherence, because we'll start incrementally landing whatever features are part of the next big push.

That said, I'm hoping editions can help us ensure that this temporary incoherence doesn't negatively affect the day-to-day Ember developer. Because the guides and examples will be oriented around the "current" edition, they will not be updated to use new APIs until the next edition is declared. Folks like @mike-north or the Ember Map crew working on training content will have a very clear signal about what's "ready," and what should be reserved only for the more adventurous.

As always, the devil is in the details. How we organize the guides is pretty clear to me, but I'm still not sure how editions would change how we think about API docs. There's a risk that the framework might feel buggier, because we'll have fewer people trying out and giving feedback on new features as we land them. (We already have this problem today, for example, with not enough people trying out Ember CLI betas and only discovering showstopper bugs once we do a stable release.)

Sorry for the novel, but I thought it might be useful to get some of these deeper thoughts out that are motivating my personal excitement about editions. I hope the framing of the problem about managing the ebb and flow of incoherence, and how we communicate that to end users, helps others as much as it has helped me.

[wycats]

I (unsurprisingly) agree with @tomdale's comments strongly.

One point I'd like to reiterate: when building new features, you have to choose between landing parts of the feature as they stabilize or landing the entire suite of features once it is fully complete, fully documented, and ready to be used by all users.

Historically, we've erred far too much in the direction of waiting for the entire suite of features to be ready, which was often articulated as:

• "But how will people know how to use when is still around. Shouldn't we also finish the job of eliminating ?" (example: Feature X: Routable Components; Feature Y: Controllers)
• "But if we only ship part of without , it will be very confusing!" (example: Feature X: Angle Bracket Components, Subpart Y: this.args)

These sentiments are common, and like @tomdale said, are sentiments that we ourselves have felt strongly in the past, in part because it feels embarrassing to ship work that people find confusing.

But observe that none of these sentiments are particularly connected to stability. For example, we were able to stabilize @name syntax without this.args. It wasn't difficult to stabilize it technically from a compatibility perspective. It does, however, raise a question: if someone starts migrating to @name syntax, how should they think about their JS classes? Should we maybe wait until we have this.args ready to go before exposing Ember developers to a part of the new programming model?

What @tomdale and I realized was that this consideration was significantly slowing down work, because it imposed a "coherence" constraint on the technical project of landing work incrementally. Additionally, once some functionality is stable, it is useful to addons and power users, who can then provide feedback on the feature that can feed into the rest of the development.

But moving to an "eventually coherent" model, in addition to all of the benefits it provides for momentum and velocity, creates a new problem: how should developers know which aspects of the framework represent the parts that have crossed the "coherent" threshold. And the answer we landed on was frequent "editions", which allow us to build community momentum towards an end state for the suite of features that landed since the last edition, and gives us an opportunity to focus the community on wrapping up loose ends to make the programming model in the new edition as complete and ergonomic as possible.

---

One last thing: we used the word "incoherent" internally a lot, and I don't mind that @tomdale used it in this post. But it's important to distinguish between two kinds of incoherence.

"Programming model incoherence", which we're allowing here, means that a user trying to use new features might find that there are "cracks" in the design that makes it hard to use or possibly forces unpleasant choices between the "old" and "new" programming models that are only identified late in the game. The process of coherence is the process of sanding down those rough edges, either by finishing the suite of new features (so there is feature parity with the old way) or by increasingly interoperability (so the old way is available as an escape valve).

"Semantic incoherence", which is still very unacceptable, would mean landing features that are broken in their own terms. For example, we wouldn't stabilize a version of the named blocks feature that broke lexical scope, even if you had to opt in to the feature.

What we're trying to do is allow features to land that are complete in their own terms, and allow the stabilization of idioms and patterns to happen at edition boundaries.

[ryanto]

Y'all are fantastic writers and this was a fun RFC to read. I got really excited thinking about how editions would play a role in Ember's development!

It sounds like editions will give us a point to align all of the various pieces that make up Ember. This means that an edition would cause the programming model, code, api docs, guides, addons, and on-boarding to all have a shared narrative, is that correct?

Another question I have is that it seems like there will be a period where an "eventually coherent" feature is released in stable, but we are between editions. How are those features documented or talked about? I’d imagine some of those features will help solve real world problems, so teams will want to start taking advantage of them. Is there a way to talk about these features in a way that’s helpful to users looking to adopt them?

[wycats]

Another question I have is that it seems like there will be a period where an "eventually coherent" feature is released in stable, but we are between editions. How are those features documented or talked about? I’d imagine some of those features will help solve real world problems, so teams will want to start taking advantage of them. Is there a way to talk about these features in a way that’s helpful to users looking to adopt them?

My current sentiment is that they would be added:

• in a "next edition" section in the guides (name TBD), which would include information and links to the active tracking issue. This would leave the main guides for the mainline, coherent programming model.
• behind a "next edition" checkbox in the API docs

We'd need to find a name that communicates both that the feature has landed but might still not be amazing to rush to adopt. I imagine that addons will be able to understand the nuance, and that it might not even be the worst thing in the world if app developers who aren't paying close attention perceive these features to be "unstable".

But again, naming TBD.

[ryanto]

Nice. I like where you're going, thanks for taking the time to explain. Next edition guides seem like a thoughtful way to communicate the current thinking and understanding around these features.

I'd also love to hear about the edition release process. I'd imagine there are multiple ways to know that a feature's incoherence is low or the programming model has changed. When do you know it's time for a new edition? Is there a maximum amount of time that can pass without an edition?

Also I realize I’m asking questions that are diving into the implementation details of the edition process, which no one can perfectly predict. Is this RFC for “hey we’re doing editions, we’ll figure out the details in later RFCs”? Or is this the time to ask questions that will define everyone's understanding of the edition process?

[mike-north]

One consequence of deferring documentation updates until the completion of an edition is that the public API of the framework may be unclear.

Having spent some significant time writing type information for Ember and validating completness of API docs -- we need to work on building more clarity in this area, not less.

Some portion of risk-tolerant developers will always be interested in adopting new features early -- there's a non-trivial slice of our community that's already using ES6 classes and Module Unification in production (despite these features still being in development).

One idea would be to keep API docs in sync with stable releases, but defer updating the guides until completion of an edition.

[davewasmer]

One idea would be to keep API docs in sync with stable releases, but defer updating the guides until completion of an edition.

I think this is the best tradeoff.

The narrative nature of the guides lends itself well to what we're aiming for with editions: a coherent programming model. It's easier to write the guides from a perspective of a given edition. And I definitely think we should continue documenting new features as they land in the API docs as well - editions are far too long to wait for them. And I think this minimizes incoherence: I doubt many people casually peruse the API docs, so it's unlikely to introduce confusion for folks who are trying to learn the current edition's model.

Perhaps the guides can be tweaked to show an edition dropdown rather than the current version dropdown?

I'd also love to hear about the edition release process. I'd imagine there are multiple ways to know that a feature's incoherence is low or the programming model has changed. When do you know it's time for a new edition? Is there a maximum amount of time that can pass without an edition?

@ryanto I think this will be a very subjective and difficult to define moment - a "know it when you see it" type of thing. I hesitate to add any additional structure or process around how we ship editions as well. It's better to aim for the minimal process first, and add more as we hit pain points, rather than try to anticipate and plan for eventualities.

In the same way that we don't have a concrete process for when major versions happen, I think editions are large and coarse enough that the core team and community at large should be able to identify good opportunities relatively easily.

[Kerrick]

I think this will be a very subjective and difficult to define moment - a "know it when you see it" type of thing.

So will "I see it" be brought up in...

• Core team meetings?
• Another RFC some day?
• A PR on the guides repo?
• A discord channel?
• A Discuss thread?

...and can it be brought up by...

• The steering committee?
• Core team members?
• The ember learning team?
• Any community member?

[locks]

I see it working similar with major releases. At the moment we don't have a specific cadence, so it's mostly an executive decision. Since we have implemented the Roadmap process this year, a suggestion would be that it would be part of that roadmap whenever a new edition wants to be proposed.

[btecu]

Isn't everyone else using major version for the same purpose as this?
Sure, ember has that policy of no new features and only code removal with major versions. Perhaps it should be re-considered if it requires inventing editions.

Also, releasing new blueprints and turning flags on by default that could break code would be a breaking change, hence requiring a major version anyway, correct?

[mike-north]

Isn't everyone else using major version for the same purpose as this?

For a SemVer projects, major version only describes a backward incompatible change (source)

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented.

Note that this statement has no mention of features or new capabilities being available. The ember project goes to extra lengths to ensure that new capabilities are available without making these breaking changes.

[davewasmer]

Isn't everyone else using major version for the same purpose as this?

@btecu I think this is a fair statement - even if semver doesn't strictly require it, it seems like most other JS frameworks take this approach, and it's a valid one.

It's also fair to suggest that we reconsider our approach - it is relatively unique, and this RFC alone is evidence of the problems it introduces. Personally, I'm in favor of Ember's current approach for a variety of reasons, but the choice here is a tradeoff. I don't think either approach is strictly better along every dimension.

That said, I'd suggest that a proposal to move away from Ember's semver strategy belongs in a separate RFC, since that is a big change to how things currently work, and would deserve it's own discussion.

[rwjblue]

Cross posting from #364.

@Gaurav0 said (#364 (comment)):

I'd like to renew my previous question about upgrading apps. If we turn off jQuery in the blueprint how will we not do this for apps upgrading via ember-cli-update?

My response was (#364 (comment)):

@Gaurav0 - Great question, sorry I missed it. I think we need to discuss the concrete specifics over in the Editions RFC, but the rough shape of things is probably something like (from this conversation in discord):

• have ember-cli infer the "new app blueprint" from the projects .ember-cli file. This would be used for ember-cli-update / ember init purposes
• create the new octane blueprint, making it the default for new apps (when the edition is "shipped")
• update ember-cli-update to check the projects .ember-cli file to know what "kind" of project it is, and update accordingly
• create a command the "migrate" to the edition (e.g. to go from the current default blueprint to the new one), separate from "simply" upgrading

After this is done, all ember new foo will get the octane edition blueprint, existing users would get their current blueprint updates, users of existing apps can easily migrate to the edition and know that they have done it correctly.

I'll cross-post this in the editions RFC so we can chat about it over there...

I think that the plan above makes sense, and would nicely answer some of the specific implementation details of how the editions work. What do you think @davewasmer?

[Gaurav0]

In practice, I could easily imagine that it's often the case that editions precede a major release, but we shouldn't view it as a requirement. If we ship a new programming model in 4.3, we shouldn't hesitate to mark a new edition just because we are far off from another major release.

I hope we don't get (back) into the habit of releasing or deprecating features shortly before a major release. That was what made the 1.0 -> 2.0 transition so difficult, and the 2.0 -> 3.0 transition less so.

[Gaurav0]

update ember-cli-update to check the projects .ember-cli file to know what "kind" of project it is, and update accordingly

So the lack of an "edition" marker in .ember-cli would indicate not to update to Octane? How long would the "non-octane" blueprint be maintained?

[rwjblue]

How long would the "non-octane" blueprint be maintained?

Unclear, likely for at least an LTS cycle but possible for the full major cycle. Really looking for @davewasmer / @tomdale’s thoughts here too.

[luxzeitlos]

I love how tomdale explained how an edition is both the "start or the end of something"! And I think this is a good argument against a name that spans a time, because then the question is what time should it span? Is now the "Octane era" because we build it or will it be the "Octane era" after we've released it because then it's used?

However a new Idea for a name: Vision.

It can be used in the fist phase when the ember developers have a vision how ember should be. And later it is the Vision how users should think about ember. And we can say "ember finished the octane vision". While Vision is not perfect I think it could be a good idea to think about other names that focus on the mind, thinking and imagination.

[chriskrycho]

Octane shipped; we have done an edition! Presumably this should move into FCP now? 😂

[rwjblue]

Yes, I agree. We need to move this forward...

[NullVoxPopuli]

What's the status of this RFC?

[knownasilya]

Was just about to say the same 😄 It needs to be updated (with any learnings from the last edition) and merged. Most likely @davewasmer won't be updating it since he's not really doing Ember atm, so someone will have to take over.

[wagenet]

I'm going to try to get the team to actually accept this!