Resources are accessible by slug

RESOLVED WONTFIX

Status

defect
--
major
RESOLVED WONTFIX
5 years ago
2 years ago

People

(Reporter: jwhitlock, Unassigned)

Tracking

Details

(Whiteboard: [bc:infra][bc:milestone=spaceship])

What problems would this solve?
===============================
Many resources include a unique slug, which is a more human-friendly identifier than the integer database key.  It is better for documenting the desired resource, and it will be easier to detect typos (1 and 2 vs 'chrome' and 'firefox')  However, the API call for filtering by slug is ugly.

Who would use this?
===================
API users like MDN that need to capture a resource ID in their own database or source code.

What would users see?
=====================
Instead of these URLs:

http://doesitwork-dev.allizom.org/api/v1/browsers/2
http://doesitwork-dev.allizom.org/api/v1/features/19

users would use:

http://doesitwork-dev.allizom.org/api/v1/browsers/firefox
http://doesitwork-dev.allizom.org/api/v1/features/web-css-color_value

What would users do? What would happen as a result?
===================================================
Users would use slugs to access the API instead of database primary keys

Is there anything else we should know?
======================================
Blocks: 1063168
Severity: normal → enhancement
Blocks: 996570
No longer blocks: 1063168
Depends on: 1153288
Commits pushed to master at https://github.com/mozilla/web-platform-compat

https://github.com/mozilla/web-platform-compat/commit/69349e50451866b65313cbbbf544f28bc0795373
bug 1078699 - Requirements bump

alabaster 0.7.4 -> 0.7.5 - small fixes
check-manifest 0.24 -> 0.25 - small fixes
ipdb 0.8 -> 0.8.1 - small fixes
mccabe 0.3 -> 0.3.1 - small fixes
py 1.4.27 -> 1.4.28 - small fixes
pyflakes 0.8.1 -> 0.9.1 - small improvements
pyroma 1.8.1 -> 1.8.2 - basestring is not error!
tox 2.0.1 -> 2.0.2 - pass LANG environ variable
virtualenv 13.0.1 -> 13.0.3 - update pip
django-mptt - 0.7.3 -> 0.7.4 - Fix issue w/ get_queryset_ancestors
djangorestframework - 3.1.2 -> 3.1.3 - various unrelated fixes
nose 1.3.6 -> 1.3.7 - Windows fix
psycopg2 2.6 -> 2.6.1 - small fixes
django-cors-headers - bumped to master, still unreleased
parsimonious - bumped to master, still unreleased

https://github.com/mozilla/web-platform-compat/commit/77c099fba8d3e67ba96109550ebc754070f09cf4
bug 1078699 - GET /api/v1/view_features/by_slug

Allow the feature slug to be used instead of the feature ID when
fetching the feature and related data.

https://github.com/mozilla/web-platform-compat/commit/6d3a591bce79e8f15a80c85d31f65d55eacdbc30
Merge pull request #39 from jwhitlock/1078699_resource_by_slug

bug 1078699 - GET /api/v1/view_features/by_slug
Component: General → BrowserCompat
As part of Skateboard, I am experimenting with displaying the new tables.
Features are available by slug, but I would like to bring up for discussion how the slugs look like.

E.g.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all
http://browsercompat.herokuapp.com/importer/5032

The slug here is 
> "web_javascript_reference_global_objects_promi561a8"

I think due to the length it gets hashed. From shorter slugs, I would have expected:
> web_javascript_reference_global_objects_promise-all"
But this fails atm.

I am not sure (given MDN will not be the only consumer of compat data), this slug makes sense. Wouldn't it be nicer to make the compat data available under the name of the API? E.g.
> "promise-all"

Or, if we have a way to re-use the categories we also use for filtering the imported pages, maybe:
> "javascript-promise-all"

Slugs need to be unique, but something more readable and intuitive would save a lot of time, as I currently have to look up the hashed slug name for every feature I want to include on MDN.
Status: UNCONFIRMED → NEW
Ever confirmed: true
renoirb has concerns about the slugs as well, added him to CC list.

