browser-specs - npm Package Compare versions

Comparing version 3.70.0 to 3.70.1

package.json

 {
   "name": "browser-specs",
-  "version": "3.70.0",
+  "version": "3.70.1",
   "description": "Curated list of technical Web specifications that are directly implemented or that will be implemented by Web browsers.",
@@ -5,0 +5,0 @@ "repository": {

README.md

@@ -57,2 +57,3 @@ # Web browser specifications
   - [`source`](#source)
+- [Spec identifiers](#spec-identifiers)
 - [How to add/update/delete a spec](#how-to-addupdatedelete-a-spec)
@@ -140,2 +141,5 @@ - [Versioning](#versioning)<!-- COMMON-TOC: end -->
 
+The URL should be relatively stable but may still change over time. See
+[Spec identifiers](#spec-identifiers) for details.
+
 The `url` property is always set.
@@ -160,2 +164,5 @@
 
+The shortname should be relatively stable but may still change over time. See
+[Spec identifiers](#spec-identifiers) for details.
+
 The `shortname` property is always set.
@@ -468,2 +475,5 @@
 
+The URL should be relatively stable but may still change over time. See
+[Spec identifiers](#spec-identifiers) for details.
+
 The `url` property is always set.
@@ -597,2 +607,3 @@
 - `specref`: information retrieved from [Specref](https://www.specref.org/)
+- `ietf`: information retrieved from the [IETF datatracker](https://datatracker.ietf.org)
 - `spec`: information retrieved from the spec itself
@@ -603,2 +614,52 @@
 
+## Spec identifiers
+
+An entry in browser-specs contains properties that can be viewed as
+identifiers: [`shortname`](#shortname), [`url`](#url), and
+[`nightly.url`](#nightlyurl). Please note that these identifiers are not fully
+stable.
+
+The `shortname` property should remain mostly stable over time. The `shortname`
+may still change though, for instance when a W3C specification starts being
+published as a TR document with a shortname that is different from the one used
+during incubation, or when an IETF specification gets published as an RFC.
+Starting in July 2023, when the `shortname` of a specification changes in
+browser-specs, the previous `shortname` gets added to a
+[`formerNames`](#formernames) property. This makes it possible to track a
+specification entry over time in browser-specs.
+
+The `url` property contains a URL of the specification that can be regarded as
+canonical and mostly stable too, but that URL will typically change when a
+specification starts getting published as a formal technical document, or when
+a specification transitions from one organization or group to another one.
+
+The `nightly.url` property is the least stable identifier of a specification.
+That URL may be under the control of an individual or group, who may decide to
+change the URL at any time. Or it may be affected by a change of status. For
+instance, the `nightly.url` property will change when a W3C spec incubated in
+the Web Platform Incubator Community Group (WICG) transitions to a Working
+Group, or when a new version of an IETF draft gets published.
+
+If your project tracks specifications over time and relies on browser-specs to
+gather information about these specifications, you will need to record the
+`shortname` of the specifications you're tracking, and apply the following
+algorithm to find the relevant specification entry in browser-specs:
+
+1. Look for an entry in browser-specs whose `shortname` matches the recorded
+shortname. If one is found, that is the relevant specification entry.
+2. Look for entries in browser-specs that have the recorded shortname in its
+`formerNames` property. If one is found, that is the relevant specification
+entry.
+3. If you found more than one entry in the previous step, that looks like a bug
+in browser-specs, please [raise an
+issue](https://github.com/w3c/browser-specs/issues/new).
+3. If you're still looking for a relevant specification entry at this point
+whereas the recorded shortname used to exist in browser-specs, that looks like
+a bug in browser-specs too, please [raise an
+issue](https://github.com/w3c/browser-specs/issues/new).
+
+Shortname changes may occur in major and minor releases of npm packages but not
+in patch releases.
+
+
 ## How to add/update/delete a spec
@@ -605,0 +666,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Number of lines in readme file

741

increased by8.97%

Worsened metrics

Total package byte prevSize

718235

decreased by-0.79%

Lines of code

22577

decreased by-1.22%

No dependency changes