More clarity on what baseline represents?

[evanw]

Hello! I'm the author of esbuild and one of my users has requested the ability to set esbuild's target to a "baseline" for a specific year. It seems like it should be possible to add this feature except that I'm really struggling to figure out what baseline means. I searched for a while but was unable to find a usable definition. If I'm confused then I suspect others are too. I'm not sure if this is more of a question that can be resolved by just being pointed to existing documentation, a bug report about missing/unclear documentation, or a feature request for an additional data set to make the definition of baseline usable for other tools.

From https://web.dev/blog/baseline-definition-update it intuitively seems like baseline for the year XYZ is something sort of like "features that were present in all of the four browsers we care about 30 months prior to the year XYZ." But then I couldn't find data to back that up. I was expecting to find something like "baseline 2022 means Chrome ≥87 + Firefox ≥84 + Safari ≥14 + Edge ≥87" because that would be something I can easily work with. My search led me to https://github.com/web-platform-dx/web-features/tree/main/feature-group-definitions, but that a) just has things like baseline_low_date and baseline: high which I don't think is enough information for me to use and b) seems to be updated by hand picking which features are in or out instead of using a data-driven approach to deriving the baseline status from existing feature compatibility tables. Basically it's unclear if the "30 months" thing is actually how baseline works or if it's just a fuzzy guideline and how baseline really works is a collection of independent decisions about each feature. This matters for me because I need to figure out how to write some code to map something like "baseline 2022" into supported/unsupported statuses for each relevant feature.

Also: I found #522 about adding a baseline_high_date field, which seems relevant. But one of the comments seems to imply that the definition may be altered over time. Is that a deliberate goal of the baseline project (to have a definition that can change over time)? If so, that would be good for me to know as it would then not be something I will be integrating into esbuild. I want esbuild to be a deterministic build tool and having something like "baseline 2022" change in meaning over time would go against that goal.

Sorry for asking these questions! I'm interested in potentially integrating baseline status into esbuild but I'm confused and need some help 😅

[tidoust]

Hi @evanw. Thanks for the interest! There are a few things to unpack in your comment. Before I get to the core of the issue, let's see if I can clarify a few things 😅

Baseline is formally defined in the Baseline document. That document attempts to clarify the ins and outs, and contains the rules followed to set the low and high Baseline statuses. The definition is linked from the beginning of the README in the repository, too bad that the web.dev article that you started from does not link to it...

Essentially, features defined in web-features link to a list of individual features in BCD. The Baseline status is then derived from BCD data. As such, the project does use a "data-driven approach to deriving the baseline status from existing feature compatibility tables". Unless you're thinking about something else?

The goal is to create meaningful features in web-features. That requires assessing whether a feature makes sense as a whole, and then assessing what individual features it encompasses. There may be good reasons to include/exclude individual features from the definition of a feature in web-features. For example, CSS Grid and Media Source Extensions could mean different things to different people. Both of these assessments are manual. I think that's the "hand picking" process that you describe.

As noted in the Baseline definition, editorial overrides of the Baseline status are also possible if the group feels that they are warranted, e.g., because there are too many bugs in implementations. I don't think there are examples of such overrides for now though. Most of the times, these problems will get trapped at the individual feature level in BCD.

The project is still relatively new. Automation is work in progress, and some of the steps that ought to be automatic currently require manual intervention. The list of features should also grow over time.

The Baseline definition is indeed expected to change over time. It will be reviewed on an annual basis at a minimum. The goal is not to surprise people but rather to fine-tune the definition as new and possibly better data becomes available to compute wide availability, and/or to change the list of core browsers that need to be considered. There is no guarantee that a feature that was Baseline will remain Baseline, see Goal 2 in the Baseline definition.

Now to the core of the issue: the group has been using the concept informally but I don't think that there is a concrete definition of "Baseline 2022" or "Baseline 2023". Given that the date could change over time, the addition of a baseline_high_date field is probably not what you need,

I'm sure people involved in web-features will have other ideas, but one idea that comes to mind would be to tag the version of web-features that the group considers to be "Baseline 2022", "Baseline 2023", etc. (there are releases already, but none of them says "I'm Baseline 2022!" for now). That would effectively give you a pointer to frozen data. How about it?

