Status of @fluent/dom

[stasm]

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:

• https://github.com/mozilla-iot/gateway and its forks, all using @fluent/dom 0.6.0.
  • https://github.com/grbesd1/mwot
  • https://github.com/jkim117/mozilla-iot-gateway-atomic
  • https://github.com/TwiggyBuffalo/webthings-gateway-nextjs
• https://github.com/coralproject/talk, which uses @fluent/react for the UI, and @fluent/dom to localize HTML email templates.
• https://github.com/mozilla/testpilot which uses @fluent/web, but has also been archived.
• https://github.com/psimonyi/openslowly, a web extension using @fluent/dom 0.5.0.

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]

CC @Pike, @zbraniecki.

[stasm]

Here's my proposal:

• Archive and sunset @fluent/web as it's not used by anyone.
• Communicate clearly that at this time, @fluent/dom is in the maintenance mode and that new projects should not use it.
• Later this year, define a new scope for @fluent/dom, taking into account the most probably use-cases. For instance, we might want to limit the support for shadow DOM for now and for observing multiple roots. We might be able to remove some performance optimizations which were needed for the startup scenario in Firefox, but which don't have much benefit on the web. We also might want to treat email sending (and SSR) as a first-class use-case.
• The definition of the new scope and drivers will coincide with our plans to design a unified Localization abstraction.
• Rewrite @fluent/dom with the new use-cases in mind and using the new Localization abstraction, in TypeScript.
• Implement the updated markup overlay logic at the end of the year.

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]

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:

• @fluent/web should be moved outside of project fluent. It should either be a separate repo or I can move it to github.com/zbraniecki and we can point it to people as an example of how to integrate Fluent into their Web App. It is a demo slash example and should be treated as such.
• @fluent/dom should keep getting updated to the current stable @fluent/bundle. This may be within the maintenance mode category, I agree. I don't agree we should discourage new projects from using it, without having an alternative to provide. I believe we can have maintenace mode without suggesting projects not to use it.
• @fluent/fallback should be carved out of @fluent/dom as it is not DOM specific and without it, many API decisions around @fluent/bundle look non-ergonomic.

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]

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]

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]

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]

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]

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]

Thank you Axel for bringing your perspective!

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

• I'm not interested in blocking Stas' proposal
• I disagree with Stas proposal
• I see value in maintaining fluent-web, and if it's a hassle to be maintained within projectfluent org, I suggest we move it to my personal org.
• I believe we should separate Localization from fluent-dom.
• I believe we should continue using current fluent-dom and fluent-web as the Fluent solution for localization of web apps.
• In the absence of alternative solutions, we should not discourage users of fluent-dom or fluent-web from using it.
• I'm not interested in blocking Stas' proposal

[stasm]

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]

New proposal:

• @zbraniecki If you're up for it, let's move the maintenance of @fluent/web into your GitHub fork. I'll archive the projectfluent/fluent-web repo and point to your fork in the README. I'll also deprecate the current version of @fluent/web on npm.
• @fluent/dom will be put in the maintenance mode. This means that for the next few months we're not planning to work on it. Potential consumers should be aware of this as well as of the fact that there will be a new version coming later this year with a possibly incompatible syntax for overlays.
• I'll update this issue once more details about the future of the overlays and the Localization class materialize.
• Later this year, define a new scope for @fluent/dom, taking into account the most probably use-cases. Rewrite @fluent/dom in TypeScript with the new scope in mind, and using the new overlays and the Localization class.