Now that we’ve gone through requirements from an MDN contributor
perspective let’s go through what John and I discussed.
@John, please correct me if I'm wrong. I’m persisting notes here to
improve understanding of the system; I may be wrong on some aspects.
Hopefully, this will answer technical constraints, and answer
requirements and, most importantly, make us all on the same page.
The following is assuming that Sebastian’s answers are representative
of others stakeholders. I’m doing this because I can’t wait to get
more feedback and feels similar to what I’ve deduced from
conversations I had so far.
# Recap of the requirements shared earlier this week
I’ve taken the liberty to comment what may be the impacts on the
system if we follow this course.
I’ll use them as a support what John and I discussed earlier this wee.
<aside>Entries below are archived in [MDN BrowserCompat Backlog][1]
spreadsheet.</aside>
> A) I want to be able to tell manually which
> Compatibility table to display on a given
> page. Regardless of where it is in MDN.
YES — Now archived as Backlog item #58
> B) I want to be able to read, and understand, the
> referencing string in the Kuma macro (i.e. not
> an opaque string or number)
YES — Now archived as Backlog item #59
> C) I want to be able to visualize the relationship
> between features (e.g. {{EmbedCompatTable
> ("/css/properties/background/origin")}} for
> background-origin support feature for
> background CSS property)
NO — Now archived as Backlog item #57
I feel uneasy about not prioritizing #57. It means we’ll have to set
an aliasing system in place. Not a bad thing in itself.
The reason I’m uneasy is that if we were to make something that looks
like a URL or a directory tree, we should clean up the data and
fulfill the metaphor.
Let’s see later, when we have more feedback, about whether we should,
or not take #57 into account at all.
> D) I want Kuma to be able to "guess" what table to
> display based on the MDN URL (i.e. in
> ".../Web/CSS/background", use {{EmbedCompatTable}},
> will show background CSS compatibility table)
YES — Now archived as Backlog item 60
I haven’t had a chance to discuss with John about this aspect yet.
> E) As BC, the Web Application and API, I want
> to allow clients to be able to recreate any identifiers
> systematically (i.e. like GitHub does with git
> commit hashes, and how we can view the commit
> on GitHub)
YES — Now archived as Backlog item #61
Making a hard bind between a human-friendly slug system and an API
identifier can’t happen. If we want to allow to rewrite them as the
resulting hash will also change.
The way I saw this requirement was as part of #57.
The heart of the issue that started this thread is about the
limitation of what we can use in a Kuma macro (e.g.
{{EmbedCompatTable('foo')}}) **because** we were using it directly as
a BC API call (e.g. `?slug=foo`).
Having (#57 false, and #61 true) made me revise the position I had
earlier this week;
> (...) the impact of disagreeing with #61, would require we make
> "at insert time" ID. That ID could be a number or generated UUID,
> but in both cases still get an identifier that would be unique to each
> BC deployment. With this design decision, we wouldn't be able to
> sync data between a staging instance hosting data we want to merge
> into production. (...)
This would be the case where it’s maybe best we have unique
identifiers at insert time for BC API and a way to map slugs to the
opaque identifier. An aliasing system of sorts.
All of this to say that making an insert-time unique identifier, such
as an opaque string, a number, or a UUID on BC API side, isn’t a bad
idea after all.
As long as (#58, #59, #60) are fulfilled and make MDN Contributors
don’t have to deal with this complexity, or fill a page with cryptic
or ambiguous code.
[1]: <
http://bit.ly/mdn-browsercompat-backlog>
--
Renoir Boulanger
Web Browser Compatibility Data Lead
Mozilla Corporation