[Not mandatory of course, but if you're available and interested, you're most welcome to join an upcoming group call so that we can figure out what changes and tools may be needed to ease integration in esbuild. Next call dedicated to Baseline is this Thursday at 4pm UTC. Let me know if you'd like to join]

[evanw]

Thanks for taking the time to write a thorough reply. It's great to have some additional context around this and the link to baseline.md was very helpful. For example, I know now that I shouldn't be trying to derive baseline status myself using a 30 month date offset, as each feature in/out decision is made by a human (although heads up that some other people have that intuition too).

From what you're saying, it sounds like baseline is more of a guide for developers to pick what features to use and what features to avoid, and not really something intended for tools like esbuild to consume. That's perfectly fine! This seems similar in spirit to Browserslist but on a feature-by-feature basis instead of browser-by-browser basis. Browserslist is a great tool for developers, but it's also not a good candidate for inclusion in esbuild for the same reason (the definition is continuously changing, by design).

Perhaps this isn't something that belongs in esbuild after all, at least unless the "pointer to frozen data" is present. But please don't feel pressure to do additional work to support that use case. There are probably a lot of other decisions to be made (e.g. by-year may even be the wrong approach since browser release many versions a year, so it could be up to a year out of date) and it could be a distraction from what it seems like you're trying to do, which is write a guide for people to read.

Thanks for the invitation to the call but I'm unfortunately unavailable to join any live discussions at the moment. Feel free to close this issue as I now think I have sufficient clarity on what baseline represents.

[Shinigami92]

https://github.com/web-platform-dx/web-features/tree/main/feature-group-definitions looks like something I should explore 🤔
Right know I miss explorability on MDN docs and find it a bit sad that when something is not in baseline, it is just not displayed at all as e.g. grayed/"negative" banner or at least as "not defined yet" status

Sorry if I pollute this thread and tell me if we should open another thread about it, but maybe I could write a tabular application to make these yaml data visually presented (and search-/filterable) on one site with links to their sources 🤔

I'm dreaming about e.g. an eslint-plugin one day that warns about usage of non curated baseline features

[tidoust]

@evanw Understood. I'll keep the issue open for now as that seems worth discussing in the group. I think this also links to @romainmenke's request in #524, which suggests creating dedicated Baseline versions of browsers so that developers can test a Baseline target more easily.

[tidoust]

@Shinigami92 I linked to your comment from #538 for the visualization part although it may be orthogonal to what you're willing to do. In #538, the goal is to explore the list of BCD features that do not yet link to web-features. Such individual BCD features are at a fine-grained level (e.g., an IDL interface or method), and not at a coarser "X/Y/Z API" level.

If by "non curated Baseline features", you rather mean the list of features in web-features (in other words, that have a YAML file) that don't yet have a Baseline status, we need to track that of course, but my expectation is that the list should shrink to an empty set relatively quickly: we're adding Baseline statuses progressively right now, but once we've gained enough experience, the process should probably run more smoothly and there should not be a huge delay between the time a feature gets added to web-features and the time it gets a Baseline status.

In any case, tooling to visualize the YAML data is definitely of interest. If you write an application to explore and visualize the yaml data in any way, feel free to share, or contribute ;)

[romainmenke]

For postcss-preset-env I haven't decided yet if a baseline or baseline-2022 preset should exist, but I have added baseline labels as a communication tool to our users.

This surfaces here :

• https://cssdb.org
• https://github.com/csstools/postcss-plugins/blob/main/plugin-packs/postcss-preset-env/FEATURES.md
• and on each feature readme : https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-cascade-layers#readme

If our users are targeting "baseline" or "baseline 2020" they can easily see which polyfills/fallbacks/transpilers are still relevant to them.

We do use a "30 months ago" calculation : https://github.com/csstools/cssdb/blob/a4cb4e43e8b321cfdf5f254815805dfa5831fd1a/utils/baseline-status.mjs#L10-L15

Mostly because our grouping/definition of individual features predates web-features, so calculating our own status makes more sense at this time. This might change in the future.

It isn't perfect, but I hope that this helps our users to find an easy answer to "do I still need postcss-preset-env today"

[captainbrosset]

https://github.com/web-platform-dx/web-features/tree/main/feature-group-definitions looks like something I should explore 🤔 Right know I miss explorability on MDN docs

I'm sure you're not the only one. Let me create a different issue on the repo for this: #541 .

[Shinigami92]

Maximal ugly and absolutely point of starting 😄

• https://github.com/Shinigami92/baseline-green
• https://shinigami92.github.io/baseline-green/