search

projectfluent / fluent.js

JavaScript implementation of Project Fluent
https://projectfluent.org/
Apache License 2.0
937 stars 77 forks source link

Status of @fluent/dom #470

Open stasm opened 4 years ago

stasm commented 4 years ago

I'd like to establish what the current state of @fluent/dom is, and decide what the maintenance story for it should be.

@fluent/dom was our first implementation of platform-specific bindings. It was written first with Firefox OS in mind, and then modified to support the effort of migrating Firefox to Fluent. Today, most of the Fluent code in Firefox has been rewritten to C++ or Rust; the only part running still in JS is Localization.jsm based on @fluent/dom's Localization.js, but also heavily modified and tailored to Gecko's needs. There are plans to port it to C++ or Rust, too.

I think it's fair to say that today, the vanilla @fluent/dom isn't used in Gecko at all. The code works, but isn't actively maintained, and it doesn't have the Firefox driving its development any more. It's used in a few web projects, however. A GitHub search for package.json dependencies yielded at least the following projects:

In total, @fluent/dom currently has 241 weekly downloads, and @fluent/web has 1. I also checked the old names, fluent-dom and fluent-web respectively, which have 1 weekly download each. It's worth remembering that weekly downloads don't paint the whole picture, so I'm taking these numbers with a grain of salt.

In any case, I think we are at a risk of @fluent/dom becoming a maintenance burden. It was tailored for a use-case it doesn't support any more (Gecko), and hasn't been looked at, reviewed, or updated in a while. Fortunately, it works with the most up-to-date FluentBundle API, and it thus supports Fluent Syntax 1.0.

The main risk that I see related to the syntax is related to markup overlays. Both IOT Gateway and Talk make some use of overlays (<a> with names, and <br>). I'd like to work on the next iteration of markup overlays in the second part of the year, and depending on the amount of changes and then the extent of support in Pontoon and compare-locales, we might want to make sure @fluent/dom uses the updated overlay logic.

stasm commented 4 years ago

CC @Pike, @zbraniecki.

stasm commented 4 years ago

Here's my proposal:

This allows us to keep the lights on for projects currently relying on @fluent/dom and devise a path forward for maintaining @fluent/dom as part of the @fluent family with the limited resources that we have.

zbraniecki commented 4 years ago

I like fluent/dom and fluent/web as a gateway to Fluent. They allow someone to plug a single script and see Fluent localizing an HTML document.

I'd like to preserve that value, while recognizing that the Fluent team doesn't consider vanilla Web a priority target for Fluent.

From that perspective, I suggest the following alternations to your plan:

So, I think that your vision for the status by the end of the year matches mine. I think I differ in how i believe we should communicate our support for Fluent in JS before the end of the year :) I'd prefer to use 0.x to indicate lack of stability, you suggest maintenance mode, discourage new uses and sunset.

stasm commented 4 years ago

I agree that @fluent/web can serve as an onboarding experience. What I'm afraid of is that with the resources we have today, I can't ensure that it's a good experience. I would also like to limit @fluent/dom deployments out in the wild for now and wait a few months until we have time to work on Localization and overlays. We have scheduled time in Q3 and Q4 for this, so it's not that far out in the future.

I also admit that I've done a poor job of communicating the stability of @fluent packages in the past. We're at 0.x with all our packages. Some of them have been used in production for a long time. My goal for this quarter is to release 1.0 versions of most @fluent packages, and then work my way up to versions 2, 3, etc, as I work on new features.

What I'd like to say is: here's a plan, I'm working on making this right, please wait a bit before using @fluent/dom so that you're not stuck on a version that will be obsolete in a few months. We'll already have a problem with migrating Firefox and @fluent/react to new overlays, and I'd like to avoid adding yet another dimension to it.

zbraniecki commented 4 years ago

I agree that @fluent/web can serve as an onboarding experience. What I'm afraid of is that with the resources we have today, I can't ensure that it's a good experience.

I don't think I understand that concern. @fluent/web lives in its own repo, works today, can be build against the latest @fluent/bundle and serves its purpose. At the same time, since January 2018, your only commit to @fluent/web was an addition to the changelog.

Can you explain what resource drain do you have on mind? What experience degradation are you worried about?

I'm working on making this right, please wait a bit before using @fluent/dom so that you're not stuck on a version that will be obsolete in a few months.

If your main concern is that people will be stuck with a version that is obsolete, then I believe 0.x is the correct way to communicate it. It's prior to 1.0 therefore it is not stable and if you want to use in production, you may have to invest in updates.

We'll already have a problem with migrating Firefox and @fluent/react to new overlays, and I'd like to avoid adding yet another dimension to it.

