Repository navigation
Conversation
03a510f to
8221150
Compare
8221150 to
712274a
Compare
|
Thanks for putting this together @xeenon !! In general there seem to be two major potentially unavoidable concerns with the conventions.
|
|
Thanks, @carlosjeurissen. On the second point: a value shared by the manifest and an API is the awkward case, and The reason for kebab-case is the W3C style for web APIs, which asks for lowercase, dash-delimited enum values. That was the main driver in #563. I also counted enum values in the JS APIs and Aligning manifest keys and values with the API style is something I would like to see, but that is a larger change for a future manifest version. |
|
@xeenon thanks for the added context! In that case I would be in favor of also using kebab-case for future web extension enums in manifest files even if this is different than what we do with RunAt. |
FWIW
What about |
| |---|---|---| | ||
| | Namespace | camelCase | `declarativeNetRequest` | | ||
| | Method | camelCase, verb first | `getRecentlyClosed()` | | ||
| | Event | `on` followed by camelCase | `onVisitRemoved` | |
There was a problem hiding this comment.
Nitpicky nitpick:
Strictly speaking it is "camelCase" starting with "on".
(Or "on" followed by PascalCase)
| | Constant | SCREAMING_SNAKE_CASE | `TAB_ID_NONE` | | ||
| | Enum value | kebab-case | `"per-origin"` | | ||
| | Manifest key | snake_case | `"default_title"` | | ||
| | Manifest enum value | snake_case | `"document_idle"` | |
There was a problem hiding this comment.
| | Manifest enum value | snake_case | `"document_idle"` | | |
| | Manifest enum value | kebab-case | `"no-repeat"` | |
The web app manifests also use kebab-case for enums in the manifest. Aligning with them seems to make sense.
carlosjeurissen
left a comment
There was a problem hiding this comment.
Very much in favor of using kebab-case for manifest enum values. This will align us with the web app manifest spec and would align with the JS APIs.
|
kebab-case in manifest sounds like a breaking change for MV4+. |
|
@tophf the point of writing these conventions is to be applied for new enums. We still have to discuss how to migrate existing enums to properly formatted/cased enums. Supporting both could be something browsers could offer on a very short notice. While actually removing support for non kebab-case values should indeed only happen in mv4+ in my opinion. |
|
Mixing of different conventions in one scope is not a consistent API design. We already suffered Chromium-imposed SCREAMING_CASE inside values under a specious argument that it helps unification while actually it only added more fragmentation, but that's what MV3 ended up doing globally anyway, so ironically there is internal consistency. Thing is, if your extension wants to run in older versions of Chromium you are stuck with those SUDDENLY_SCREAMING values in manifest.json. |
…est. Cover the casing of namespaces, methods, events, properties, types, constants, enum values, manifest keys and manifest enum values, how acronyms are written, and how a property that is in both the manifest and an API is named.
|
@carlosjeurissen @tophf thanks, both of you. The goal of this document is to write down what we largely agree on for new APIs, without a drastic departure from what is implemented today. The main thing I want to avoid is new SCREAMING_CASE values being introduced, as tophf describes, and the document does that either way. For manifest enum values I would keep snake_case for now, because it matches the values already in the manifest ( I agree this should be revisited for a v4 with a holistic view of backwards compatibility. Browsers could normalize automatically so that old and new spellings both load, while enforcing one consistent style going forward. Safari already does a little of this. It accepts |
712274a to
3c3baf9
Compare
Fills in
docs/api-conventions.mdwith the naming conventions agreed in #563 and extends them to methods, properties and manifest keys. The method and property rules come from the casing that existing APIs already use.It covers:
IDstaysIdto matchtabId,windowIdandframeId.action.setIcon({ variants }).css_originandcssOrigin,color_schemesandcolorSchemes).The conventions apply to future additions. Existing names are not changed.
Closes #563