From 5dbbc9fb26f5f6bfe90a59e3a4605bceb7bc4ac8 Mon Sep 17 00:00:00 2001 From: Anton Bershanskiy Date: Fri, 15 May 2020 00:35:31 +0300 Subject: [PATCH 1/3] Permissions API permissions descriptions linter - Document existing convention for naming Permissions API permissions - Add linter to enforce this convention - Fix typo in "permissons" caught by linter --- docs/data-guidelines.md | 21 +++++++++++++++++++++ test/linter/test-descriptions.js | 30 ++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) diff --git a/docs/data-guidelines.md b/docs/data-guidelines.md index a018770b83e67c..bac5c21ed83d87 100644 --- a/docs/data-guidelines.md +++ b/docs/data-guidelines.md @@ -120,6 +120,27 @@ For example, the `ImageData` API has worker support, recorded like this: Formerly named `available_in_workers`, this policy was set in [#2362](https://github.com/mdn/browser-compat-data/pull/2362). +### Permissions API permission descriptions (`api.Permissions.*_permission.__compat.description`) + +Document Permissions API permissions called `[permissionname]` as `api.Permissions.[permissionname]_permission` and add a description that reads `"[permissionname] permission"` +For example, the Geolocation permission is named `geolocation_permission` with the description text `geolocation permission`, like this: + +``` +{ + "api": { + "Permissions": { + "__compat": { ... }, + "geolocation_permission": { + "__compat": { + "description": "geolocation permission", + "support": { ... } + } + } + } + } +} +``` + ## Non-functional defined names imply `partial_implementation` If a browser recognizes an API name, but the API doesn’t have any discernable behavior, use `"partial_implementation": true` instead of `"version_added": false`, as if the feature has non-standard support, rather than no support. diff --git a/test/linter/test-descriptions.js b/test/linter/test-descriptions.js index 7ed8e617538765..76e09a22b0f29a 100644 --- a/test/linter/test-descriptions.js +++ b/test/linter/test-descriptions.js @@ -75,6 +75,29 @@ function hasCorrectWebWorkersDescription(apiData, apiName, logger) { } } +/** + * @param {Identifier} apiData + * @param {String} apiName + * @param {Logger} logger + */ +function hasCorrectPermissionDescription(apiData, apiName, logger) { + const expectedDescrition = `${apiName.replace( + '_permission', + '', + )} permission`; + if ( + apiName && + apiName.match('_permission$') && + apiData && + apiData.__compat && + apiData.__compat.description !== expectedDescrition + ) { + logger.error(chalk`{red Incorrect permission description for {bold ${apiName}}} + {yellow Actual: {bold "${apiData.__compat.description || ''}"}} + {green Expected: {bold "${expectedDescrition}"}}`); + } +} + /** * @param {string} filename */ @@ -101,6 +124,13 @@ function testDescriptions(filename) { } } + if (data.api && data.api.Permissions) { + for (const permissionKey in data.api.Permissions) { + const apiData = data.api.Permissions[permissionKey]; + hasCorrectPermissionDescription(apiData, permissionKey, logger); + } + } + if (errors.length) { console.error( chalk`{red Descriptions – {bold ${errors.length}} ${ From 0e095e273453abc917862ad18b4781720033f32c Mon Sep 17 00:00:00 2001 From: Anton Bershanskiy Date: Wed, 20 May 2020 19:46:40 +0300 Subject: [PATCH 2/3] Review feedback --- docs/data-guidelines.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/data-guidelines.md b/docs/data-guidelines.md index bac5c21ed83d87..3cb0d0e9fb0993 100644 --- a/docs/data-guidelines.md +++ b/docs/data-guidelines.md @@ -120,9 +120,10 @@ For example, the `ImageData` API has worker support, recorded like this: Formerly named `available_in_workers`, this policy was set in [#2362](https://github.com/mdn/browser-compat-data/pull/2362). -### Permissions API permission descriptions (`api.Permissions.*_permission.__compat.description`) +## Permissions API permissions (`permissionname_permission`) + +Add [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API) permissions as subfeatures of [`api.Permissions`](https://developer.mozilla.org/en-US/docs/Web/API/Permissions) using the name _permissionname_\_permission with the description text set to `permissionname permission`. -Document Permissions API permissions called `[permissionname]` as `api.Permissions.[permissionname]_permission` and add a description that reads `"[permissionname] permission"` For example, the Geolocation permission is named `geolocation_permission` with the description text `geolocation permission`, like this: ``` @@ -141,6 +142,8 @@ For example, the Geolocation permission is named `geolocation_permission` with t } ``` +This guideline was proposed in [#6156](https://github.com/mdn/browser-compat-data/pull/6156). + ## Non-functional defined names imply `partial_implementation` If a browser recognizes an API name, but the API doesn’t have any discernable behavior, use `"partial_implementation": true` instead of `"version_added": false`, as if the feature has non-standard support, rather than no support. From d25481140165ef6e61164990449166b0ee3c493d Mon Sep 17 00:00:00 2001 From: Anton Bershanskiy Date: Wed, 20 May 2020 19:51:38 +0300 Subject: [PATCH 3/3] Update ToC --- docs/data-guidelines.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/data-guidelines.md b/docs/data-guidelines.md index 3cb0d0e9fb0993..0cc262f49df30a 100644 --- a/docs/data-guidelines.md +++ b/docs/data-guidelines.md @@ -7,6 +7,7 @@ This file contains recommendations to help you record data in a consistent and u - [DOM events (`eventname_event`)](#dom-events-eventname_event) - [Secure context required (`secure_context_required`)](#secure-context-required-secure_context_required) - [Web Workers (`worker_support`)](#web-workers-worker_support) + - [Permissions API permissions (`permissionname_permission`)](#permissions-api-permissions-permissionname_permission) - [Non-functional defined names imply `partial_implementation`](#non-functional-defined-names-imply-partial_implementation) - [Release lines and backported features](#release-lines-and-backported-features) - [Safari for iOS versioning](#safari-for-ios-versioning)