When auto-generating slugs, using the full MDN path is the best way to ensure unique slugs, but it falls apart for these long paths.  One solution would be to increase the size of slugs from 50 to 100, or whatever would cover current MDN use cases.  Another (which I'm not recommending) is to reduce the length of the path name on MDN.

Currently, the API does not allow slugs to be modified, because they are a promise to API users of where data is located.  It's also extremely painful to fix downstream issues when a slug changes.  We did it for bug 1128525, and we're still working through the consequences.


However, in these early days, it may be useful to manually adjust some slugs. This could be added as an API permission, or we could do a one-time cleanup of slugs based on a spreadsheet.

So, in summary, here's some API-side changes:
1) Expand slug length so hashing doesn't occur - easiest, with some data cleanup
2) Add API permission to update slugs - 1-2 days of code, potential issues when API is used in production
3) Generate new slugs, with manual overrides, for all MDN pages - Collaborative process, will probably require wiping out feature / support data already committed to API.  Possible now, impossible later.
Hi,  I've spent some more thoughts about the issue.

John and I had talks on how to generate the slugs and make them harmonized (e.g. Two object method siblings getting different separators web-api-idbenvironment vs 
web_api_idbenvironment_indexeddb). Which might confuse contributors on how they can guess a slug name if its unclear why its an - or a _.

The point I wanted to make is to prevent confusion between "directory" separator from element name.  

For example

web-css-position implies position css property within the web platform

But what about names that genuinely uses - as part of their name such as border-radius.

We've had some talks on rules proposals (won't be all listed here ATM) and another limitation came up;  we want the slug to be easy and valid ascii characters so we won't need to make humans remember to urlencode. Failing the purpose.

Now that I see that lenght is another limitation, It came to me the conversations I had two years ago with Doug Schepers at W3C about that.

What we came up with was to follow simplest rules:

1. Use the feature name (e.g. background-color)
1. lowercase it
2. Remove any non ascii characters
3. Replace spaces by _

We named this a "feature"

But what if we have things with same names in different contexts.

For this, we decided to separate the elements in a parent that defines them.  MathML, SVG, HTML, in their own namespaces.  We named this a "topic".

The current compatibility tables implementation I built for webplatform.org uses this as parameters to tell the mediawiki macro to build an html table based on data it has in the huge and incomplete JSON string we created.

We could the display font html element (not SVG's) compatibility table like this.

    <compatibility topic=svg feature=script></font>

You can see it in action here [1], raw wikitext[2] will show you.

All of this to say that maybe we should consider repeat this idea.

PS: compatibility tables is disabled in webplatform's production wiki. Notice the address [1] its in /test/ not wiki.  If you want to play with my implementation, you'll have to stay in /test/)

[1] <https://docs.webplatform.org/test/Tests/Compatibility_table_and_caching#SVG_Script_tag>
[2] <https://docs.webplatform.org/test/Tests/Compatibility_table_and_caching?action=raw>
I think the solution of this bug blocks installing skateboard on a broader set of pages. That is, if slugs change, there is no point in using the current slugs all over the place. For a beta, we need to install skateboard on a broader set of pages.

(In reply to John Whitlock [:jwhitlock] from comment #3)
> So, in summary, here's some API-side changes:
> 1) Expand slug length so hashing doesn't occur - easiest, with some data
> cleanup
> 2) Add API permission to update slugs - 1-2 days of code, potential issues
> when API is used in production
> 3) Generate new slugs, with manual overrides, for all MDN pages -
> Collaborative process, will probably require wiping out feature / support
> data already committed to API.  Possible now, impossible later.

This sounds like a good plan to me. I think we need at least 1) for beta. 

3) sounds like something we want in the long run.
Severity: enhancement → major
Here are some notes I made about the requirements we want to fill.


What we're trying to achieve
============================

Slugs are meant to be human rememberable. As in a few words, harmonized.