My understanding is that there's no additional dimension. Overlays work the same way in Firefox and @fluent/dom, so anything we'll have to do to update the former, will work on the latter (e.g. - scripts). The package is pretty well aligned with what Firefox is doing and I'm intending to keep it as such. The user experience, and API, should remain compatible and any migration paths will be analogous.

We can also communicate that there's a major revision of Overlays brewing and in result we expect the current overlays logic to change and users should be aware of the revision coming by EOY.

If there's a person out there, working on a new website, and interested in providing localization capabilities, I think that their decision on whether to use @fluent/dom should be based on the semantic version of the package.

So, my suggestion for alternation would be: here's a plan, I'm working on making this right, please be aware that the API will change by the end of the year when considering using the project..

stasm commented 4 years ago

Can you explain what resource drain do you have on mind? What experience degradation are you worried about?

I'm worried about the cost of providing support to projects which start using @fluent/web. Every @fluent package out there extends the API surface which needs to be maintained and supported. Otherwise, we're just creating technical debt.

I'm also worried about the future cost of the project aiming to unify overlay syntax.

It's prior to 1.0 therefore it is not stable and if you want to use in production, you may have to invest in updates.

This isn't the reality we're in. Updates are usually a shared effort, where I personally help consumers switch to the more recent version. The reason for this is that at the end of the day, many of these projects are on Pontoon, which can support only one version of Fluent and one version of overlays at a time.

My understanding is that there's no additional dimension. Overlays work the same way in Firefox and @fluent/dom, so anything we'll have to do to update the former, will work on the latter (e.g. - scripts).

For Firefox, we'll likely take advantage of the migration infrastructure, which other projects don't have. For @fluent/react, I'll probably help each project migrate manually, as I have done for other API and syntax breaking changes in the past. I don't have the capacity to do the same for @fluent/web projects, other than iot-gateway and talk, which I mentioned above.

We can also communicate that there's a major revision of Overlays brewing and in result we expect the current overlays logic to change and users should be aware of the revision coming by EOY.

I think our opinions differ becase we have different past experience from Fluent upgrades. I wish I had your optimism :) You seem to be saying: This is 0.x, ; there will be API changes, you have been warned.

I think this is how it would work in an ideal world. The reality so far has been different, however. People almost never upgrade dependencies themselves, unprompted. And when we update Pontoon, we need all of the projects there to have upgraded. It's a lot of effort and coordination which I went through before Fluent Syntax 1.0 was published, and I'd like to avoid doing it again.

zbraniecki commented 4 years ago

Every @fluent package out there extends the API surface which needs to be maintained and supported.

Would it be alleviated if we moved it out of @fluent package to, say, @zbraniecki/fluent-web? :)

I think our opinions differ becase we have different past experience from Fluent upgrades.

Are you talking about Mozilla installations, or non-Mozilla installations?

Because I think they're different in the level of support we provide, and for non-Mozilla ones, I hope you don't have any work to do when upgrading.

For Mozilla on the other hand, the question is - what would you suggest for them in place of fluent-web until EOY?

Pike commented 4 years ago

A change to how overlays work will need to come with migrations for Mozilla projects.

As we take on programs like sanitizing DOM overlays, Mozilla will need to resource them end-to-end, and it's likely split among the time that stas, flod, zibi, and I have. There's an engineering part to this, but there's also workstreams around re-educating application engineers, and migrating existing translations, including finding a way to ship them. I.e., in the case of Firefox and the two overlay mechanism it uses, cross-channel is gonna be fun once again.

Only once such a program is completed, we can think about adding localizer-facing support for DOM overlays.

And yes, the caveat is that we don't have an alternative to propose right now, inside the Fluent ecosystem. And yet, it's also true that the more mass we gather on the current overlays, the less likely we're going to move our ecosystem.

zbraniecki commented 4 years ago

Thank you Axel for bringing your perspective!

After reading Stas and Axel's points, I'd like to summarize my position:

stasm commented 4 years ago

Thanks, @zbraniecki, I appreciate your position.

Would it be alleviated if we moved it out of @fluent package to, say, @zbraniecki/fluent-web? :)

A little bit :) I think more than the name on npm, I'm interested in setting the right expectations about the level of support now and in the future. I understand that @fluent/web may still be interesting for non-Mozilla consumers. OTOH, for Mozilla consumers, I'd like to set the expectation that @fluent/web shouldn't be used right now. To reiterate: this is a temporary measure.

Are you talking about Mozilla installations, or non-Mozilla installations?

I was talking about Mozilla's web projects.

For Mozilla on the other hand, the question is - what would you suggest for them in place of fluent-web until EOY?

I don't think we need to have an answer to this question right now. If there's a new Mozilla web project using vanilla JS which needs to be localized before EOY, we can then talk about our options. We'd do the same for an Angular project, for example.

stasm commented 4 years ago

New proposal: