1246967 - Add a UUID to the page API

Status: RESOLVED FIXED

(developer.mozilla.org Graveyard :: API, defect)

Description

[John Whitlock [:jwhitlock]]

What problem would this feature solve?
======================================
MDN and the BrowserCompat (BC) service will soon use a UUID to link MDN pages to BC features (bug 1230306). If MDN generates a UUID to identify pages, then the BC service can adopt the English page's UUID as the feature UUID, reducing or eliminating the need to sync UUIDs to the MDN database. The UUID could then be used by an enhanced CompatiblityTable macro [1] to automatically display API-backed compatibility table when available.

[1] https://developer.mozilla.org/en-US/docs/Template:CompatibilityTable

Who has this problem?
=====================
Core contributors to MDN

How do you know that the users identified above have this problem?
==================================================================
The 'skateboard' phase of BC deployment proved that slugs were a contraversial way to link MDN pages to BC features (see the comments on bug 1078699). This also required manually or programmatically adding the EmbedCompatTable macro [2] to MDN pages once API data is available. These two issues cause conversion to be stuck at 20 pages [3].

[2] https://developer.mozilla.org/en-US/docs/Template:EmbedCompatTable
[3] https://browsercompat.herokuapp.com/importer/?converted_compat=2

How are the users identified above solving this problem now?
============================================================
Conversion of pages to BC API data has halted until this issue is resolved

Do you have any suggestions for solving the problem? Please explain in detail.
==============================================================================
Add a UUID field [4] to the kuma Document model [5], called 'external_id', with a default argument of a random v4 UUID [6]. In the build_json_data method [7], add the English page's UUID as and 'external_id' member, and translation's UUIDs to their representation as well.

[4] https://docs.djangoproject.com/en/1.9/ref/models/fields/#uuidfield
[5] https://github.com/mozilla/kuma/blob/master/kuma/wiki/models.py#L174
[6] https://docs.python.org/2/library/uuid.html#uuid.uuid4
[7] https://github.com/mozilla/kuma/blob/master/kuma/wiki/models.py#L567

Is there anything else we should know?
======================================
Once this work is complete, the BC API will adopt the production MDN UUIDs as the UUIDs for features.

This does not include converting MDN pages to use UUIDs as the primary key, which is a non-trivial migration.

Comment 1

[Jannis Leidel [:jezdez]]

I like the plan in general, but the field in the Document model shouldn't be called "external_id" but simply "uuid" or "unique_id" or something to communicate that it's not only useful for external purposes but also for internal references for any future feature development.

Comment 2

[MDN Team (:mdn-dev)]

Commits pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/fc4d3cdbed9e4d067be609cde2c7456dbf7541c5
bug 1246967 - Add Document.uuid to database

Adds a null uuid column to the Document table. This field is intended to
be used as a strong identifier for an MDN page in the BrowserCompat
project.

This migration needs to be applied in production before the
Django models are updated or the field is used. The database default is
null, so that new documents can be created without error. This will be
fixed in future migrations.

https://github.com/mozilla/kuma/commit/22ef9543e256697332380bd4cfe112754aa7cda0
Merge pull request #3793 from mozilla/uuid_step1_1246967

bug 1246967 - Add Document.uuid to database, plus other migrations

r=jezdez

Comment 3

[MDN Team (:mdn-dev)]

Commits pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/4a6411c1f90e22bf4fa3b88e0364162bd3e22903
bug 1246967 - Add Document.uuid to model

The uuid field is intended to be used as a strong identifier for the
BrowserCompat project.

The schema migration will switch from a database-enforced default of null to
a Django-enforced default of a new Version 4 (random) UUID.

https://github.com/mozilla/kuma/commit/0308e4a99a945c041e21588ac20a66188669b15e
bug 1246967 - Refactor Doc*Tests.test_json_data

* Switch from _eq and _ok to asserts (py.test's preference)
* Switch to "assert actual==expected" order (MDN devs' preference)

https://github.com/mozilla/kuma/commit/18b5291bac50a87c50c70e629d452b5fdf6ab6b6
bug 1246967 - Add uuid to $json API

Add the UUID to the $JSON API output

Comment 4

[MDN Team (:mdn-dev)]

Commit pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/9d43d354ef274317304a73baf27a712f2436db93
bug 1246967 - Fix test_json_data_null_uuid

This test was using a test utility (doc_rev) that was removed in a
previous commit (69cf488).

Comment 5

[MDN Team (:mdn-dev)]

Commits pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/3b40a995edbcec6e539c1f772a503216108947c8
bug 1246967 - Populate Document.uuid field

Populate null Document.uuid fields, without updating modification time.

https://github.com/mozilla/kuma/commit/7ffafc4de4a6bf668fd3effcb52245a5286ec157
bug 1246967 - Require Document.uuid

Change Document.uuid from a nullable to a non-nullable field, and simplify
$json API code accordingly.

https://github.com/mozilla/kuma/commit/c70f7f6d95e7df26c0b8d63679e3462287b5bac8
Merge pull request #3795 from mozilla/uuid_step3_1246967

fixes bug 1246967 - Add Document.uuid