If a slug is that long, why bother and not use an UUID, a number, a hash, or anything similar.

Use of slugs in BC and MDN:
* Identifier that a human can type to get a table
* Tag to use when searching
* More likely to remember if it's short and direct term to the page on topic

Devil's advocate:
* Once we know the slug, copy paste is good enough
* Why not using numbers then?

Made up list of desirable slug properties:
* Short, less words as possible
* Representative of what it aliases to
* Human readable (and easy to remember?)

Maybe it would be worthwhile to focus on simplifying even more slugs.

We have this opportunity to fix something that went out of control over time and improve at another spot usability of MDN.

We’ll only have that one shot at it.

I agree, though, that we don't have unlimited time bandwidth.


Let's see which ones is simpler for you to do that'll serve users.




Use two arguments instead of one (opaque?) string
=================================================


I know I'm making the recommendation I implemented on WebPlatform, but I don't see why it's not a good idea.

Using two arguments could enforce the "directory" like paradygm, and lower uniqueness issue to lesser number of pages it could collide with.

That way, if we have a search index, we'll be able to make it give us collection results for collision, yet be specific when required.

e.g. script tag is in both SVG and HTML

  {{EmbedCompatTable('script', 'svg')}}
  {{EmbedCompatTable('script', 'html')}}
  {{EmbedCompatTable('script', 'dom')}}

Instead of 

  {{EmbedCompatTable('web-svg-element-script')}}
  {{EmbedCompatTable('web-html-element-script')}}
  {{EmbedCompatTable('web-api-svgscriptelement')}}


Reasons I see about this doesn't seem enough to break the benefits we'd gain:


1. Everything has a slug, including parents and we want "directory" like feel.

Omitting the second argument would give the list of everything that has 'script' as slug, which may be something people wants.


2. Slug creation complexity can-of-worms

We have a lot of concatenated parts, we may create collisions.

A complexity I see is that we don't want to make the slug creation process parse the targeted page and see if it has a compatibility table or not.

To take the example of HTML input element spellcheck attribute documentation page [1] has no compatibility table, but is part of the input HTML page [2].

This is why I’d like to see how far we can simplify slugs, and an ability to change slug from the API looks like a sensible thing to do for after this work item.


  [1]: <https://developer.mozilla.org/en-US/docs/Web/HTML/Controlling_spell_checking_in_HTML_formsControlling_spell_checking_in_HTML_forms>
  [2]: <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Browser_compatibility>
I started a thread on the public mailing-list [1], pasting here the notes.

I've sent two messages that are meant to help clarify the scope of this issue.

This comment contains the two sent messages, for posterity.

* 1. Initiating the thread
* 2. Ask community about priorities


# 1. Initiating the thread

