bevy_color migration plan

[viridia]

This ticket outlines a plan for integrating bevy_color into the rest of Bevy. The plan consists of several phases.

Phase 1

In Phase 1, the public-facing Bevy APIs will not be changed, but the bevy_color crate will be integrated in ways that do not impact end users. During this phase, the following tasks will be performed:

• Refine and enhance the bevy_color crate with additional features, such as fluent builder methods.
• Do a mass renaming of the existing Color type to LegacyColor, and then provide a type alias Color = LegacyColor. The purpose of this change is to allow measurement of the migration progress by searching for the symbol LegacyColor. Because of the type alias, no end-user code will be broken. This step should be performed by an SME so that it can be done atomically, minimizing merge conflicts with any in-flight PRs that might be impacted.
• Replace internal uses of LegacyColor that are not exposed to end users, especially constant color values (I counted 601 color constants in the current code base).
• Color conversion functions in bevy_render will be moved to bevy_color. What we want to end up with is a one-way dependency such that render depends on color, and not the other way around.
• We may also want to move the From implementations for LegacyColor into the same module as LegacyColor.

Phase 2

In Phase 2, we will modify Bevy APIs, but only the ones that can be modified in a backwards-compatible way. For example, the Gizmo APIs which accept a LegacyColor argument can be changed to accept impl Into<LinearRgba>, allowing either the old or new color types to be passed in without needing to call .into().

Also during this phase, we'll add new APIs for bundle types such as Fog or BackgroundColor which currently accept a LegacyColor as a property - the new APIs will have constructors that take an impl Into<LinearRgba>. This means that users who want to use the new color types can do so in a forward-compatible way.

Phase 3

In Phase 3, the remaining APIs - the ones that cannot be made backwards compatible - will be migrated. This includes things like bundle properties. In most cases, low-level color attributes will use the LinearRgba type.

Users will need to update their code, at minimum adding a call to .into() when passing a legacy color into an API that accepts the new color types.

Timing

I'm assuming that these three phases will be spread out over several Bevy release cycles. The reason for this is that we'll want to give users plenty of warning that this breaking change is coming. However, this decision - whether to try and fit all of the migration into a single Bevy release cycle or not - is above my pay grade.

[alice-i-cecile]

I like phase one a lot. The enhancements and iterative migration seems great.

I personally think we should skip the intermediate APIs for bundle types: they're messy and inconsistent and won't make the migration any easier. I would like to ship LegacyColor in one release though, with conversions into the new color types. This will give users time to complain about missing APIs.

[bushrat011899]

I think it would be beneficial to end-users to have at least 1 Bevy release where the LegacyColor is available but depreciated. If we're going as fast as possible:

1. Complete Phase 1 (bevy_color available but "unused")
2. Complete Phase 2 (bevy_color used internally)
3. Mark LegacyColor as deprecated
4. Release 0.14
5. Complete Phase 3 (bevy_color fully adopted)
6. Remove LegacyColor
7. Release 0.15

This will make it clear to users that a new color API is coming, and will be a call to action for feature suggestions/contributions which will refine bevy_color prior to it being "the only choice".

[viridia]

@bushrat011899 The only issue I have with your proposal is that it will be problematic to mark LegacyColor as deprecated while there are APIs still using it. Other than that, it seems fine.

[viridia]

Also note that LegacyColor will continue to work with the new APIs after migration, but will require an explicit .into(). This might be useful for large projects that use LegacyColor extensively at the app level, and for which changing all of their app code might be a burden. So one option is to keep around LegacyColor for one more release cycle, even though no APIs are actually using it.

[cart]

I strongly prefer a full hard switch PR where we can tweak / polish / evaluate the new approach in full. "Half ports" risk optimizing for the wrong things because we aren't using the new types in contexts that might inform their design.

Likewise, I think a "middle ground / support both" release would just be confusing and introduce more churn than ripping off the bandaid right away. It risks churning our users more because by not fully using a given API internally, we may learn we need to break it again when a new scenario turns up. In the migration scenario, we're renaming Color to LegacyColor, so we're already breaking peoples' code. I don't think the color-representation change is complicated enough to be significantly more work than the rename operation.

I think we should:

1. Merge bevy_color as is (without porting)
2. Create a new PR that fully ports Bevy to bevy_color, using the new Color enum in place of the current Color enum, and making uncontroversial ports (such as using LinearSrgba in the Render App). Merge the PR (and export bevy_color as bevy::color) only when we are confident that bevy_color is ready / an improvement over the status quo.
3. Create other PRs for specific, more controversial changes (such as replacing StandardMaterial::color with LinearSrgb or Sprite::color with Srgba)

[viridia]

@cart Renaming Color to LegacyColor isn't going to break users code by itself, because we are also at the same time going to add a type alias which defines Color = LegacyColor. You might ask then, what's the point? The answer is that it gives us a way to track which parts of the code base have been migrated. If we have two different types named Color it becomes very hard to search for one and not the other. Renaming solves that problem.

I also think that you may be underestimating the degree of user unhappiness generated by introducing a breaking change like this, with no prior warning. I know that there were some angry comments on Reddit about some previous change to Bevy (don't remember the details). Also, I was one of the people involved with the Python 2.x -> 3.0 language evolution, which was far more painful than anyone had predicted - what we thought would take a year ended up taking ten years (it's a long story).

