Skip to content

EditingHelp

Jump to bottom
Joe Medley edited this page Feb 24, 2022 · 15 revisions

This page provides detailed help and examples of how to fill in individual fields of feature entries.

General guidance

  • Look for ways to simplify your language. You have a limited amount of space. Reducing wordiness in a single idea will give you more space or ideas. Say 'implementing' instead of 'working to implement'. Say 'many' instead of 'an enormous number'.

  • Be specific. If you're adding a method or property, call it a method or property, not an API.

Feature name

Each feature should have a unique name that is written as a noun phrase.

  • Capitalize only the first letter and the beginnings of proper nouns.
  • Avoid using verbs such as "add", "enhance", "deprecate", or "delete". Instead, simply name the feature itself and use the feature type and stage fields to indicate the intent of change.
  • Do not include markup or markdown.
  • Write keywords and identifiers as they would appear to a web developer, not as they are in source code. For example, a method implemented as NewInterface#dostuff would be written as in JavaScript: NewInterface.doStuff().

Example

  • Conversion Measurement API
  • CSS Flexbox: New intrinsic size algorithm
  • Permissions-Policy header

Summary

Provide a one sentence description followed by one or two lines explaining how this feature works and how it helps web developers.

Note: This text communicates with more than just the rest of Chromium development. It's the part most visible to external readers and is used as the basis for the text in the beta release posts.

  • Write from a web developer's point of view, not a browser developer's.
  • Do not use markup or markdown.
  • Do not use hard or soft returns.
  • Avoid phrases such as "a new feature". Every feature on the site was new when it was created. You don't need to repeat that information.
  • The first line should be a sentence fragment beginning with a verb. (See below.) This is the rare exception to the requirement to always use complete sentences.
  • "Conformance with spec" is not adequate. Most if not all features are in conformance to spec.

Example

Splits the HTTP cache using the top frame origin (and possibly subframe origin) to prevent documents from one origin from knowing whether a resource from another origin was cached. The HTTP cache is currently one per profile, with a single namespace for all resources and subresources regardless of origin or renderer process. Splitting the cache on top frame origins helps the browser deflect side-channel attacks where one site can detect resources in another site’s cache.

Motivation

Provide a short explanation of the motivation for this feature.

  • Do not use markup or markdown.

Example

Cache attacks can lead to the following leaks:

Detect if a user has visited a specific site: If the cached resource is specific to a particular site or to a particular cohort of sites, an adversary can detect user’s browsing history by checking if the cache has that resource.

Cross-site search attack: There exist cross site search attack proofs-of-concept which exploit the fact that some popular sites load a specific image when a search result is empty. By opening a tab and performing a search and then checking for that image in the cache, an adversary can detect if an arbitrary string is in the user’s search results.

Clone this wiki locally