On Monday, November 23, 2015 at 3:26:28 PM UTC-5, Renoir Boulanger wrote:
> Hi folks,
> 
> We're about to start migrating MDN pages to use BrowserCompat ("BC")
> backed compatibility tables.
> 
> This process will have us, and our contributors to insert a macro with
> a "slug" (e.g. `{{EmbedCompatTable("foo")}}`). That will display the
> API-backed table to some users, and the traditional wiki-backed table
> to the rest.  Eventually, the wiki-backed table will be removed,
> leaving just the slug connecting the MDN page to the BC API feature,
> and moving data management to the API and contribution interface.
> 
> The problem about the slugs is that they look very similar to an MDN
> URL and gives the impression a user could change parts of it to get
> another table, but the promise breaks quickly.
> 
> A discussion arose about the format of the slug, if it should give a
> textual representation (e.g. "web-css-border-radius"), if it should
> simply be an opaque string (e.g. "000-000-000"), and other similar
> questions.
> 
> We're still at the early stage of BC, but we’re about to make a big
> leap by migrating MDN pages to use BC backed tables.
> 
> The reason for prioritizing; the JavaScript pages are a good candidate
> for converting.
> 
> We thought of using JavaScript topic because; existing tables errors
> has been fixed and can be easily imported, the translators for this
> section do a good job at keeping their version up to date with the
> English page, and the JavaScript topic is the one that has most
> traffic on MDN.
> 
> On the flip side, the JavaScript topic pages are the ones with the
> longest URLs and would hit this issue quickly.
> 
> All of this is to say that we could have a good amount of pages to
> roll the BC backed tables and do some stress-testing.
> 
> Not a lot of pages has the macro —about 20; yet, maybe we should make
> a change before it's too late.
> 
> This essay is about finding a future-friendly solution for identifying
> what data we display on MDN and on BC API side, so we won't have
> regrets later.
> 
> In the following sections, I'll cover the potential problems we might
> face with the current implementation, make a requirement proposal and
> give options with pros and cons so we can make an informed decision.
> 
> 
> 
> # The current state
> 
> The origin of data BC is, for the most part, from MDN, it's natural we
> associate 1:1 a documentation page URL to a feature.
> 
> For example, we could be tempted to use "Web/CSS/border-radius" as
> identifier directly from BC. But it's not a good idea for many
> reasons, one of them being a limitation of which characters we can use
> in a path  (e.g. the bar part in "/api/foo/bar") or query (e.g. after
> the "?") part of a URL. Due to that need to be usable in an URL, we
> are limited to use ASCII Alphanumeric characters.
> 
> The initial BC identifier scheme, referred to as "slug", is roughly
> lower casing and replacing parts from an MDN URL (e.g.
> "Web/CSS/border-radius") to make it valid URL part (e.g.
> "web-css-border-radius").
> 
> The requirement to fit within ASCII Alphanumeric and be path-like is
> forcing us to try replacing slash ("/") with a dash, and other
> manipulations in an attempt to ensure we have unique identifiers.
> 
> The fact we're close to MDN URL scheme, in which we don't mute some
> words, quickly makes a long string and becomes hard to predict (e.g.
> "web_javascript_reference_global_objects_numbea9a2b"). Which in the
> end may confuse users and would lose its essence if the original page
> change location.
> 
> This scheme seemed to make sense at first, but gets out of control
> quickly and with the compound need to have not-too-long and unique
> identifiers, we get forced truncate and add random characters; Which
> breaks the "usable for humans." principle of slugs.
> 
> A solution could be we don't use slugs at all, and use database insert
> ID, or other "auto increment" number. Unfortunately, due to the nature
> of databases, we can't get for sure the same ID between full import
> runs and would break the contract of identifying uniquely and
> consistently.
> 
> 
> ## The limitations
> 
> As previously stated, one reason we can't use a path-like (i.e.
> "Web/CSS/border-radius", converted to "web-css-border-radius) as a
> resource identifier is that it becomes quickly out of control, and we
> can't help users predict the syntax to use.
> 
> Here are a few MDN path and what would be the "slugs" to use with the
> current implementation;
> 
> /Web/JavaScript/Reference/Global_Objects/RegExp, into
> web-javascript-reference-global_objects-regexp
> 
> /Web/JavaScript/Reference/Global_Objects/NumberFormat, into
> web-javascript-reference-global_objects-numberform
> 
> /Web/JavaScript/Reference/Global_Objects/NumberFormat/resolvedOptions, into
> web_javascript_reference_global_objects_numbea9a2b
> 
> /Web/CSS/display, into
> web-css-display
> 
> /Web/CSS/background-color, into
> web-css-background-color
> 
> 
> Notice the following:
> 
> * We can't know for certain when should we use dash ("-")
>    instead of underscore ("_")
> 
> * Some words are redundant making the slug
>    longer and could be omitted
> 
> *  We can't know how to separate categorization
>    (e.g. Web, CSS) from predicate (e.g. border-radius)
> 
> * The text is directly bound to an MDN URL
> 
> 
> Besides, we can't copy-paste strings with dashes easily. When we
> double click, we don't get the full string selected but only the word
> between the dashes.
> 
> 
> With those examples in mind, we can observe the following limitations:
> 
> 
> 1. Users might want to use the same compatibility table on another MDN page.
> 
>   Not only the page that particularly explain the feature.
> 
> 
> 2. A human might not be able to guess what to change in a too long or
> cryptic string.
> 
>   For example, the Number JavaScript API method
> NumberFormat.resolvedOptions has
> "web_javascript_reference_global_objects_numbea9a2b" as a slug.
> 
> 
> 3. On MDN, content moves around independently and so URLs can change.
> 
>   At any time, it's most likely that somebody will rework
> documentation about a feature and move content and URLs around.
> 
>   We could try to find a way to harmonize how we refer and a way to
> translate to some identifier the feature for BC internal purposes but
> without adding complexity at the places users will interact with it.
> 
> 
> 4. BC isn't running as part of MDN runtime.
> 
>   It can't know about things that got renamed. It is debatable,
> whether or not it should track or act differently about it.
> 
>   The exception is to help us migrate out of MDN data currently holds.
> 
> 
> 5. URL on MDN often also represent a locale.
> 
>   A User-Agent feature will work the same anywhere, regardless of
> which language the user understands.
> 
>   Only difference BC will do display in English and allow us to tell
> in which language we want the data. If the translation exists, it'll
> be displayed.
> 
> 
> 6. In a foreseeable future, MDN won't be the only place to display
> compatibility tables.
> 
>   We may want the ability to merge datasets between BC sites but for
> this, we would need a systematic way of creating an identifier.
> 
>   An incremental, or one-time unique string such as an UUID wouldn't
> work for this, unless other sites constantly imports from our database
> dump or we keep a mapping somewhere.
> 
>   A solution to this could be that we hash a human-friendly slug so we
> meet both sides (slug for Kuma + opaque identifier for BC API). That
> would be another discussion though.
> 
> 
> 
> 
> # Requirements
> 
> For an ideal solution, we'd require.
> 
> 
> ## BC Identifiers
> 
> * ASCII Alphanumeric + "_", "-", and URL encoded
>   (ref: URL code points)
> * No collisions
> * (optional, if we want human-usable slugs)
>    Predictable scheme
> 
> 
> ## Slugs
> 
> 
> Those would apply, unless we aren’t using slugs at all.
> 
> Remember: the idea of a slug is to be possible for a human to read and predict.
> 
> * One character to mark categorization+predicate
>    separation
> * No collisions
> * No ambiguity and not too long
> * Makes it possible to visualize what it’s
>    about
> * Max length of 100 characters
> * No dash, as it’s hard to copy-paste
>    dashed strings
> 
> In this case, we're likely to need a way to convert into a valid BC
> API identifier.
> 
> 
> 
> 
> 
> # Proposed solution
> 
> 
> The question boils down to; Should we use slugs, or should we use an
> opaque string (e.g. “000-000-000” a UUID, “ab1ab2ab3ab4ab5ab” a hash)?
> 
> 
> Also, do we want to have the same string to represent a given feature
> on both systems:  In KumaScript macro, AND on BC API URLs?
> 
> 
> If we decide, as a community, that BC API uses opaque identifiers
> (e.g. "/api/v1/features/000-000-000") it doesn't mean we can’t set in
> place tools for MDN contributors to know what to paste in the page.
> 
> 
> We are in front of two possible solution paths:
> 
> 
> Don't use a slug at all in Kuma; use the same identifier as BC API
> 
> Use an unlimited slug in Kuma; convert into BC API elsewhere
> 
> 
> Depending on the choice, we’ll be able to tell what to prioritize
> about it and see when we can make this change.
> 
> -- 
> Renoir Boulanger
> Mozilla Corporation