However, I don't really want to get into a long debate about this so that's all I have to say for the moment.

This is a big migration: there are 852 uses of Color in the Bevy code base, not counting the implementation of Color itself or documentation files. That's not going to all happen overnight.

It would be helpful, I think, to have a survey of all the uses of Color in the current bevy code base, grouped into a dozen or so categories - I've identified a few already: bundle properties and gizmo methods, both of which make for a fairly large chunk. For each of those groups, we can then propose a consistent rule for incorporating color arguments.

[cart]

Renaming Color to LegacyColor isn't going to break users code by itself, because we are also at the same time going to add a type alias which defines Color = LegacyColor

Oops I glossed over that / didn't fully process the implications of the type alias (allowing Color to continue to resolve to the old type).

I also think that you may be underestimating the degree of user unhappiness generated by introducing a breaking change like this, with no prior warning.

This may be true, but note that I am expecting users to be unhappy with this breakage. From my perspective deprecation only serves to confuse and prolong the situation more:

• I feel strongly about a full internal port before releasing the new color types (and I suspect others will feel similarly, but this is still open to discussion). If we do that, I expect a high percentage of cases to look like sprite.color = Color::rgb(1.0, 1.0, 1.0);, where Color is LegacyColor and sprite.color is bevy::color::Color. These cases will not have a soft landing, even if LegacyColor implements Into<NewColor>. Callers will need to manually add into() calls, or move to the new type.
• Color is currently in the prelude, so if the goal is to not break people (with a full rename to LegacyColor), we can't add the new Color to the prelude too, meaning people will get warnings to port bevy::prelude::Color (likely imported via bevy::prelude::*) to bevy::color::Color. People resolving the warning will end up with a bunch of manually typed soon-to-be-unnecessary imports in their codebase (manually typed because Rust Analyzer will not help with if you already have Color in scope via a full prelude import).

That being said, I'm less opposed to the "deprecation" part of the proposal than I am to the "partial port across releases" part of the proposal. I'd still be reasonably happy with the approach: "full port, with a soft landing by keeping the old Color type around for a release". I just expect the "support both / soft landing" approach to introduce additional weirdness and comparable levels of discomfort (and likely greater amounts of discomfort, when the porting process is considered as a whole).

Also, I was one of the people involved with the Python 2.x -> 3.0 language evolution, which was far more painful than anyone had predicted - what we thought would take a year ended up taking ten years (it's a long story).

Oooh interesting. I'm semi-familiar with that topic. I didn't know you were involved. Very cool!

It would be helpful, I think, to have a survey of all the uses of Color in the current bevy code base, grouped into a dozen or so categories.

Agreed!

For each of those groups, we can then propose a consistent rule for incorporating color arguments

Seems reasonable to me! If we can identify every case ahead of time (and develop a "port strategy" that we agree is a net-win ahead of time), I'm more willing to break this up across PRs (especially if we commit to doing the full port before the next release). The concerns I would like mitigated:

1. Committing to an API before we know its fitness for our codebase. Aka merging a partial port of the codebase, only to discover a later case isn't well suited to the API we have chosen.
2. Having a partial port on main for a long period of time, complicating the lives of consumers of main
3. Hitting the release deadline while still in a "partially ported" situation.

[viridia]

@cart One thing to bear in mind is that there are a number of people who are gung-ho to start migrating Bevy right now. You can expect PRs to start showing up within the next couple days. This is a good thing, but we may want to exercise some restraint - once those PRs get merged we are pretty much committed unless we plan to revert them later.

For example, one strategy might be to release bevy_colors in 0.13.1, with no changes to Bevy APIs - a "preview" of what's coming, which will then give users several months to get used to the idea that the Bevy APIs will change in 0.14.

BTW, I want to push back on the idea of renaming Srgba to Color. I want to quote Albert Einstein here: "Things should be as simple as possible, but no simpler." I'm all for making things simple for new users, but we should avoid hiding important details that they need to know. Color spaces are something that eventually users are going to need some awareness of - maybe not the more esoteric spaces like Oklab, but an understanding of standard vs. linear rgba is pretty fundamental in graphics work. I would rather take the approach of writing really good docs (which I can do) that teaches them what they need to know, rather than sweeping this complexity under the rug. EIBTI.

[cart]

BTW, I want to push back on the idea of renaming Srgba to Color. I want to quote Albert Einstein here: "Things should be as simple as possible, but no simpler." I'm all for making things simple for new users, but we should avoid hiding important details that they need to know. Color spaces are something that eventually users are going to need some awareness of - maybe not the more esoteric spaces like Oklab, but an understanding of standard vs. linear rgba is pretty fundamental in graphics work. I would rather take the approach of writing really good docs (which I can do) that teaches them what they need to know, rather than sweeping this complexity under the rug. EIBTI.

Good points. If we go that route, it would likely need to be Srgba->Color and LinearSrgba->LinearColor to create the appropriate parity (especially if we're using LinearSrgba/LinearColor for StandardMaterial). Terminology-wise I personally don't see a fundamental problem with designating Srgba "Color", given that the rest of the industry does that, and people will gravitate toward that name for obvious reasons. But I'm largely undecided atm. I currently feel more strongly about the reverse: that Color likely wants a less friendly name if we're going to encourage the use of Srgba / LinearSrgba naming.