-------



# 2. Ask community about priorities

On Wednesday, November 25, 2015 at 3:37:44 PM UTC-5, Renoir Boulanger wrote:
> Let's continue this discussion about slugs and requirements.
> 
> Instead of me talking about how we could do it, something I’m keen to do,
> let’s dive into what we may or may not want.
> 
> The technical solution will impose itself once we get an agreement.
> 
> My objective is to clarify untold or silent requirements so that we can
> validate, or reject them, in the clear.
> 
> I carefully picked the use-cases below because I couldn't find a clear
> decision made about them.
> 
> The four first are from the perspective of BC when used within Kuma (MDN);
> the last one is from BC’s perspective and the contract to the web we could
> make.
> 
> 
> 
> Please answer yes/no to the following;
> 
> 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.
> 
> 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)
> 
> 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)
> 
> 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)
> 
> 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)
> 
> 
> 
> Once we figured out those requirements, we'll be able to define a set of
> rules and mechanism to enforce our choices.
> 
> Notice that the impact of disagreeing with "E", would require we make "at
> insert time" ID. That ID could be a number or generated UUID, but in both
> cases still be an identifier that would be unique to the 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. Furthermore, what
> if another entity maintains a CSS properties compatibility-data system
> running BC, and **DON’T IMPORT** from Mozilla/MDN backup/database dumps.
> 
> This situation may not be fun to think of, but we could have in our design
> a way to pull data between systems instead of creating a technical walled
> garden.--
> *Renoir Boulanger*
> Web Browser Compatibility Data Lead
> *Mozilla Corporation*





[1]: <https://groups.google.com/d/msg/mozilla.dev.mdn/SBiFR6oQVcQ/i00SsAoHGgAJ>
For posterity, another message I sent to the mailing list[1].

[1]: <https://groups.google.com/d/msg/mozilla.dev.mdn/SBiFR6oQVcQ/i00SsAoHGgAJ>

On Friday, November 27, 2015 at 6:58:19 PM UTC-5, Renoir Boulanger wrote:
> 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
---------- Forwarded message ----------
Subject: Cast your slug requirement vote [was: Let's talk slugs...]
> 
> Hey folks,
> 
> Thanks for the feedback.
> 
> Two things,
> 
> 1. Slug requirements: Cast your vote
> 2. Review the slug scheme proposals
> 
> 
> 
> # 1. Slug requirements: Cast your vote
> 
> Except Sebastian, nobody else voted.
> 
> I'm sure others would like to cast their votes.
> 
> Here are the initial use-case statements discussed earlier, and a few new ones at the bottom.
> 
> The number beside the statement is the row in which it's saved in the BackLog document.
> 
> <http://bit.ly/mdn-browsercompat-backlog>
> 


(snip)

[[ they already are noted in this issue ]]


> 
> 
> And those new ones I found while re-reading the thread;
> 
> 
> 64) AA External BC relier, IWT be able to read a copy
>     of the current data from the filesystem
> 
> 
> 65) AA User, IWT change the slug because it would make
>     more sense to change it's parent or when I found
>     a spelling mistake
> 
> 
> 66) As BC, IWT support aliasing slugs into direct
>     resource locations I store locally so that reliers
>     don’t need to keep a copy of the mapping themselves
> 
> 
> 
> # 2. Review the slug scheme proposals
> 
> So far we had two proposals in spreadsheets, here are the links.
> 
> 
> Stephanie’s
> 
> <https://docs.google.com/spreadsheets/d/183GTY9Iq6uG2uN3QTTSUvTvDpiIhj1nOuYJRH7GG0TA>
> 
> 
> My slug proposal
> 
>  <http://renoirb.com/prototypes/2015/browsercompat/slug-scheme.html>
>  
> 
> Stephanie's, using Renoir’s jsfiddle 
> 
> <https://jsfiddle.net/stephaniehobson/h1v5ecgj/2/>
> 
>
[[ Adding this here for posterity ]]

On Wednesday, December 2, 2015 at 3:10:32 PM UTC-5, Renoir Boulanger wrote:
> Hey folks,
> 
> Yesterday, John, Stephanie, Matthew and I were talking about BrowserCompat, slugs, and how to determine what table to display on MDN (Kuma), beyond the details and into the problem we're trying to solve. 
> 
> We've found a way that'll simplify work for contributors and get better control rolling the feature out.
> 
> TL;DR; 
> * Use Kuma document model field to store BC API feature ID
> * Use existing {{CompatibilityTable}} macro that's already in pages, as a placeholder
> 
> Displaying a new BC backed compatibility table will only be a matter of;
> * Kuma stores a BC API feature ID in the page's document model
> * BC API delivers compatibility information for that feature id at the time Kuma regenerates the page (previous save, force refresh)
> * The user sees the API-backed page if they have the waffle enabled (a.k.a. "Feature flag")
> 
> In other words, set aside a few adjustments, we already have all we need to migrate to new BC backed compatibility table!
> 
> The use of Kuma document model field to store the BC feature ID will make the field accessible exclusively to those who has access to the admin interface --NOT the contributor interface. We are aware that contributors will want to be able to change that value. We're assuming that for the initial rollout, it'll be OK as is, but a public editing interface will be a requirement before releasing the feature to all users.
> 
> 
> # Context
> 
> So far, we've been using hard-coded tables in HTML within the page body and use multiple macros for multiple purposes. Adding yet another macro with some text was just "business as usual". While attempting to tell which table to display, BikeShedding crept in and went about how one *prefers* one string format to another. 
> 
> Talking about what piece of text to use to tell *what* feature we want to display on a page can be a never ending spiral and a can of worms of other requirements. 
> 
> Our discussions went around: What if we don't require contributors to paste a new macro to display a compatibility table? Then, what do we need to do to make it happen?
> 
> After all, what we're really after is to Display a compatibility table.
> 
> If we need to display more than one on a page later on, we'll have already in place what's required.
> 
> In the end, the use slugs or any other identifier type --other than the BC's ID-- isn't a feature but rather a way to achieve the desired outcome that is to Display a compatibility table.
> 
> If we can display table without a slug; they become a non-issue for us to display compatibility tables on MDN.
Just to summarized, are we okay to get ride of slugs and use UUID instead?
If so, do we want to close that bug and have new one dedicated to implement UUID or just turn this one into implementing UUID?
Flags: needinfo?(jwhitlock)
Summary: [Compat Data] Resources are accessible by slug → Resources are accessible by slug
Whiteboard: [specification][type:feature] → [specification][type:feature][bc:infra]
This bug was hijacked by a discussion of automatically generated feature slugs, and we agreed to get rid of those.

However, we are still using slugs on other resources. For example, desktop firefox is available at this URL:

https://browsercompat.herokuapp.com/api/v1/browsers/6

After switching to UUIDs [1], the URL will look more like:

https://browsercompat.herokuapp.com/api/v1/browsers/9a22b218-78a0-4cf4-907d-b0c5d8f23653

After this work, it would also be available at:

https://browsercompat.herokuapp.com/api/v1/browsers/firefox_desktop

This was the original purpose of the bug, and is still a valid, unprioritized feature.

For features, it has been proposed to change from a required slug to an optional list of aliases [2]. A similar change could happen for browsers. However, the alias would still be unique across browsers, and this URL trick would still be useful.

Note that trying the "alias" URLs currently results in a 500 error [3].

[1] https://bugzilla.mozilla.org/show_bug.cgi?id=1230306
[2] https://bugzilla.mozilla.org/show_bug.cgi?id=1240785
[3] https://bugzilla.mozilla.org/show_bug.cgi?id=1229783
Flags: needinfo?(jwhitlock)
Mentor: jwhitlock
Whiteboard: [specification][type:feature][bc:infra] → [bc:infra][bc:milestone=spaceship]
Mentor: jwhitlock
The BrowserCompat project is canceled.  See https://github.com/mdn/browsercompat for current effort. Bulk status change includes the random word TEMPOTHRONE.
Status: NEW → RESOLVED
Closed: 2 years ago
Resolution: --- → WONTFIX
You need to log in before you can comment on or make changes to this bug.