diff options
Diffstat (limited to 'chromium/docs/website/site/blink')
92 files changed, 0 insertions, 7653 deletions
diff --git a/chromium/docs/website/site/blink/activedomobject/index.md b/chromium/docs/website/site/blink/activedomobject/index.md deleted file mode 100644 index 0a3950ac445..00000000000 --- a/chromium/docs/website/site/blink/activedomobject/index.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: activedomobject -title: ActiveDOMObject ---- - -**DRAFT. NEEDS REVIEW** - -The ActiveDOMObject is used to implement DOM objects that can involve -asynchronous operations such as loading data from network (e.g. XMLHttpRequest, -WebSocket) to - -* keep them alive while async op is active -* hold back actions resulting from async op while the document is - suspended - -The ActiveDOMObject classes can override its hasPendingActivity() method to keep -the object alive while some async operation is in progress. As long as -hasPendingActivity() returns true, V8 prolongs its life so that it doesn't get -garbage collected even when it becomes unreachable. Note that there must be a V8 -wrapper for the object in order to this to work. - -While hasPendingActivity() returns true, the life of the parent Document object -is also prolonged (explanation TBA). You rarely need to override -contextDestroyed() for ActiveDOMObject subclasses. - -ActiveDOMObjects are notified of detach of the parent Document object (or -shutdown of the parent WorkerThread) as the stop() method called on it. -Commonly, they start shutdown of the asynchronous operation in stop() if any. -This detach occurs regardless of hasPendingActivity(). - -suspend() is called when dialogs such as alert(), prompt(), etc. are going to be -shown or the WebInspector's pause is going to be active. resume() is called when -the dialog is closed or the WebInspector resumes script execution. Between -suspend() and resume(), it's recommended that operations on the ActiveDOMObjects -are suspended. Since resource loading is automatically suspended by Chrome's -resource dispatched code, you may not need to manually hold back async method -calls. - -When implementing, it is critical that you also add ActiveDOMObject to the -interface flags in your IDL file, or GC will pay no attention to -hasPendingActivity()! - -As of Nov 12 2013 by tyoshino@. Updated July 17, 2014 by kouhei@ - -Thanks haraken@, abarth@
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/blink-api-owners-requirements/index.md b/chromium/docs/website/site/blink/blink-api-owners-requirements/index.md deleted file mode 100644 index cd1147cda83..00000000000 --- a/chromium/docs/website/site/blink/blink-api-owners-requirements/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: blink-api-owners-requirements -title: Blink API OWNERS Requirements ---- - -## [Moved here](/blink/guidelines/api-owners/requirements)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/blink-gardening/index.md b/chromium/docs/website/site/blink/blink-gardening/index.md deleted file mode 100644 index b2e1660ff2b..00000000000 --- a/chromium/docs/website/site/blink/blink-gardening/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: blink-gardening -title: Blink gardening ---- - -This page has moved (there's no more Blink gardening!). See [Handling Blink -failures](/blink/sheriffing)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/blink-gc/index.md b/chromium/docs/website/site/blink/blink-gc/index.md deleted file mode 100644 index 871984b9e60..00000000000 --- a/chromium/docs/website/site/blink/blink-gc/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: blink-gc -title: Garbage Collection for Blink C++ objects (a.k.a. Oilpan) ---- - -This documentation was moved to -<https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/platform/heap/BlinkGCAPIReference.md>.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/blink-in-js/index.md b/chromium/docs/website/site/blink/blink-in-js/index.md deleted file mode 100644 index 11411b08519..00000000000 --- a/chromium/docs/website/site/blink/blink-in-js/index.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: blink-in-js -title: Blink-in-JavaScript ---- - -## NOTE: THIS DOCUMENT IS NO LONGER VALID - -## It is left available out of historical interest. - -## Overview - -***Blink-in-JavaScript*** is a mechanism to enable Blink developers to implement -DOM features in JavaScript (instead of C++). The goal of Blink-in-JS is to -improve web layering by implementing high-level DOM features on top of existing -web-exposed APIs. You can learn the design in [this design -document](https://docs.google.com/a/google.com/document/d/13cT9Klgvt_ciAR3ONGvzKvw6fz9-f6E0FrqYFqfoc8Y/edit#) -and [this -slide](https://docs.google.com/a/google.com/presentation/d/1XvZdAF29Fgn19GCjDhHhlsECJAfOR49tpUFWrbtQAwU/edit#slide=id.g3840fe06e_00). -If you are interested in the security model, you can also look at [this -document](https://docs.google.com/a/google.com/document/d/1AtnKpzQaSY3Mo1qTm68mt_3DkcZzrp_jcGS92a3a1UU/edit). - -## Guideline - -When you want to implement a feature in Blink-in-JS, you need to follow the -following guideline. - -1. If you plan to implement a feature in Blink-in-JS, you need to send - an Intent-to-Implement to blink-dev@. The Intent-to-Implement should - explain the advantages of the Blink-in-JS and have a list of private - script APIs that will be required for the Blink-in-JS. (\*\*) -2. You are strongly discouraged to use private script APIs. If you need - to add a private script API, you need to provide a justification for - the API and get an LGTM from one API owner (\*\*\*). The API must - meet either of the following conditions: - - * The API is a missing part of the current web and going to be - exposed to the web in the future. - * The API is for supporting a will-be-deprecated feature. - -(\*) See [this -slide](https://docs.google.com/a/chromium.org/presentation/d/1-5wpqeIltM40DAZdQBhbqnzOZuFNezS4eUfx1T4YV50/edit#slide=id.g437b0e633_00) -for a background of this guideline. - -(\*\*) The fact that we’re lowering the priority of Blink-in-JS means that we -are going to be conservative about accepting your Intent-to-Implement. It is -important to consider if your Blink-in-JS work has higher impact than other -projects you could work on alternately. The Intent-to-Implement must provide -clear advantages of why you think it is important for Blink to implement the -feature in Blink-in-JS. For example, the following Intent-to-Implements look -appealing: - -* I need to implement MediaControls for Android. There are two options - for us: implement it in C++ or implement it in JS. Given that - MediaControls is a self-contained and high-level feature that can be - developed on top of existing web-exposed API, I propose to implement - MediaControls in Blink-in-JS. It is easier to develop and maintain. -* XMLViewer is already written in JS and it is invoked using direct V8 - APIs. Given that Blink-in-JS has a safer mechanism to run JS in - Blink, I propose to move XMLViewer to Blink-in-JS. -* I plan to make a substantial restructuring of the rendering system - for performance. I noticed that marquee-specific code in the - rendering system prevents us from making the restructuring. Given - that marquee is an out-dated feature, I want to just factor out the - implementation to Blink-in-JS instead of supporting the - marquee-specific code in the new rendering system. - -On the other hand, the following Intent-to-Implement would not be appealing: - -* HTMLFormControls are self-contained and it is not hard to move the - implementation to Blink-in-JS. The benefit is that we can remove a - bunch of code from C++. However, I’m not sure if HTMLFormControls is - an actively developed area and thus it’s not clear at this point how - helpful it is for on-going Blink projects. - -(Note: These are just examples and not intending to imply go or non-go of -MediaControls-in-JS etc) - -(\*\*\*) It is a good idea to ask review for dglazkov@ (API owner), jochen@ (API -owner), haraken@ and area experts of the API. - -## Basics - -The most common usage of Blink-in-JS is to implement DOM features defined in an -IDL file in JavaScript. For example, consider to implement a <marquee> tag -in Blink-in-JS. - -In this case, what you need to do is just to: - -* Add \[ImplementedInPrivateScript\] IDL extended attributes to DOM - attributes/methods in an IDL file. -* Implement the DOM attributes/methods in JavaScript (This JavaScript - file is called a ***private script***.) - -Specifically, you first need to add \[ImplementedInPrivateScript\] IDL extended -attributes to DOM attributes/methods in -[HTMLMarqueeElement.idl](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/core/html/HTMLMarqueeElement.idl&q=htmlmarqueeelement.idl&sq=package:chromium&type=cs). - -```none -interface HTMLMarqueeElement : HTMLElement { - [ImplementedInPrivateScript] void start(); - [ImplementedInPrivateScript] void stop(); - [ImplementedInPrivateScript] attribute long loop; - [ImplementedInPrivateScript] attribute long scrollAmount; - ...; -}; -``` - -Second, you need to implement the DOM attributes/methods in -[HTMLMarqueeElement.js](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/core/html/HTMLMarqueeElement.js&sq=package:chromium&type=cs). - -```none -installClass("HTMLMarqueeElement", function(HTMLMarqueeElementPrototype)) { - HTMLMarqueeElementPrototype.start = function() { - // Implement the start() method. - // |this| object is equal to the wrapper of the <marquee> element. - } - Object.defineProperty(HTMLMarqueeElementPrototype, 'loop', { - get: function() { - // Implement the getter of the loop attribute. - // |this| object is equal to the wrapper of the <marquee> element. - }, - set: function(value) { - // Implement the setter of the loop attribute. - // |this| object is equal to the wrapper of the <marquee> element. - }, - }); - ...; // Implement other DOM attributes/methods. -}; -``` - -That's it. Then the IDL compiler auto-generates the binding code that connects -user's script with the JavaScript functions defined in the private script. - -The important points are as follows: - -* A private script runs in a dedicated isolated world. For security - reasons, no JavaScript objects nor DOM wrappers are shared between - the private script and user's script. This restriction is needed to - prevent the private script from leaking confidential information to - user's script. -* To force the restriction, the type of arguments you can pass from - user's script to the private script is limited to JavaScript - primitive types (e.g., int, double, string, boolean etc) and DOM - wrappers. Similarly, the type you can return from the private script - back to user's script is limited to JavaScript primitive types and - DOM wrappers. You cannot pass JavaScript functions, JavaScript - objects, Promises etc. -* |global| is a window object of the private script. You can use the - |global| object as you like, but note that the |global| object is - shared among all private scripts. For example, HTMLMarqueeElement.js - and XSLT.js share the same |global| object. Thus you should not - cache data specific to your private script onto the |global| object. -* |HTMLMarqueeElementPrototype| is a prototype object of the private - script. Your main work is to define DOM attributes/methods on the - prototype object. -* |this| object is equal to the wrapper of the <marquee> element - in the isolated world for private scripts. Due to the security - isolation, |this| object is a different wrapper from the wrapper of - the <marquee> element in the main world. You can cache - whatever you want onto the |this| object. It is guaranteed that the - |this| object is not accessible from user's script. - - By default, the IDL compiler assumes that you have HTMLMarqueeElement.h in - Blink. If you don't want to have HTMLMarqueeElement.h, you need to add - \[NoImplHeader\] IDL attribute on the interface. - -* |this| object has the following prototype chain: |this| --> - HTMLMarqueeElementPrototype --> HTMLMarqueeElement.prototype - --> HTMLElement.prototype --> Element.prototype --> - Node.prototype --> .... - -For more details, you can look at how -[HTMLMarqueeElement.js](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/core/html/HTMLMarqueeElement.js&sq=package:chromium&type=cs) -and -[PrivateScriptTest.js](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/core/testing/PrivateScriptTest.js&q=privatescripttest.js&sq=package:chromium&type=cs) -are implemented. - -## Details - -By using the \[ImplementedInPrivateScript\] IDL extended attribute, you can -implement DOM features exposed to the web in a private script. However, this is -sometimes not sufficient to implement real-world DOM features in a private -script. Sometimes you will need to invoke a private script from C++. Sometimes -you will need to implement internal DOM attributes/methods that are only exposed -to private scripts. - -In general, Blink-in-JS supports the following four kinds of APIs. - -* \[user's script & private script => C++\]: This is a normal DOM - attribute/method (where Blink-in-JS is not involved). The DOM - attribute/method is implemented in C++, and the DOM attribute/method - is exposed to both user's script and private scripts. -* \[user's script & private script => private script\]: This is the - most common usage of Blink-in-JS explained above. The DOM - attribute/method is implemented in a private script, and the DOM - attribute/method is exposed to both user's script and private - scripts. -* \[private script => C++\]: This is an "internal" DOM - attribute/method for private scripts. The DOM attribute/method is - implemented in C++, and the DOM attribute/method is exposed only to - private scripts (not exposed to user's script). -* \[C++ => private script\]: This is a way to invoke a private - script from C++. The DOM attribute/method is implemented in a - private script, and a C++ static function is provided to invoke the - DOM attribute/method so that Blink can use it wherever it wants. - -You can control the kind of each API by combining the -\[ImplementedInPrivateScript\] IDL extended attribute and -\[OnlyExposedToPrivateScript\] IDL attribute. - -* \[user's script & private script => C++\]: Use no IDL extended - attributes. -* \[user's script & private script => private script\]: Use - \[ImplementedInPrivateScript\]. -* \[private script => C++\]: Use \[OnlyExposedToPrivateScript\]. -* \[C++ => private script\]: Use \[ImplementedInPrivateScript, - OnlyExposedToPrivateScript\]. - -Here is an example: - -```none -interface XXX { - void f1(); // Normal DOM method implemented in C++; exposed to user's script and private scripts. - [ImplementedInPrivateScript] void f2(); // DOM method implemented in a private script; exposed to user's script and private scripts. - [OnlyExposedToPrivateScript] void f3(); // DOM method implemented in C++; exposed only to private scripts. - [ImplementedInPrivateScript, OnlyExposedToPrivateScript] void f4(); // DOM method implemented in a private script; V8XXX::PrivateScript::f4Method() is provided as a static method so that Blink can invoke the private script. -}; -``` - -For more details, see test cases in -[PrivateScriptTest.idl](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/core/testing/PrivateScriptTest.idl&sq=package:chromium&type=cs). - -DOM attributes/methods that have \[OnlyExposedToPrivateScript\] IDL attribute -are "backdoors". **Backdoors are strongly discouraged** unless you are certain -that the backdoors are APIs that are missing in the current web platform and -should be exposed to the web in the future. Ideally Blink-in-JS should be -implemented only by using existing web platform APIs. The only case where -backdoors are allowed is a case where we think that the API is a missing part of -the current web platform and should be exposed to the web in the future. (One of -the goals of Blink-in-JS is to understand what APIs are missing in the web -platform by trying to implement built-in contents of Blink in JavaScript.) - -## Where Your Private Script lives? - -Your private script lives in `blink_resources.pak` in -`out/*config*/gen/blink/public/resources/`, which is generated by -[`blink_resouces.gyp`](https://chromium.googlesource.com/chromium/blink/+/HEAD/public/blink_resources.gyp), -then it repacked into `content_shell.pak`, `resources.pak` and so. - -So, you need to do following steps putting your private script into resource -file: - -1. Change - [`blink_resources.grd`](https://chromium.googlesource.com/chromium/blink/+/HEAD/public/blink_resources.grd) - in Blink repository to include your private script, e.g. - [crrev/570863002](http://crrev.com/570863002) - * Since we also need to change file in Chromium repository, I - recommend to create dummy file and check-in this before - reviewing your private script. -2. Change - [`content/child/blink_platform_impl.cc`](https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/blink_platform_impl.cc) - in Chromium repository, e.g. - [crrev/556793006](http://crrev.com/556793006) - * **You should wait step #1 blink change is rolled into Chromium - rather than landed into blink repository.** - -Note: Due to [crbug/415908](http://crbug.com/415908), blink_resources.pak isn't -rebuild when your private script file changed. You may want to remove it, -`out/Debug/gen/blink/public/resources/blink_resources.pak`. - -## Contacts - -If you have any questions or comments, feel to free to ask haraken@. I'm -planning to factor out more things from C++ to Blink-in-JS to improve the -hackability of the Blink core. Your contributions are super welcome!
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/blink-network-stack/index.md b/chromium/docs/website/site/blink/blink-network-stack/index.md deleted file mode 100644 index eaa496cbd9b..00000000000 --- a/chromium/docs/website/site/blink/blink-network-stack/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: blink-network-stack -title: Blink Networking APIs ---- - -> [See here for Chromium Network Stack team -> info](/developers/design-documents/network-stack) - -> <https://docs.google.com/document/d/1PN8RN9NESiOtVzMWZf1f94H85Nf6Sfs9Lc9xgAsjVsU/edit> - -> #### Blink Networking APIs
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/blink-post-merge-faq/index.md b/chromium/docs/website/site/blink/blink-post-merge-faq/index.md deleted file mode 100644 index c8ca2aa4e0c..00000000000 --- a/chromium/docs/website/site/blink/blink-post-merge-faq/index.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: blink-post-merge-faq -title: Blink post-merge FAQ ---- - -## Merge versions - -**Pre-merge:** - -> Blink git SHA: -> [37d233bde3baaea720a9a81296fa77b63c9d8981](https://chromium.googlesource.com/chromium/blink/+/HEAD) - -> Blink revision: **[202666](http://blinkrev.hasb.ug/202666)** - -> Chromium git SHA: -> [70aa692d68ee86d365928edd160c3575fda2b453](https://chromium.googlesource.com/chromium/src/+/70aa692d68ee86d365928edd160c3575fda2b453) -> [350323](http://crrev.com/350323) Chromium revision: -> Chrome version: -> [47.0.2518.0](https://chromium.googlesource.com/chromium/src/+/70aa692d68ee86d365928edd160c3575fda2b453/chrome/VERSION) - -**Post-merge:** - -> Blink git SHA: *n/a* - -> Blink revision: *n/a* - -> Chromium git SHA: -> [b59b6df51a249895fbba24f92b661f744e031546](https://chromium.googlesource.com/chromium/src/+/b59b6df51a249895fbba24f92b661f744e031546) - -> Chromium revision: **[350324](http://crrev.com/350324)** - -> Chrome version: -> [47.0.2519.0](https://chromium.googlesource.com/chromium/src/+/341be68a2f3f424685a709aacc683d227f0de7eb) -> -- version bump came 1 day after -> [branch](https://chromium.googlesource.com/chromium/src/+/b59b6df51a249895fbba24f92b661f744e031546/chrome/VERSION) - -## How to migrate local /src (chromium main project) branches - -* ## Only once to update the remote - - ## ```none - git remote update (or git fetch) - ``` - - ## `For each branch` - - ## ```none - git rebase $(git merge-base branch_name origin/master) branch_name --onto origin/master - ``` - -## How to migrate local /src/third_party/WebKit branches - -When running gclient sync after the merge point, the previous .git directory -(containing all the local branches) for blink will be saved in -//src/../old_src_third_party_WebKit.git - -For each local branch, run the following steps: - -* Create a patch file - - ```none - git diff origin/master...branch_name > /tmp/old-blink.patch - ``` - -And then in the new checkout, after the branch point - -* Recreate the branch - - ```none - git new-branch old-blink - ``` - -* Apply the patch - - ```none - git apply -3 --directory third_party/WebKit/ /tmp/old-blink.patch - ``` - -## How to migrate blink patches from Rietveld - -If you have the patch locally as a git branch, migrating that would be easier. -Otherwise, follow these steps: - -1. Download the raw patch from codereview.chomium.org/123456 -2. Create a new local git branch in a post-merge checkout - - ```none - git new-branch issue123456 - ``` - -3. Apply the patch - - ```none - git apply -3 --directory third_party/WebKit/ issue123456_1001.diff - ``` - -4. Add new files and commit changes -5. Upload to a new CL - -## How can I avoid getting the entire Blink history when going over the merge commit - -If you use `git log` or similar over the merge commit, use `--first-parent` to -walk up only in the chromium history. - -## Cherry-picking a Blink CL to a release branch - -The active releases branches will be merged (i.e. won't have a -third_party/WebKit subproject) as well. - -For CL that get landed after the merge day, it won't be any different than -cherry-picking a chromium CL. Just follow the -[git-drover](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/git-drover.html) -man page. - -To cherry-pick a blink CL that was landed before the merge day: - -* Find the corresponding commit that you want to cherry-pick in the - chromium master and note its SHA1 (note: it will have a different - SHA1 than what reported in the codereview.chromium.org/NNNN) - e.g., if you want to cherry-pick - <https://codereview.chromium.org/1340403003> - - ```none - git log origin/master --grep codereview.chromium.org/1340403003 -- third_party/WebKit - commit c614d6deae3c6e4cc0bfbb60bb15a17305b418b7 - Author: .... - ``` - -* Follow the - [git-drover](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/git-drover.html) - documentation using SHA1 above when doing git cherry-pick -x - -## Creating a checkout using fetch blink does no longer work - -Use `fetch chromium` instead. - -## Converting revision range links from SVN to git - -See [this document -](https://docs.google.com/document/d/1v2fTiNF2FNzbSZXuF1JQxT3UHghM9GUI5csWIpSdu68/edit)for -instructions. - -## Bisecting across the merge point - -* Bisect scripts (src/tools/bisect-builds.py) and bots should Just - Work TM. File a bug if that is not the case. -* Doing a git bisect on a revision range that includes the merge point - requires a little trick. (See [\[chromium-dev\] Merge of Chromium - and Blink repositories - git bisect is - broken?](https://groups.google.com/a/chromium.org/forum/#!topic/chromium-dev/ydCRw4V6u5o) - for context and details) -* The trick consists in convincing git that the merge commit - (b59b6df51) did NOT pull in the blink history (70aa692d6) using - grafts - - ```none - git replace --graft b59b6df51 70aa692d6 - # Do the git bisect as usual - git bisect start GOOD_SHA1 BAD_SHA1 - # Remove the grafts at the end - $ git replace -d b59b6df51 - ``` diff --git a/chromium/docs/website/site/blink/blink-testing-and-the-w3c/index.md b/chromium/docs/website/site/blink/blink-testing-and-the-w3c/index.md deleted file mode 100644 index f302488b4b0..00000000000 --- a/chromium/docs/website/site/blink/blink-testing-and-the-w3c/index.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: blink-testing-and-the-w3c -title: Blink, Testing, and the W3C ---- - -*Blink is currently running a subset of the W3C's tests automatically, as -documented in [Importing the W3C tests to Blink](/blink/importing-the-w3c-tests) -.* - -*This document is left here for historical purposes and to document some of the design and process tradeoffs involved.* - -> *Document owner: [dpranke@chromium.org](mailto:dpranke@chromium.org)* - -## Overview - -The W3C has defined a large number of tests used for conformance testing. - -Blink has inherited from WebKit a large number of tests that are used for -regression testing. Many of these tests (mostly the so-called "pixel tests") -require manual verification of correctness and take a fair amount of work to -keep these tests up-to-date. Many are also not written in a way that can be -easily used by other browser vendors. - -Blink does not currently (4/2013) regularly import and run the W3C's tests, but -we have done some ad-hoc partial imports of test suites in the past into our -existing regression test suites. Some of these previously imported W3C tests are -therefore out of date and/or redundant. - -The Blink team [has stated](/blink/#testing) that any new features being -developed should be accompanied by conformance tests and that we should be -working with the W3C on these tests. We believe that having a comprehensive, -vendor-neutral set of tests for the web platform is good for the web as a whole. - -Thus, there are several interrelated problems: - - *The W3C has a lot of tests that aren't being run regularly (by us, at - least).* - - *We have redundant and/or out of date tests.* - - *We have a lot of tests that are hard to maintain.* - - *We have a lot of tests we could potentially share with the W3C.* - - *We do not have a great sense of the coverage of either or both sets of - tests.* - - *Neither we nor the W3C have smoothly running development processes to make - these two sets of tests converge where possible.* - -I will also note that although I used the words "conformance" and "regression" -above, they don't necessarily mean much difference in practice. You can, and -probably should, use conformance tests for regression testing. - -## Ideal state - -We should work together with the W3C to resolve these problems as much as -possible. The ideal end state might look something like: - - *All of the W3C’s tests would be in a single location or repository, clearly - organized by some scheme that identified which features each test targeted, - and what the state of the test was (submitted, accepted/approved, etc.)* - - *There would be some sort of process for minimizing or eliminating redundant - tests.* - - *The test suite coverage would be comprehensive, and portable (it would be - well understood how to write tests that ran in the major browsers).* - - *The processes for submitting new tests, getting changes made to existing - tests, and downloading the latest test suites and integrating them into our - builds would be well defined and practiced.* - - *The tests could be run and evaluated automatically (i.e., tests would not - require manual review to see if you passed or failed).* - - *The number of chromium-/blink- specific layout tests would be kept to a - minimum; if the test suites were comprehensive, arguably we’d have little - need for custom tests except for features that weren’t standards-track. We - would have a well-polished process for removing our tests when they were - made redundant.* - -## Current state - -Today, as I currently understand it, none of these things are true, although -some are closer than others. Item-by-item: - - *Tests are scattered across multiple locations.* - - **Most of them can be found somewhere on the W3C’s mercurial repository - (dvcs.w3.org/hg), and are mirrored to w3c-test.org .** - - **Some tests are also being moved to Github. The W3C has claimed a goal - of moving everything to Github by the end of 2013.** - - **Different WGs follow different naming conventions, although I think - things are fairly consistent for newer tests.** - - *I have no idea how people figure out if there are redundant tests in the - W3C suites. My guess is that reviewers and spec editors make their best - efforts here.* - - *I have no real idea how comprehensive the existing test suites are, nor how - many of them run on Blink as-is (let alone pass).* - - **At a rough guess, there’s somewhere between 13,000 and 18,000 existing - tests in various stages of approval.** - - **I don’t yet really know how many reftests really are portable and - aren’t subject to diffs resulting from rounding errors and other things - that don’t really affect correctness.** - - **On a related note, it’s hard to say how many of the tests are “good”, - in the sense that they are maintainable, clear, focused, fast, etc.** - - *I think the processes for submitting new tests are roughly defined for most - groups at this point, but I don’t know how broadly shared they are between - WGs. We in Blink are at least not very familiar with the processes.* - - *Many of the older tests (e.g., CSS1, CSS2.1) were written assuming someone - would look at them individually to decide if they were passing.* - - **We currently run those as pixel tests, but it would be difficult to - say with confidence how many of them we were “passing” (due to the way - Blink manages passing vs. expected results).** - - **There may be some tests that require interactive (manual) execution, - as well as manual review. I don’t know if we are interested in them at - all (I’m not, personally).** - - *I have no idea how many of our existing regression tests are redundant, nor - how many of them could be reused by other vendors.* - -**Work items** - -So, this leaves us with the following (unprioritized) set of potential work -items: - - *Pull all of the existing tests down and see:* - - **How many of them we already have?** - - **How many of them are ref tests or are otherwise self-contained (i.e., - we don’t need to generate -expected results separately and review them - for correctness)?** - - **What sort of coverage do we have? How much overlap with existing Blink - tests do we have?** - - **How well do they integrate into the existing harnesses we have?** - - *Help organize the W3C repos.* - - *Work on tools and processes for submitting new tests, getting tests - approved, and pulling them down to run, etc.* - - *Work to identify areas missing coverage.* - - *Work to write tests for those areas.* - - *Formalize tracking the test suites for new features we’re working on and - ensuring the test suites are accepted (I think we do this today in a fairly - ad-hoc and informal way). We should at least be regularly running our own - tests!* - - *Work on the w3c’s test harness and figure out if it needs more features to - be able to get better test coverage and/or work more portably.* - - *Publish our test results regularly somehow.* - - *Perhaps help publish the results of other implementations (Helping to build - a common dashboard or something; presumably we don’t want to be publishing - the results from other vendors ourselves).* - -This is all a fair amount of work, but there are too many unknowns to be able to -really give a resource estimate (at least I wouldn’t want to). - -## Q2 2013 goals - -We on Blink have a Q2 2013 goal of at least the following: - - *Develop tools to import some of the larger test suites from the W3C, if not - all of them. (with some [help from - Adobe](https://lists.webkit.org/pipermail/webkit-dev/2013-March/024055.html))* - - *Import and run the tests in an automated manner as part of our existing - regression testing processes (the layout tests). This will not include any - tests requiring manual verification of correctness (i.e., no tests requiring - new platform-specific baselines).* - - *Provide at least an initial set of feedback to the W3C on what did and - didn't work (including which tests are and aren't passing), including - enhancement requests for their infrastructure and processes if we find our - needs aren't currently met.* - -This should give us a pretty good sense of where we're at and how much work the -remaining open problems may be. - -Note that if we get this working smoothly, we can hopefully extend these -processes to other standards bodies as need be (ECMA, Khronos, etc.)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/blink-triaging/index.md b/chromium/docs/website/site/blink/blink-triaging/index.md deleted file mode 100644 index 07bd8f4ed41..00000000000 --- a/chromium/docs/website/site/blink/blink-triaging/index.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: blink-triaging -title: Component:Blink bug labeling rotation ---- - -[Document with tips for bug -labeling](https://docs.google.com/document/d/1l9XehKEHAJu3-LnWDdXl8-t-8rz9dk8dy1bEI4zzUOU/edit) - -## [Mapping of labels to owners and teams](https://docs.google.com/spreadsheets/d/19JEFMvsxD3eThyGiJRqAjcpx362LHUDdVzICAg7TYZA/edit#gid=0) - -## Goal - -Deliver Blink bugs in crbug.com to engineers who are responsible for the bug -area by adding Blink>*Foo* components. - -## Example Instructions - -We don't have a common instruction yet. The below is an example, and you don't -need to follow it. Important points are: - -* Reduce the number of [Component=Blink - bugs](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=Component%3DBlink) -* Newer bugs are important. - -### Task 1: Handling Component=Blink issues (mandatory, daily) - -1) Search for ["Component=Blink -Hotlist=CodeHealth -Needs=Feedback --Needs=Reduction"](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=Component%3DBlink+-Hotlist%3DCodeHealth+-Needs%3DFeedback+-Needs%3DReduction) - -2) Read the issue description and comments and add Blink>*Foo* component and -remove Blink component, if the area/ownership is clear. Otherwise: - -* If the issue has not enough information, ask for additional - information, add Needs-Feedback label, and add your email address to - Cc field. - Add a Next-Action value set to 14 days from the current date. - You're responsible for this bug. You should handle the bug until you - identify Blink areas or feedback timeout. - [This - link](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=component%3DBlink+-Hotlist%3DCodeHealth+Needs%3DFeedback+cc%3Ame&colspec=ID+Pri+M+Stars+ReleaseBlock+Component+Status+Owner+Summary+OS+Modified&x=m&y=releaseblock&cells=tiles) - shows the list of bugs of this kind you are responsible for. -* If the issue doesn't seem to be reproducible, but plausible, add - Needs-TestConfirmation. -* If the reproduction is too complex to understand the culprit area, - add Needs-Reduction. -* If you understand the culprit, but can't find an appropriate - Blink>*Foo* component (eg. by looking at similar bugs resolved in - the not-too-distant past), email - [crblink-rotation@](https://groups.google.com/a/chromium.org/forum/#!forum/crblink-rotation) - (and/or add Hotlist-BlinkNoLabel, this is TBD). You should find an - owner if the bug looks serious. - -**Task 2: Handling Component=UI issues (mandatory, daily)** - -1) Search for untriaged -[Component=UI](https://bugs.chromium.org/p/chromium/issues/list?q=Component%3DUI%20-Needs%3DFeedback%20-Type%3DFeature%2CTask&can=2) -bugs - -2) Read the issue description and add comments or move to sub-components of UI -or other components (including Blink sub-components as appropriate). Set -priorities as needed. - -### Task 3: Handling issues without Component: field (optional) - -Do the same things as task 1 and task 2 for issues without Component: field. If -an issue isn't related to Blink, add appropriate non-Blink components such as -Component:`UI`, Component:`Internals`. - -* [Bugs created in the last 30 days without - owners](https://bugs.chromium.org/p/chromium/issues/list?q=-has%3Acomponent%20-reporter%3Achromium.org%20-label%3Aautofiled%20-label%3Aperformance%20-hotlist%3DHistogramEraser%20%20-hotlist%3DMetrics-Eraser%20opened%3Etoday-30%20-has%3Aowner&can=2) -* [Bugs that have owners but that haven't been modified in the last - year](https://bugs.chromium.org/p/chromium/issues/list?q=-has%3Acomponent%20-reporter%3Achromium.org%20-label%3Aautofiled%20-label%3Aperformance%20-hotlist%3DHistogramEraser%20%20-hotlist%3DMetrics-Eraser%20modified%3Ctoday-365%20has%3Aowner%20%20-hotlist%3DExpiredHistograms&can=2) -* [All bugs without - owners](https://bugs.chromium.org/p/chromium/issues/list?q=-has%3Acomponent%20-reporter%3Achromium.org%20-label%3Aautofiled%20-label%3Aperformance%20-hotlist%3DHistogramEraser%20%20-hotlist%3DMetrics-Eraser%20-has%3Aowner&can=2) -* [All - bugs](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=-has%3Acomponent+-reporter%3Achromium.org+-label%3Aautofiled+-label%3Aperformance+-hotlist%3DHistogramEraser++-hotlist%3DMetrics-Eraser) - -**Task 4: monitor stale P0/P1 security bugs (optional)** - -* Review all result from [this - search](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=Type%3DBug-Security+component%3Ablink+pri%3D0%2C1+modified%3Ctoday-30&colspec=ID+Pri+M+Stars+ReleaseBlock+Component+Status+Owner+Summary+OS+Modified&x=m&y=releaseblock&cells=ids). -* Check that the bug has an owner, the owner is actively working on - the issue, and is fixing. Re-assign, re-categorize or ping the bug - as appropriate. - -**Deprecated:** - -### Reducing/Confirming Component=Blink bugs (mandatory, daily) - -1) Search for "[Component=Blink -Needs=Reduction](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=Component%3DBlink+Needs%3DReduction)", -choose one, and investigate it to identify Blink areas by reading HTML/CSS/JS -code and/or making a reduction. - -2) Add Blink>*Foo* components, remove Blink component and Needs-Reduction -when confirmed and updated the status accordingly, if needed. - -## Contact - -Public mailing list: -[crblink-rotation@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/crblink-rotation) -(<https://groups.google.com/a/chromium.org/forum/#!forum/crblink-rotation>)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/coding-style/index.md b/chromium/docs/website/site/blink/coding-style/index.md deleted file mode 100644 index 1b667e4f987..00000000000 --- a/chromium/docs/website/site/blink/coding-style/index.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: coding-style -title: Blink Coding Style Guidelines ---- - -These guidelines are specific to the [Blink](/blink) project, not to be confused -with the general [Chromium coding -style](https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/styleguide.md). - -[TOC] - -## C++ - -This documentation has moved to the [Blink C++ Style -Guide](https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/c++/blink-c++.md). - -## Python - -This documentation has moved to the [Blink Python Style -Guide](https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/python/blink-python.md). - -## Web tests - -See [Writing Web -Tests](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/writing_web_tests.md). - -## License - -Existing files in Blink use a longer header license block inherited from WebKit, -however new files should follow the Chromium [File Header -Style](https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/c++/c++.md#File-headers). - -To use this license block you must make sure you have completed the [External -Contributor -Checklist](/developers/contributing-code/external-contributor-checklist). - -## License for this document - -*This page began as the [WebKit Coding Style -Guidelines](http://www.webkit.org/coding/coding-style.html), Licensed under -[BSD](http://www.webkit.org/coding/bsd-license.html):* - -BSD License -Copyright (C) 2009 Apple Inc. All rights reserved. -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: -1. Redistributions of source code must retain the above copyright notice, this -list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright notice, -this list of conditions and the following disclaimer in the documentation and/or -other materials provided with the distribution. -THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS “AS IS” AND ANY -EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY -DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -## References - -\[1\] Comments on comments -<https://lists.webkit.org/pipermail/webkit-dev/2011-January/015769.html>
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/coding-style/layout-test-style-guidelines/index.md b/chromium/docs/website/site/blink/coding-style/layout-test-style-guidelines/index.md deleted file mode 100644 index e5fb1897d06..00000000000 --- a/chromium/docs/website/site/blink/coding-style/layout-test-style-guidelines/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/coding-style - - Blink Coding Style Guidelines -page_name: layout-test-style-guidelines -title: Web Test Style Guidelines ---- - -[docs/testing/writing_web_tests.md](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/writing_web_tests.md)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/deprecating-features/index.md b/chromium/docs/website/site/blink/deprecating-features/index.md deleted file mode 100644 index 8f4438ad286..00000000000 --- a/chromium/docs/website/site/blink/deprecating-features/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: deprecating-features -title: Deprecating Features ---- - -[TOC] - -## How To Measure Usage and Notify Developers - -1. Add your feature to [web_feature.mojom's - WebFeature](https://cs.chromium.org/chromium/src/third_party/WebKit/public/platform/web_feature.mojom?q=third_party/WebKit/public/platform/web_feature.mojom&sq=package:chromium&dr&l=16). -2. Add a clever deprecation message to the big switch in - [UseCounter::deprecationMessage](https://cs.chromium.org/chromium/src/third_party/WebKit/Source/core/frame/Deprecation.cpp?type=cs&q=Deprecation::DeprecationMessage%5C(&l=295). -3. Instrument your code by: - * Adding - `[DeprecateAs](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/WebKit/Source/bindings/IDLExtendedAttributes.md#DeprecateAs_m_a_c)=[your - enum value here]` to the feature's IDL definition (see [these - examples](https://cs.chromium.org/search/?q=DeprecateAs+file:%5Esrc/third_party/WebKit/Source/modules/+package:%5Echromium$&type=cs)). - * Adding a call to - `[Deprecation::CountDeprecation](https://cs.chromium.org/chromium/src/third_party/WebKit/Source/core/frame/Deprecation.h?type=cs&l=43)` - somewhere relevant (as we're dong for the - [UserMediaRequest](https://cs.chromium.org/chromium/src/third_party/WebKit/Source/modules/mediastream/UserMediaRequest.cpp?type=cs&q=Deprecation::CountDeprecation%5C(document-%3EGetFrame%5C(%5C),&l=422)). - -Note that `DeprecateAs` is intended to replace `MeasureAs` in the IDL file. -Specifying both is redundant.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/developer-faq/index.md b/chromium/docs/website/site/blink/developer-faq/index.md deleted file mode 100644 index e452d1d4408..00000000000 --- a/chromium/docs/website/site/blink/developer-faq/index.md +++ /dev/null @@ -1,318 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: developer-faq -title: Developer FAQ - Why Blink? ---- - -[« Back to the Blink project page](http://www.chromium.org/blink) - -[TOC] - -### Why is Chrome spawning a new browser engine? - -There are two main reasons why we’re making this change. - - The main reason is that Chromium uses a different multi-process architecture - from other WebKit-based browsers. So, over the years, supporting multiple - architectures has led to increasing complexity for both the WebKit and - Chromium communities, slowing down the collective pace of innovation. - - In addition, this gives us an opportunity to do open-ended investigations - into other performance improvement strategies. We want web applications to - be as fast as possible. So for example, we want to make as many of the - browser’s duties as possible run in parallel, so we can keep the main thread - free for your application code. We’ve already made significant progress - here--for example by reducing the impact JavaScript and layout have on page - scrolling, and making it so an increasing number of CSS animations can run - at 60fps even while JavaScript is doing some heavy-lifting--but this is just - the start. - -We want to do for networking, rendering and layout what V8 did for JavaScript. -Remember JS engines before V8? We want the same sort of healthy innovation that -benefits all users of the web, on all browsers. - -### What sorts of things should I expect from Chrome? - -In the Blink [Architectural -Changes](http://www.chromium.org/blink#architectural-changes) section we have -listed a few changes that will improve the speed and stability of the web -platform in Chrome. Meanwhile, there are more improvements whose feasibility and -performance benefits we're excited to investigate: - -* Deliver a speedier DOM and JS engine - * Multi-process, security-focused, and faster low-overhead DOM - bindings to V8 - * JIT DOM attribute getters in V8. That would allow V8 to access - div.id, div.firstChild, etc without leaving JIT code. Mozilla is - also meanwhile trying to[ JIT DOM attribute - getters](https://bugzilla.mozilla.org/show_bug.cgi?id=747285). - * Implement the DOM in JS. This has the potential to make - JavaScript DOM access dramatically faster, but will involve a - very large re-write of WebKit’s DOM implementation. IE is - already doing this and overall, this helps yield faster GC, and - faster DOM bindings - * Support snapshotting in V8. This could allow us to have no - parse-time overhead and near-instant startup of previously - loaded pages. -* Keep the platform secure - * Better sandboxing of the compositor thread - * [Out-of-process - iframes](http://www.chromium.org/developers/design-documents/oop-iframes). - Use renderer processes [as a security - boundary](http://www.chromium.org/developers/design-documents/site-isolation) - between cross-site iframes. -* Refactor for performance - * Reduce binding layer overhead. We can make things even faster by - simplifying the many abstractions in the binding layers that - have existed to share code between JavaScriptCore and V8 (e.g. - ScriptState, DOMRequestState, etc). - * Improve the performance of style resolution. - * Improve utilization of multiple cores. -* Enable more powerful rendering and layout - * Pursue multi-threaded layout - * Overhaul style recalculation and selector resolution performance - * Stop creating renderers for hidden iframes - * Fix old bugs like plugins unloading when they're set to - display:none. - * Allow generated content to be selectable and copy-pasteable. - * Rewrite event handling to be more consistent and have fewer bugs - with focus, mouse up, clicks, etc. - * Fire `<iframe>` unload events async to make removeChild faster. - -### Is this new browser engine going to fragment the web platform's compatibility more? - -We're keenly aware of the compatibility challenges faced by developers today, -and will be collaborating closely with other browser vendors to move the web -forward and preserve the interoperability that has made it a successful -ecosystem. We’ve also put a lot of work over the past few years into reducing -that pain. Take one of the huge successes of the web standards community: the -HTML5 Parser. All major browser engines now share the exact same parsing logic, -which means things like broken markup, <a> tags wrapping block elements, -and other edge cases are all handled consistently across browsers. This -interoperability is important to Chrome and we want to defend it. - -Our team regularly contributes to sites that document browser support and -differences like Mozilla's [MDN](https://developer.mozilla.org/en-US/), -[WebPlatform.org](http://docs.webplatform.org/), and [Can I -Use](http://caniuse.com/). The last thing we want is for things to go backwards. - -We see testing as the critical piece of web browser interoperability. Chrome -currently shares and runs tests that were authored by Opera, Mozilla, and W3C -Working Groups and we'll be doing a better job of this going forward. Developers -need to be able to rely on Chrome’s implementation of standards, and that’s -something we take very seriously. See the -[Testing](http://www.chromium.org/blink#testing) section for our plans. - -### Hold up, isn't more browsers sharing WebKit better for compatibility? - -It's important to remember that WebKit is already not a homogenous target for -developers. For example, features like WebGL and IndexedDB are only supported in -some WebKit-based browsers. [Understanding WebKit for -Developers](http://paulirish.com/2013/webkit-for-developers/) helps explain the -details, like why `<video>`, fonts and 3D transforms implementations vary across -WebKit browsers. - -Today Firefox uses the Gecko engine, which isn’t based on WebKit, yet the two -have a high level of compatibility. We’re adopting a similar approach to Mozilla -by having a distinct yet compatible open-source engine. We will also continue to -have open bug tracking and [implementation status](http://chromestatus.com/) so -you can see and contribute to what we’re working on at any time. - -From a short-term perspective, monocultures seem good for developer -productivity. From the long-term perspective, however, monocultures inevitably -lead to stagnation. It is our firm belief that more options in rendering engines -will lead to more innovation and a healthier web ecosystem. - -### How does this affect web standards? - -Bringing a new browser engine into the world increases diversity. Though that in -itself isn't our goal, it has the beneficial effect of ensuring that multiple -interoperable implementations of accepted standards exist. Each engine will -approach the same problem from a different direction, meaning that web -developers can be more confident in the performance and security characteristics -of the end result. It also makes it less likely that one implementation's quirks -become de facto standards, which is good for the open web at large. - -### Will we see a `-chrome-` vendor prefix now? - -We’ve seen how the proliferation of vendor prefixes has caused pain for -developers and we don't want to exacerbate this. As of today, Chrome is adopting -a policy on vendor prefixes, one that is similar to [Mozilla's recently -announced -policy](http://lists.w3.org/Archives/Public/public-webapps/2012OctDec/0731.html). - -In short: we won't use vendor prefixes for new features. Instead, we’ll expose a -single setting (in `about:flags`) to enable experimental DOM/CSS features for -you to see what's coming, play around, and provide feedback, much as we do today -with [the “Experimental WebKit -Features”/"](https://plus.google.com/+GoogleChromeDevelopers/posts/ffDPaPAMkMZ)==Enable -experimental Web Platform features"==[ -flag](https://plus.google.com/+GoogleChromeDevelopers/posts/ffDPaPAMkMZ). Only -when we're ready to see these features ship to stable will they be enabled by -default in the dev/canary channels. - -For legacy vendor-prefixed features, we will continue to use the `-webkit-` -prefix because renaming all these prefixes to something else would cause -developers unnecessary pain. We've [started looking -into](https://plus.google.com/+GoogleChromeDevelopers/posts/Rh1aMkzucgV) real -world usage of HTML5 and CSS3 features and hope to use data like this to better -inform how we can responsibly deprecate prefixed properties and APIs. As for any -non-standard features that we inherited (like `-webkit-box-reflect`), over time -we hope to either help standardize or deprecate them on a case-by-case basis. - -### So we have an even more fragmented mobile WebKit story? - -We really don’t want that; time spent papering over differences is time not -spent building your apps’ features. We’re focusing our attention on making -Chrome for Android the best possible mobile browser. So you should expect the -same compatibility, rapid release schedule and super high JS and DOM performance -that you get in desktop Chrome. - -Your site or app's success on the mobile web is dependent on the mobile browsers -it runs on. We want to see that entire mobile web platform keeps pace with, and -even anticipates, the ambitions of your app. Opera is already shipping a beta of -their Chromium-based browser which has features and capabilities very similar to -what's in Chrome on Android. - -### What's stopping Chrome from shipping proprietary features? - -Our goal is to drive innovation and improve the compatible, open web platform, -not to add a ton of features and break compatibility with other browsers. We're -introducing strong developer-facing policies on [adding new -features](http://www.chromium.org/blink#new-features), the [use of vendor -prefixes](http://www.chromium.org/blink#vendor-prefixes), and [when a feature -should be considered stable enough to -ship](http://www.chromium.org/blink#compatibility). This codifies our policy on -thoughtfully augmenting the platform, and as transparency is a core principle of -Blink, we hope this process is equally visible to you. The [Chromium Feature -Dashboard](http://www.chromestatus.com/features) we recently introduced offers a -view of the standards and implementation status of many of our implemented and -planned features. - -Please feel free to watch the development of Blink via -[Gitiles](https://chromium.googlesource.com/chromium/blink), follow along on the -[blink-dev mailing -list](https://groups.google.com/a/chromium.org/group/blink-dev), and join -`#blink` on Freenode. - -We know that the introduction of a new rendering engine can have significant -implications for the web. In the coming months we hope to earn the respect of -the broader open web community by letting our actions speak louder than words. - -### Is this just a ruse to land Google-developed technologies? - -Nope, not at all! We're instituting [strong guidelines on new -features](http://www.chromium.org/blink#new-features) that emphasize standards, -interoperability, and transparency. We expect to hold all new shipping features -that affect web developers on the open web up to the same level of scrutiny. -Technologies and standards developed primarily within Google will be held to the -same guidelines as others. - -### What should we expect to see from Chrome and Blink in the next 12 months? What about the long term? - -Our main short-term aim is to improve performance, compatibility and stability -for all the platforms where we ship Chrome. In the long term we hope to -significantly improve Chrome and inspire innovation among all the browser -manufacturers. We will be increasing our investment in conformance tests (shared -with W3C working groups) as part of our commitment to being good citizens of the -open web. - -### Is this going to be open source? - -Yes, of course. [Chromium is already open-source](http://www.chromium.org/Home) -and Blink is part of that project. Transparency is one of our core principles. -[Developing Blink](http://www.chromium.org/blink#participating) covers this in -detail. - -### Opera recently announced they adopted Chromium for their browsers. What's their plan? - -Opera will be adopting Blink, as mentioned by [Bruce Lawson on his -blog](http://www.brucelawson.co.uk/2013/hello-blink/). - -### Why is this is good for me as a web developer? - -One of the keys to improving users’ experience is to give developers the tools, -features, compatibility and performance they need to get the most out of the -platform. Although the move is borne out of architectural necessity, it also -allows us to prioritize the features that you need to build the next generation -of apps, on both mobile and desktop. Similar to the introduction of V8, we hope -this will spur innovation and you can and should expect the whole web platform -to benefit. - -Our ambitions are high and we continue to need the feedback and contributions -that have made Chrome the browser it is today. You should also expect improved -transparency in Blink's development processes, so getting involved will be -easier than ever. Please, review the [Chromium Feature -Dashboard](http://www.chromestatus.com/features), experiment with future -features in Dev/Canary and [file any bugs](http://crbug.com/) you find. - -~ FAQ authored by Paul Irish and Paul Lewis on the Chrome Developer Relations -team - -[<img alt="image" -src="/blink/developer-faq/paulhead.jpg.1365009992996.png">](/blink/developer-faq/paulhead.jpg.1365009992996.png)[<img -alt="image" -src="/blink/developer-faq/lewishead.jpg.1365009990294.png">](/blink/developer-faq/lewishead.jpg.1365009990294.png) - -# Q&A Video - -After the Blink announcement, the developer community submitted hundreds of -questions and votes on Google Moderator ([goo.gl/Uu0qV](http://goo.gl/Uu0qV)) -that sought answers to your tough questions about Blink. - -Engineering leads Darin Fisher and Eric Seidel are joined by PM Alex Komoroske -and Developer Advocate Paul Irish - -Below are the top-voted questions, along with timecodes you can click (will open -in a new window): -[1:12](http://www.youtube.com/watch?v=TlJob8K_OwE#t=1m12s) What will be the -relationship between the WebKit and Blink codebases going forward? -[2:42](http://www.youtube.com/watch?v=TlJob8K_OwE#t=2m42s) When will Blink ship -on the Chrome channels Canary/Beta/Stable? -[3:25](http://www.youtube.com/watch?v=TlJob8K_OwE#t=3m25s) How does the plan for -transitioning the WebKit integrated in Android to Blink look like? -[4:59](http://www.youtube.com/watch?v=TlJob8K_OwE#t=4m59s) Can you elaborate on -the idea of moving the DOM into JavaScript? -[6:40](http://www.youtube.com/watch?v=TlJob8K_OwE#t=6m40s) Can you elaborate on -the idea of "removing obscure parts of the DOM and make backwards incompatible -changesthat benefit performance or remove complexity"? -[8:35](http://www.youtube.com/watch?v=TlJob8K_OwE#t=8m35s) How will Blink -responsibly deprecate prefixed CSS properties? -[9:30](http://www.youtube.com/watch?v=TlJob8K_OwE#t=9m30s) What will prevent the -same collaborative development difficulties that have hampered Webkit emerging -in Blink, as it gains more contributors and is ported to more platforms? -[12:35](http://www.youtube.com/watch?v=TlJob8K_OwE#t=12m35s) Will changes to -Blink be contributed back to the WebKit project? -[13:34](http://www.youtube.com/watch?v=TlJob8K_OwE#t=13m34s) Google said -problems living with the WebKit2 multi-process model was a prime reason to -create Blink, but Apple engineers say they asked to integrate Chromium's -multi-process into WebKit prior to creating WebKit2, and were refused. What -gives? -[16:46](http://www.youtube.com/watch?v=TlJob8K_OwE#t=16m46s) Is the plan to -shift Android's <webview> implementation over to Blink as well? -[17:26](http://www.youtube.com/watch?v=TlJob8K_OwE#t=17m26s) Will blink be able -to support multiple scripting languages? E.g. Dart. -[19:34](http://www.youtube.com/watch?v=TlJob8K_OwE#t=19m34s) How will affect -other browsers that have adopted WebKit? -[20:44](http://www.youtube.com/watch?v=TlJob8K_OwE#t=20m44s) Does this means -Google stops contributions to WebKit? -[21:31](http://www.youtube.com/watch?v=TlJob8K_OwE#t=21m31s) What Open Source -license will Blink have? Will it continue to support the H.264 video codec? -[22:11](http://www.youtube.com/watch?v=TlJob8K_OwE#t=22m11s) Any user-agent -string changes? -[23:38](http://www.youtube.com/watch?v=TlJob8K_OwE#t=23m38s) When we'll be able -to test first versions of Blink in Chromium? -[24:15](http://www.youtube.com/watch?v=TlJob8K_OwE#t=24m15s) How can developers -follow Blink's development? -[25:40](http://www.youtube.com/watch?v=TlJob8K_OwE#t=25m40s) What is -[chromestatus.com](http://chromestatus.com/) about? -[26:40](http://www.youtube.com/watch?v=TlJob8K_OwE#t=26m40s) How will this -impact Dart language's progress? -[27:13](http://www.youtube.com/watch?v=TlJob8K_OwE#t=27m13s) Will this be a -direct competitor against Mozilla's new engine? -[29:03](http://www.youtube.com/watch?v=TlJob8K_OwE#t=29m03s) When will all -existing vendor prefixes in Blink be phased out? -[30:20](http://www.youtube.com/watch?v=TlJob8K_OwE#t=30m20s) Will you support --blink-text-decoration: blink? ;)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/developer-faq/lewishead.jpg.1365009990294.png.sha1 b/chromium/docs/website/site/blink/developer-faq/lewishead.jpg.1365009990294.png.sha1 deleted file mode 100644 index 33db8a86ca3..00000000000 --- a/chromium/docs/website/site/blink/developer-faq/lewishead.jpg.1365009990294.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -666d6ff57f982560e223f88679a92af3a8add1e6
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/developer-faq/paulhead.jpg.1365009992996.png.sha1 b/chromium/docs/website/site/blink/developer-faq/paulhead.jpg.1365009992996.png.sha1 deleted file mode 100644 index 59f13937a19..00000000000 --- a/chromium/docs/website/site/blink/developer-faq/paulhead.jpg.1365009992996.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -63185d7d28f9ea5167ba48ff67cb106ea6d8ae36
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/directory-dependency-in-blink/before.png.sha1 b/chromium/docs/website/site/blink/directory-dependency-in-blink/before.png.sha1 deleted file mode 100644 index e000008f819..00000000000 --- a/chromium/docs/website/site/blink/directory-dependency-in-blink/before.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -1b760df62cdf3f99711ecb2edb7218789fe0acd3
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/directory-dependency-in-blink/before_merge_resized.png.sha1 b/chromium/docs/website/site/blink/directory-dependency-in-blink/before_merge_resized.png.sha1 deleted file mode 100644 index c722d1c0f0d..00000000000 --- a/chromium/docs/website/site/blink/directory-dependency-in-blink/before_merge_resized.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -7e5ca31542d6d7c86e7188765ef8c9ad72704119
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/directory-dependency-in-blink/index.md b/chromium/docs/website/site/blink/directory-dependency-in-blink/index.md deleted file mode 100644 index 07a1277d513..00000000000 --- a/chromium/docs/website/site/blink/directory-dependency-in-blink/index.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: directory-dependency-in-blink -title: Directory dependency in Blink (Still DRAFT) ---- - -## NOTE: This plan is not decided yet and is still a work in progress. - -## Overview - -In 2015 Sep, we merged the Blink repository into the Chromium repository. The -repository merge enabled us to add dependencies from Blink to Chromium and -opened a door for significantly simplifying abstraction layers that had been -needed to connect Blink with Chromium. However, adding random dependencies from -Blink to Chromium will break layering and just mess up the code base. We need a -guideline about it. - -Before the repository merge, Blink had the following dependency. Public APIs -were the only way to connect Blink with Chromium's content layer. - -[<img alt="image" -src="/blink/directory-dependency-in-blink/before_merge_resized.png">](/blink/directory-dependency-in-blink/before_merge_resized.png) - -After the repository merge, we're planning to introduce direct dependencies from -Blink to Chromium (e.g., wtf/ => base/) to simplify the interactions. To -introduce a new dependency, you need to follow the following guideline. - -## Guideline - -1. Send an email to blink-dev@ to propose the dependency. The email - needs to explain the advantages of introducing the dependency. -2. Get a consensus on blink-dev@. If people can't get agreement in the - discussion, public/OWNERS should give advice. -3. Add the dependency to the following "Allowed dependencies from Blink - => Chromium" section. - -We do want to avoid introducing random dependencies and breaking layering. -Unless introducing the dependency is going to have a large benefit (e.g., remove -a lot of abstraction classes, remove a lot of code duplication etc), you should -instead consider just using public APIs. After the repository merge, it is -pretty easy to add/remove/modify public APIs because you no longer need -three-sided patches. In particular, remember that: - -* Blink and Chromium have different assumptions and priorities on - performance, memory and code health. So we may not want to share - implementations too much. For example, we may want to keep standard - libraries in wtf/ such as Vectors and Strings until we’re pretty - sure that it is really a win to replace them with base/ - alternatives. -* This kind of refactoring requires a substantial amount of - engineering resources. We should keep in mind the opportunity cost. - -## Allowed dependencies from Blink => Chromium - -(Once the intent-to-implement is approved, please add the dependency to the -following list. You can also add a link to a discussion log in blink-dev@, -design documents etc.) - -* ... -* ... -* ... - -## Discussions - -If you want to know more background about the dependency design, see the -following discussions. - -* [Removing the WTF namespace - (blink-dev@)](https://groups.google.com/a/chromium.org/forum/#!topic/blink-dev/B29AVrZy1Z4/discussion) -* [Proposal for the future dependency model in Blink - (blink-dev@)](https://groups.google.com/a/chromium.org/forum/#!topic/blink-dev/e4y_6y0Nlp8/discussion) -* [Proposal for a future Blink architecture (design document that - summarized people's thoughts as of 2015 - May)](https://docs.google.com/document/d/1gwQ1qn3Qx1U_xm9BbwIsJz0GP_05KUXVHhk3PxeNuSw/edit#)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/dom-exceptions/index.md b/chromium/docs/website/site/blink/dom-exceptions/index.md deleted file mode 100644 index 47319d71e22..00000000000 --- a/chromium/docs/website/site/blink/dom-exceptions/index.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: dom-exceptions -title: DOM Exceptions ---- - -**Useful error messages with ExceptionMessages** - -When throwing a DOM exception, please ensure that you take the time to write an -error message that helps developers understand what's gone wrong, and what they -can do to fix things. Something like -exceptionState.throwDOMException(InvalidStateError, "This object's 'readyState' -is not 'open'.") can make the difference between a 5 minute fix, and an all-day -facepalming session. The -[ExceptionMessages](http://cs.chromium.org/ExceptionMessages.h) helper class has -a variety of methods that help you construct a more detailed and specific -message in a consistent way. Perhaps: - -es.throwDOMException(TypeMismatchError, -ExceptionMessages::argumentNullOrIncorrectType(1, "Node")); - -That will give the user an exception object whose message property reads "Failed -to execute "method" on "Interface": The 1st argument is null, or an invalid Node -object.", which has been scientifically measured to be 83 times more useful than -an exception lacking that detail. In general, developers will be much happier if -we give them enough data to resolve an issue right away, so please don't be -afraid of adding detail. - -Just add #include "bindings/v8/ExceptionMessages.h" and go wild. - -**Security considerations** - -Exception messages are exposed to the web via JavaScript. Please be very careful -when throwing exceptions that might expose interesting data cross-origin. In -particular, SecurityError messages are prone to this sort of accidental leakage. - -1. Always throw SecurityError exceptions via - [ExceptionState::throwSecurityError](http://cs.chromium.org/ExceptionState::throwSecurityError). -2. Ensure that the sanitizedMessage (first parameter) can safely be - exposed to JavaScript. -3. Add additional detail via an unsanitizedMessage (second parameter) - if relevant. - -Practical examples of this include -DOMWindow::sanitizedCrossDomainAccessErrorMessage and -DOMWindow::crossDomainAccessErrorMessage. We call both of these methods from -inside -[V8Initializer::failedAccessCheckCallbackInMainThread](http://cs.chromium.org/V8Initializer%20failedAccessCheckCallbackInMainThread) -to ensure that JavaScript can't access details about cross-origin frames, but -that those details appear in the console if the exceptions aren't caught.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/getting-started-with-blink-debugging/index.md b/chromium/docs/website/site/blink/getting-started-with-blink-debugging/index.md deleted file mode 100644 index ffb332fd0a1..00000000000 --- a/chromium/docs/website/site/blink/getting-started-with-blink-debugging/index.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: getting-started-with-blink-debugging -title: Getting Started with Blink Debugging ---- - -[TOC] - -### Introduction - -While many of the tools and tips on this page can be used for it, this page -focuses on debugging Blink outside the context of the web tests. For more web -test specific instructions, see [this -page](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/web_tests.md). -For more general Chromium debugging info, see the respective pages for debugging -on [Windows](/developers/how-tos/debugging-on-windows), -[Mac](/developers/how-tos/debugging-on-os-x), and -[Linux](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux_debugging.md). - -### Linux - -#### Getting Started - -There are two main ways to get into blink: via debugging the chromium binary -itself or `content_shell`. For most purposes of exclusive Blink debugging, the -latter is the recommended option because it drastically reduces size and -complexity. This means building `content_shell`, which should be as simple as -making it the build target for your build method of choice. This should stick a -`content_shell` binary in your `out/Default` directory. - -`content_shell` itself takes as an argument the HTML file you wish to run Blink -on. Furthermore, one of the simplest types of debugging you might want to do is -to see the basic page structure after a page load (this internal structure in -Blink is called the Layout Tree, not to be confused with the DOM Tree or the -Line Box Tree). You can do this with a simple command line option of -`--run-web-tests`. Thus, one of your simplest debugging tools, seeing the page -structure after a page load, might look something like: - -```none -content_shell --run-web-tests test.html -``` - -#### Starting the Debugger - -Debugging on Linux is generally done with GDB, so we will assume that's what you -are using here. Not surprisingly, you will almost always want to compile Blink -in debug mode to get all the symbols and tools you will need. - -You will also want to use the `gdbinit` script to help gdb find source code, -pretty-print common types, and other such niceties that will avoid you staring -at assembly code. See -[`docs/gdbinit.md`](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/gdbinit.md) -for more details. - -**Important: Previous revisions of this document suggested running with the -`--single-process `when debugging. That flag is no longer supported; it may -work, it may fail outright, and it may appear to work yet manifest subtle -differences in behavior that will cause you to waste many hours in understanding -them.** - -You may need to modify your system's ptrace security policy before you can debug -the renderer -([details](http://askubuntu.com/questions/41629/after-upgrade-gdb-wont-attach-to-process)); -run this command: - -```none -echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope -``` - -Both `content_shell` and `chromium` spawn renderer sub-processes; to debug -blink, you need to attach a debugger to one of those sub-processes. The simplest -way to do this is with the `--no-sandbox` and `--renderer-startup-dialog` -parameters: - -```none -out/Default/content_shell --no-sandbox --renderer-startup-dialog test.html -``` - -When you do this, `content_shell` will print a message like this: - -```none -[10506:10506:0904/174115:2537132352130:ERROR:child_process.cc(131)] Renderer (10506) paused waiting for debugger to attach. Send SIGUSR1 to unpause. -``` - -This tells you that the pid of the renderer process is 10506. You can now attach -to it: - -```none -gdb -p 10506 -``` - -When gdb loads up, set whatever breakpoints you want in the blink code and -'continue'; for example: - -```none -(gdb) b blink::LayoutView::layout -(gdb) c -``` - -Then, send SIGUSR1 to the renderer process to tell it to proceed: - -```none -(gdb) signal SIGUSR1 -``` - -If you are running web test, `third_party/blink/tools/debug_web_tests` does -almost everything except for SIGUSR1 automatically. - -If you see 'Could not find DWO CU' errors, you may need to have a symlink to the -build directory from the current working directory. - -```none -% cd third_party/blink -% ln -s ../../out/Default/obj . -% ./tools/debug_web_tests --target=Default -``` - -### General Useful Debugging Tools - -#### Debugging functions - -There are some key functions built into objects once you've reach a breakpoint -inside Blink. For the examples here, we'll assume you're using GDB on Linux. -These can be incredibly useful for showing the trees midway during execution to -try and identify points when things change. You can use the GDB command print to -display them. Here are some of Blink's debugging functions: - -<table> -<tr> -<td> Function</td> -<td>Objects it's available on </td> -<td>Description</td> -</tr> -<tr> -<td> ShowTreeForThis()</td> -<td>`Node`s and LayoutObjects</td> -<td>Outputs the DOM tree, marking this with a \*</td> -</tr> -<tr> -<td> ShowLayoutTreeForThis()</td> -<td>LayoutObjects</td> -<td>Outputs the Layout tree, marking this with a \*</td> -</tr> -<tr> -<td> ShowLineTreeForThis()</td> -<td>LayoutObjects and InlineBoxes</td> -<td>Outputs the Inline Box tree for the associated block flow, marking all matching inline boxes associated with this with a \*</td> -</tr> -<tr> -<td> ShowDebugData()</td> -<td>DisplayItemLists</td> -<td>Outputs the list of display items and associated debug data</td> -</tr> -</table> - -Assuming a local variable `child` in scope that's a `LayoutObject`, the -following will print the Layout Tree: - -```none -(gdb) print child->showLayerTreeForThis() -``` - -`#### Blink GDB python library` - -`When using a GDB build that supports python, there's a library of useful Blink -functions and pretty printers that can make working with some of Blink's types -easier and more convenient, such as pretty printers for LayoutUnit and -LayoutSize classes. You can find it at third_party/blink/tools/gdb/blink.py; see -[LinuxDebugging](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux/debugging.md) -for instructions.` - -### Printing back trace - -#### Use Chromium's StackTrace - -```none -#include "base/debug/stack_trace.h" -... -base::debug::StackTrace().Print(); -// or -LOG(ERROR) << base::debug::StackTrace(); -``` - -and run Chrome with `--no-sandbox` command line option. - -### Debugging Printing related issues - -It is difficult to understand whether an issue lies in the Print Preview logic -or the Rendering logic. This -[document](https://docs.google.com/document/d/1aK27hiUPEm75OD4Dw2yQ9CmNDkLjL7_ZzglLdHW6UzQ/edit?usp=sharing) -uses some of the tools available to us to help solve this issue.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/guidelines/api-owners/index.md b/chromium/docs/website/site/blink/guidelines/api-owners/index.md deleted file mode 100644 index 9ca1c2287cb..00000000000 --- a/chromium/docs/website/site/blink/guidelines/api-owners/index.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/guidelines - - Guidelines and Policies -page_name: api-owners -title: Blink API owners ---- - -Summary - -The Blink API owners oversee, enforce and evolve the [Blink Intent -process](/blink/launching-features). Their most public role is to approve -experimentation and shipping of new or changed -[web-exposed](/blink/guidelines/web-exposed) -[APIs](https://chromestatus.com/features) to Chromium-based browsers. - -You can find a list of the current API owners -[here](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/API_OWNERS). - -## What is the Blink Intent process? - -The [Blink Intent process](/blink/launching-features) - proceeding from -Prototype to Ship - is how web-exposed features ship in Chromium. - -## What are the Blink API owners? - -The Blink API owners are the stewards of the [core values of -Blink](/blink/guidelines/values) and those [values in -practice](/blink/guidelines/web-platform-changes-guidelines). They achieve this -by enforcing proper use of the Intent process, which is designed to protect and -enhance those values. - -The Blink Intent process itself is also overseen and evolved by the Blink API -owners. - -## What do the Blink API owners actually do? - -It can be summarized as: - -* LGTMs from at least three Blink API owners are necessary to ship or - change a web platform feature in Chromium -* One LGTM is necessary to start an experiment or a deprecation period -* The primary task of Blink API owners is to decide whether to give - those LGTMs - -They also give reasons, if needed, why the LGTM was provided or not provided. -The reasons are needed in cases where it may not otherwise be clear why the -decision was made. LGTMs are provided via email to -[blink-dev@chromium.org](https://groups.google.com/a/chromium.org/g/blink-dev). -Public discussion about issues of interest to the API owners occurs on -[blink-api-owners-discuss@chromium.org](https://groups.google.com/a/chromium.org/g/blink-api-owners-discuss). -Weekly meetings process the [backlog of intents needing -decisions](https://docs.google.com/spreadsheets/d/1pvXEMD5pRioognaqEzglS-4ZBSQ_YmzL8Fiz7yt4Bb4/edit#gid=0&fvid=1112765777). -Any significant changes to the Intent process also need the approval of the API -owners. - -In practice, the Blink API owners may also help developers through tricky parts -of the Intent process. - -## How do the Blink API owners arrive at their decisions? - -The Blink API owners review the Intent process was faithfully followed, and most -importantly that nothing about experimenting with or shipping these features is -in conflict with any of the core values of Blink. - -The API owners will ask any questions about the evidence provided on the -blink-dev thread for the Intent, so that everyone can see those questions. - -More details - -[Procedures governing the API owners](/blink/guidelines/api-owners/procedures) - -[Requirements for becoming an API -owner](/blink/guidelines/api-owners/requirements)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/guidelines/api-owners/procedures/index.md b/chromium/docs/website/site/blink/guidelines/api-owners/procedures/index.md deleted file mode 100644 index 2b5f20c76f6..00000000000 --- a/chromium/docs/website/site/blink/guidelines/api-owners/procedures/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/guidelines - - Guidelines and Policies -- - /blink/guidelines/api-owners - - Blink API owners -page_name: procedures -title: Blink API owner procedures ---- - -[Last updated via unanimous approval: August 3, -2021](https://groups.google.com/a/chromium.org/g/blink-api-owners-discuss/c/zeyQuh6Wk5E) - -## LGTM Requirements - -* Shipping a change to add, change or remove any substantial aspect of a web-exposed API requires 3 LGTMs. - -* Starting or extending an Origin Trial requires 1 LGTM. - -* Any non-standard Origin Trial require 3 LGTMs. - -* Intents to Prototype do not require any LGTMs. - -## Adding and removing API owners - -An API owner may be added after 3 LGTMs, plus evidence of the new API owner -meeting the [requirements](/blink/guidelines/api-owners/requirements). - -API owners may be removed if they are persistently failing to meet the -requirements as well as to review a reasonable number of the incoming intents. -They may be removed after a vote by an absolute majority of other API owners, -after at least 8 weeks notice (\*) to the API owner to be removed plus -[blink-api-owners-discuss@chromium.org](mailto:blink-api-owners-discuss@chromium.org), -and no formal objection from the API owner to be removed. A formal objection -triggers the majority vote mechanism. - -(\*) The 8 week period starts from the point at which the notified API owner can -be reasonably expected to have received the message, and is not on a leave, -vacation etc. - -API owners may resign at any time, via email to -[blink-api-owners-discuss@chromium.org](mailto:blink-api-owners-discuss@chromium.org). - -## Formal objection - -An API owner may formally object to any decision, through written communication -to -[blink-api-owners-discuss@chromium.org](mailto:blink-api-owners-discuss@chromium.org). -This triggers the majority vote mechanism. - -## Majority vote - -Any API owners decisions that cannot get the required LGTMs will be decided -through a majority vote. - -Note: API owners are expected to work via consensus, and try hard not to cause -this situation. For reference: it has never, to date, been needed. - -A “majority vote” consists of a formal vote among the API owners, at a -videoconference or in-person meeting attended by a majority of the API owners, -and announced to all API owners at least a week in advance, with option for -absentee votes. The result of this vote decides the issue. - -If a vote occurs, the documented final vote (including who voted which way), and -description of the objection raised, must be published publicly on -blink-dev@chromium.org. - -## What “LGTMs” means - -An LGTM is recorded via email to -[blink-dev@chromium.org](https://groups.google.com/a/chromium.org/g/blink-dev). - -**1 LGTM means:** An API owner LGTMed the proposal and no API owner formally objected. - -**3 LGTMs mean:** 3 API owners LGTMed the proposal and no API owner formally objected.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/guidelines/api-owners/requirements/index.md b/chromium/docs/website/site/blink/guidelines/api-owners/requirements/index.md deleted file mode 100644 index 8f2e55ffeac..00000000000 --- a/chromium/docs/website/site/blink/guidelines/api-owners/requirements/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/guidelines - - Guidelines and Policies -- - /blink/guidelines/api-owners - - Blink API owners -page_name: requirements -title: Blink API owner requirements ---- - -## Requirements for API owners - -* Chromium contributor in good standing, with a commitment to [Blink’s - mission](/blink), [core values](/blink/guidelines/values), and - [values in - practice](/blink/guidelines/web-platform-changes-guidelines) -* The person's organizational affiliations must be compatible with API - owners service as regards [CLA - status](/developers/contributing-code/external-contributor-checklist) -* Commitment of 1-2 hours per week to review intents, in addition to - the API owners meetings -* Demonstrated understanding of the Blink Launch Process \[Evidence: - Shipped APIs following this process\] - * Internalized the principles and emulated them. \[Evidence: links - to their own Intents with discussion threads highlighting how - things like interop, compat were tackled\] -* Demonstrated knowledge and ability to review Web Platform features. - \[Evidence example: Input/guidance on 10+ blink intent threads over - the past 6 months\] - -### Optional, but desirable qualifications - -* Mentored other teams through the API process. \[Evidence: Mentorship - feedback/notes, links to threads they chimed in on, that were not - their own intents\] -* Contributed to improving the API process. \[Evidence: Process - improvement proposals, process documentation\] -* Experience navigating disagreements/contention. \[Evidence: Examples - of such discussions on any public forums, not necessarily Blink - intents\] - -Becoming an API Owner - -* Candidates that meet the qualifications can be nominated by a - current API owners to the rest of the API owners group. -* A candidate may also self-nominate via communication to - blink-api-owners@chromium.org (a mailing list with only the API - owners subscribed to it), or to one or more of the API owners. -* The nomination should include an explanation as to why the candidate - meets the criteria above, including links to evidence to that - effect. -* A nominee will be appointed to be an API owners once the nomination - gets 3 LGTMs and no objections. -* Once the nomination is approved, an email will be sent to the - blink-dev mailing list announcing it. If it is rejected, a private - email with explanation will be sent to the nominee. -* Consideration of nominations will happen in a timely manner.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/guidelines/blink-api-owners-requirements/index.md b/chromium/docs/website/site/blink/guidelines/blink-api-owners-requirements/index.md deleted file mode 100644 index e2b2c8ba83c..00000000000 --- a/chromium/docs/website/site/blink/guidelines/blink-api-owners-requirements/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/guidelines - - Guidelines and Policies -page_name: blink-api-owners-requirements -title: Blink API OWNERS Requirements ---- - -## Requirements for API owners - -### <table> -### <tr> - - ### <td>Chromium contributor in good standing, with a commitment to <a - href="/blink">Blink’s mission</a>: To improve the open web through technical - innovation and good citizenship</td> - -* ### <td>The person's organizational affiliations must be compatible - with API owners service as regards <a - href="/developers/contributing-code/external-contributor-checklist">CLA - status</a></td> - - ### <td>Commitment of 1-2 hours per week to review intents, in addition to - the API owners meetings</td> - - ### <td>Demonstrated understanding of the Blink Launch Process \[Evidence: - Shipped APIs following this process\]</td> - - ### <td>Internalized the principles and emulated them. \[Evidence: links - to their own Intents with discussion threads highlighting how things - like interop, compat were tackled\]</td> - - ### <td>Demonstrated knowledge and ability to review Web Platform features. - \[Evidence example: Input/guidance on 10+ blink intent threads over the past - 6 months\]</td> - -### </tr> -### </table> - -### Optional, but desirable qualifications - -### <table> -### <tr> - - ### <td>Mentored other teams through the API process. \[Evidence: Mentorship - feedback/notes, links to threads they chimed in on, that were not their own - intents\]</td> - - ### <td>Contributed to improving the API process. \[Evidence: Process - improvement proposals, process documentation\]</td> - - ### <td>Experience navigating disagreements/contention. \[Evidence: Examples - of such discussions on any public forums, not necessarily Blink - intents\]</td> - -### <td>Becoming an API Owner</td> - -* ### <td>Candidates that meet the qualifications can be nominated by - a current API owners to the rest of the API owners group.</td> -* ### <td>A candidate may also self-nominate via communication to - blink-api-owners@chromium.org (a mailing list with only the API - owners subscribed to it), or to one or more of the API owners.</td> -* ### <td>The nomination should include an explanation as to why the - candidate meets the criteria above, including links to evidence to - that effect.</td> -* ### <td>A nominee will be appointed to be an API owners once the - nomination gets 3 LGTMs and no objections.</td> -* ### <td>Once the nomination is approved, an email will be sent to - the blink-dev mailing list announcing it. If it is rejected, a - private email with explanation will be sent to the nominee.</td> -* ### <td>Consideration of nominations will happen in a timely - manner.</td> - -### </tr> -### </table>
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/guidelines/index.md b/chromium/docs/website/site/blink/guidelines/index.md deleted file mode 100644 index c95e99c769f..00000000000 --- a/chromium/docs/website/site/blink/guidelines/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: guidelines -title: Guidelines and Policies ---- - -{% subpages collections.all %} diff --git a/chromium/docs/website/site/blink/guidelines/values/index.md b/chromium/docs/website/site/blink/guidelines/values/index.md deleted file mode 100644 index dd8abca6065..00000000000 --- a/chromium/docs/website/site/blink/guidelines/values/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/guidelines - - Guidelines and Policies -page_name: values -title: Core Values of Blink ---- - -*See also: [Blink Values in -Practice](/blink/guidelines/web-platform-changes-guidelines)* - -The core values of Blink, from which all of our actions and prioritize should -derive, are: - -#### Promoting a useful and thriving web - -We take action to improve the web over time to be more useful to users. This -primarily takes the form of shipping new features that web developers leverage. - -#### Being a good user agent - -The actions we take respect the [priority of -constituencies](https://w3ctag.github.io/design-principles/#priority-of-constituencies): -users first, over web developers, over browser developers, over specification -authors, over theoretical purity. - -#### Safeguarding the openness of the web - -We take action to maintain and strengthen the openness of the web platform, -which we define as: - -* Non-proprietary -* Based on an open, consensus-seeking standards process -* Inclusive and diverse
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/guidelines/web-exposed/index.md b/chromium/docs/website/site/blink/guidelines/web-exposed/index.md deleted file mode 100644 index 83d5669ec56..00000000000 --- a/chromium/docs/website/site/blink/guidelines/web-exposed/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/guidelines - - Guidelines and Policies -page_name: web-exposed -title: Definition of a web-exposed change to Chromium ---- - -Web-exposed is defined as **affecting web API behavior to the point that -developers using that API need to be aware of it**. - -Changes that are web-exposed: - -* Any change that adds a new API, or in general modifies any IDL file - to change what APIs developers see. -* Removal of some or all of an API. - -Cases that are usually not web-exposed: - -* Fixing a bug in the implementation to conform better with a defined - specification. - -Cases that might or might not be web-exposed: - -* Fixing a broken implementation in a way that may break significant - numbers of sites.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/guidelines/web-platform-changes-guidelines/index.md b/chromium/docs/website/site/blink/guidelines/web-platform-changes-guidelines/index.md deleted file mode 100644 index a595f5fbb9f..00000000000 --- a/chromium/docs/website/site/blink/guidelines/web-platform-changes-guidelines/index.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/guidelines - - Guidelines and Policies -page_name: web-platform-changes-guidelines -title: Blink Values in Practice ---- - -## Introduction - -The Blink project's [core values](/blink/guidelines/values) are to promote a -useful and thriving web, while being a good user agent and safeguarding the -openness of the web. We do this by shipping features that bring user benefit. - -Unlike many other platforms, the web has multiple implementations. The Blink -project's primary lever for improving the experience of web users is by -improving Chromium, and thus shipping (or unshipping) features to our users -directly. But we strive to do so in a way that also helps other implementations. -This increases the interoperable surface area of the web, which improves the -experience of those users we do not directly serve, and helps safeguard the -web's open nature. - -The Chromium project has been blessed with a large ecosystem of active -contributors. As such, we can take on the responsibility of proving out features -in our engine first, trialing them with users of Blink-based browsers ahead of -general deployment across all engines and to more web users. While we do so, it -is imperative that we deliver the feature in a way that invites broad feedback, -and makes it easy for other engines to implement if they decide the proposal is -valuable for their users. - -This document outlines how the Blink project thinks about moving the web -forward, and the reasoning behind the various processes and requirements we -place on members of the Chromium community as part of the [launch -process](/blink/launching-features) that puts our values into practice. - -## Finding balance - -For all browser developers, there is an inherent tension between moving the web -forward and preserving interoperability and compatibility. On the one hand, the -web platform API surface must evolve to stay relevant. On the other hand, the -web's primary strength is its reach, which is largely a function of -interoperability. And by definition, when any browser ships a new feature, the -API change is not yet interoperable. So we need to balance some key risks while -we improve the web platform. - -Interoperability risk is the risk that browsers will not eventually converge on -an interoperable implementation of the proposed feature. Interoperability cannot -be determined only at a given point in time; since browsers ship features at -different times, there is always a degree of non-interoperability on the web. -Instead, we are concerned with long-term interoperability risk, which we -forecast by observing the public behaviors of others in the web ecosystem, and -we work to minimize via the launch artifacts discussed below. See the [Blink -principles of -interoperability](https://docs.google.com/document/d/1romO1kHzpcwTwPsCzrkNWlh0bBXBwHfUsCt98-CNzkY/edit) -for a more in-depth discussion. - -Compatibility risk is the likelihood that a change will break existing web -content loaded in Chromium. Compatibility risk is especially common with API -removal, but it is also a factor when adding new features: before shipping, we -need to be as sure as we reasonably can that the feature will not change or -evolve in backward-incompatible ways in the future, as such incompatible changes -cause direct harm to our users. Additionally, there can be cases where even new -features interact with old ones to cause [strange compatibility -issues](https://groups.google.com/a/chromium.org/g/blink-dev/c/BytHPljnifk/m/PiKCn3Ix6IIJ). -See the [Blink principles of web -compatibility](https://docs.google.com/document/d/1RC-pBBvsazYfCNNUSkPqAVpSpNJ96U8trhNkfV0v9fk/edit) -and [Web compat analysis tools](/blink/platform-predictability/compat-tools) for -more on this subject. - -In an ideal world, all changes would both dramatically move the web forward, and -involve zero interoperability and compatibility risk. In practice, this is -rarely the case, and a tradeoff needs to be made: - -* If a change has low interop/compat risk and significantly moves the web - forward, Chromium welcomes it. (Example: [shipping CSS - Grid](https://groups.google.com/a/chromium.org/g/blink-dev/c/hBx1ffTS9CQ/m/TMTigaDIAgAJ).) - -* If a change has low interop/compat risk but isn't expected to significantly - move the web forward, Chromium usually still welcomes it. (Example: [moving - prefixed event handler properties - around](https://groups.google.com/a/chromium.org/g/blink-dev/c/4Fidt4JqkTk).) - Occasionally, Chromium will reject changes in this bucket to avoid technical - complexity (e.g., removing our implementation of [KV - Storage](https://www.chromestatus.com/features/6428344899862528)). - -* If a change has high interop/compat risk and isn't expected to significantly - move the web forward, Chromium will usually not welcome it. (Example: [not - shipping canvas - supportsContext](https://groups.google.com/a/chromium.org/g/blink-dev/c/n1LP6cE2or4).) - -* If a change has high interop/compat risk but is expected to significantly - move the web forward, Chromium will sometimes welcome it after a careful, - publicly-considered explanation, accompanied by the artifacts discussed - below. (Example: [shipping - WebUSB](https://groups.google.com/a/chromium.org/g/blink-dev/c/KuXx_k2KIis).) - -## The role of the API OWNERS - -To find this balance and resolve the above tradeoffs on a per-change basis, -Chromium delegates to a trusted group, the [Blink API -OWNERS](https://source.chromium.org/chromium/chromium/src/+/HEAD:third_party/blink/API_OWNERS), -to decide what web platform features are delivered to our users. Concretely, -they are the final approvers in the [Blink process](/blink/launching-features), -where Chromium contributors present a series of artifacts as part of their -Intent to Prototype/Experiment/Ship. - -These artifacts are a key part of the process, and much of the rest of this -document is spent detailing them and why we think they are important enough to -make them requirements before shipping a feature. Because of the amount of -resources committed to driving the web forward through Chromium, we accept that -the bar should be higher for us—we can't expect, time and again, that the burden -of designing new features will be split equally with others. So, we need to do -as much as we can to set up and encourage others to participate. - -We have not always done this perfectly in the past, and to be honest, it’s -unlikely we’ll always do it perfectly in the future. But we commit to trying to -work well with others—even when we are implementing features ahead of others. - -## Launch artifacts that Chromium values - -### Explainers - -[Explainers](https://tag.w3.org/explainers) are a proposal's first contact -with the world. Well-written and comprehensive explainers help other interested -parties judge the value of a feature, by presenting the use cases, the research, -and the tradeoffs involved in the design space. Notably, an explainer needs to -assume minimal previous domain knowledge in order to serve these goals well. - -In particular, an explainer should present a living record of: - -* What problem we are solving. - -* Why we think that problem is important to solve. - -* What the impact of solving the problem would be. - -* Over time, the explainer will develop a specific solution proposal, with - supporting arguments for why that proposal is the best among alternatives. - -* Detailed discussion of any concerns raised by other implementers or by - wide-review groups, summing up any open questions or conclusions reached. - (This often ends up in the "FAQ" or "Alternatives considered" sections, or - in other natural locations like the "Security and privacy considerations".) - -Explainers should be documents that other implementers can easily read or skim -to figure out whether they think a feature is worth investing in. If these other -implementers have the time to do so, an explainer repository also serves as an -entry point for them to engage in the early design process. Such early -engagement is excellent news: it increases the chance of the feature launching -to other engines' users, sooner. - -### Specifications - -A good specification is critical to other implementations being able to -interoperably implement a feature, and to that feature eventually reaching users -of those other implementations. Although our code is open source, and in theory -anyone could implement based on it, good specifications have the following -benefits: - -* Specifications operate at a higher level than source code, using - implementation-agnostic abstractions. Thus, an implementer working on any - implementation can read a specification and understand how it would map to - their implementation, separate from the Chromium one. - -* Similarly, specifications are reviewable by non-implementers, including web - developers and groups providing wide review. Writing a specification makes - it easier to capture the input of such groups. - -* Writing a specification crystalizes what the intended behavior is, separate - from the implemented behavior. - -* Specifications provide a mechanism for IPR coverage. The amount of coverage - varies depending on specification venue, but most venues at the very least - guarantee that the specification writers' organization grants a patent - license to implement the specification. - -***Note:** the venue for a specification, and whether it is a "specification" -(individual unofficial draft, W3C CG draft, TC39 stage 2...) or a "standard" -(W3C Recommendation, WHATWG Living Standard, Ecma Standard, ...), only impacts -the last of these bullet points. As such, it's most important that we write a -good specification. The venue and formal status are helpful for gathering IPR -coverage, but otherwise should not be a focus.* - -As such, Chromium developers must ensure that any feature they intend to ship is -backed by a complete and thorough specification. This specification must be at -the level of detail that the feature can be interoperably implemented in a -second engine, should that engine want to bring the feature in question to their -users. - -Getting this right can be difficult. Generally, a prototype implementation comes -before a specification, since it is easier to iterate on the prototype and -gather real-world feedback that way. If such prototyping drastically changes the -shape of the feature, or results in scrapping the feature altogether, this can -save a lot of specification-writing time! - -But this ordering does have one disadvantage. Since there was never a point at -which the Chromium engineer implemented the feature from scratch, following the -specification, we never get a formal check that the specification is complete -and detailed enough. This can lead to problems where, when a second -implementation *does* try to implement from scratch, they find the specification -incomplete, or find that the specification relies on Chromium-specific -assumptions. - -To help address this, we have the [Chromium Specification -Mentors](/blink/spec-mentors) program, which pairs Chromium developers with a -trusted mentor to get a second set of eyes. - -Finally, the most important part of specification writing is to keep up active -maintenance of the specification even after Chromium ships the feature. This is -especially true if a second implementer starts implementing and filing bugs -based on their experience. - -### Tests - -By contributing [web platform tests](https://github.com/web-platform-tests/wpt) -for our proposals, we create a machine-checkable subset of the specification. In -practice, this is essential to achieving interoperable implementations, as well -as ensuring compatibility through preventing regressions. Of note is the -[wpt.fyi](https://wpt.fyi/) dashboard, which enables in-depth comparison of -cross-browser results and a resulting drive toward interoperability. - -Additionally, by devoting the Chromium project's resources to writing web -platform tests, we ensure that other implementations have a ready-made test -suite when they go to implement the feature. This is excellent leverage: we can -invest our resources in writing the tests, but they can be used by all future -implementations as well, almost for free. - -Chromium developers should strive for high levels of coverage for their -feature's web platform tests suite. Ideally, something like 100% coverage of -both "spec lines" and Chromium code would ensure that Chromium implements the -spec faithfully, and that others will be able to leverage the tests to implement -the spec in the same way. Some sample test suites which approach this goal -include -[url/](https://wpt.fyi/results/url?label=master&label=experimental&aligned), -[streams/](https://wpt.fyi/results/streams?label=master&label=experimental&aligned), -and -[pointerevents/](https://wpt.fyi/results/pointerevents?label=master&label=experimental&aligned). - -In practice, this is a hard goal to reach. We can try to approach it by -[annotating specifications](https://tabatkins.github.io/bikeshed/#wpt-element) -with their associated tests, and running the appropriate Chromium [code coverage -tools](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/code_coverage.md). -Another hurdle is that some things are [not -testable](https://github.com/web-platform-tests/wpt/issues?q=is%3Aopen+is%3Aissue+label%3Atype%3Auntestable) -with current infrastructure. We have a dedicated team, -[ecosystem-infra@chromium.org](https://groups.google.com/a/chromium.org/g/ecosystem-infra), -which works to improve our testing infrastructure and mitigate such gaps. - -### Web developer and end user feedback - -The best evidence for the value of a feature is testimonials or data from users -and web developers. Before launch, these can be gathered in a variety of ways, -including [Dev -Trials](https://docs.google.com/document/d/1_FDhuZA_C6iY5bop-bjlPl3pFiqu8oFvuK1jzAcyWKU/edit), -[Origin Trials](https://github.com/GoogleChrome/OriginTrials), or direct user -and developer engagement in venues like the Chromium or specification issue -tracker. After launch, metrics such as [use -counters](https://www.chromestatus.com/metrics/feature/popularity) can show how -much uptake a feature is getting in the wild. - -Collating this information together for easy consumption is an important final -step in the process before shipping. The goal is to present a body of evidence -that makes it easy for other engines to evaluate whether they would like to -bring the proposal to their implementation, or not. - -### Wide review - -There are specific groups, usually in the specification ecosystem, which are -dedicated to reviewing feature proposals. The [W3C -TAG](https://github.com/w3ctag/design-reviews/) is one such group, whose reviews -have a formal place in the Blink launch process. But the more such reviews we -can gather, the better. - -Other groups to consider are: - -* Relevant working groups or specification editors, e.g. the CSSWG for CSS - feature proposals; the HTML Standard editors for HTML feature proposals; - etc. - -* Cross-functional W3C groups such as the [Internationalization - WG](https://www.w3.org/International/core/Overview), [Privacy - IG](https://www.w3.org/Privacy/IG/), or [APA - WG](https://www.w3.org/2018/08/apa-charter). - -* Chromium cross-functional review groups, such as the - [security](/Home/chromium-security), privacy, permissions, and anti-tracking - teams. - -* Directly reaching out to other browser engine implementers or standards - engineers for their [signals](https://docs.google.com/document/d/1xkHRXnFS8GDqZi7E0SSbR3a7CZsGScdxPUWBsNgo-oo/edit). - -None of these groups are obligated to respond; many are busy with other reviews -or with their own work. But we always attempt to reach out, and respond to any -concerns or questions raised. And then we work to capture any answers, or -resultant changes, in a permanent location like the specification or explainer. - -## Conclusion - -Notably, these guidelines do not have an explicit requirement that a feature be -standardized (as opposed to specified), or that a feature have multi-implementer -consensus. Instead, factors like those are inputs into the overall evaluation. -Indeed, all engines implement features ahead of others, or ahead of formal -standardization. (See the "Browser-Specific" section of the [Web API Confluence -Dashboard](https://web-confluence.appspot.com/#!/confluence)). But our process -requires significant up-front investment from Chromium contributors before a -feature is considered ready to ship, to help promote our -[values](/blink/guidelines/values). - -Even if other browsers have not yet implemented a feature, these artifacts are -important to the Chromium project. Creating solid explainers, specs, and tests, -and gathering feedback and wide review, can move us toward future -interoperability, and decrease the risk in the eyes of the API OWNERS. Indeed, -even if other browsers are *opposed* to a feature, by taking the steps above, we -can confidently state that we minimized risk, and layed out a well-lit path in -case the other browsers change their evaluation or their priorities in the -future. This shows that in addition to a feature promoting a useful and thriving -web, and being designed well with respect to the priority of constituencies, we -have made a strong effort to ensure the feature upholds the web's open nature as -well.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/guidelines/web-platform-changes-process/index.md b/chromium/docs/website/site/blink/guidelines/web-platform-changes-process/index.md deleted file mode 100644 index a694dde54c0..00000000000 --- a/chromium/docs/website/site/blink/guidelines/web-platform-changes-process/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/guidelines - - Guidelines and Policies -page_name: web-platform-changes-process -title: 'Web Platform Changes: Process' ---- - -### [See here](/blink/launching-features)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/how-repaint-works/index.md b/chromium/docs/website/site/blink/how-repaint-works/index.md deleted file mode 100644 index a4bf6adbd16..00000000000 --- a/chromium/docs/website/site/blink/how-repaint-works/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: how-repaint-works -title: How repaint works ---- - -Moved to -<https://docs.google.com/a/chromium.org/document/d/1jxbw-g65ox8BVtPUZajcTvzqNcm5fFnxdi4wbKq-QlY/edit#> - -#### How repaint works
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/importing-the-w3c-tests/index.md b/chromium/docs/website/site/blink/importing-the-w3c-tests/index.md deleted file mode 100644 index d00a689df0f..00000000000 --- a/chromium/docs/website/site/blink/importing-the-w3c-tests/index.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: importing-the-w3c-tests -title: Working with web-platform-tests in blink ---- - -## OBSOLETE - -**See -[here](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/web_platform_tests.md) -instead** - -[TOC] - -Interoperability between browsers is [critical](/blink/platform-predictability) -to chromium's mission of improving the web. We believe that leveraging and -contributing to a shared test suite is one of the most important tools in -achieving interoperability between browsers. The [web-platform-tests -repository](https://github.com/w3c/web-platform-tests) is the primary shared -test suite where all browser engines are collaborating. - -Chromium has mirrors -([web-platform-tests](https://chromium.googlesource.com/external/w3c/web-platform-tests/), -[csswg-test](https://chromium.googlesource.com/external/w3c/csswg-test/)) of the -GitHub repos, and regularly (at least daily) imports a subset of the tests so -that they are run as part of the regular Blink layout test testing process. - -Note that currently the main reason we do not run more of the W3C tests is -because they are (probably) mostly redundant with Blink's existing tests, and so -we would double the running time of the layout tests for little benefit. Ideally -we would identify the tests that are redundant and remove Blink's copies, so -that we run just the W3C tests where possible. - -The end goals for this whole process are to: - -1. Be able to run the W3C tests unmodified locally just as easily as we - can run the Blink tests -2. Ensure that we are tracking tip-of-tree in the W3C repositories as - closely as possible -3. Run as many of the W3C tests as possible - -## Automatic Import Process - -There is an automatic [w3c-test-autoroller -bot](https://build.chromium.org/p/chromium.infra.cron/builders/w3c-test-autoroller) -for regularly updating our local copies of web-platform-tests. -[w3c_test_autroller -recipe](https://cs.chromium.org/chromium/infra/recipes/recipes/w3c_test_autoroller.py). - -```none -Tools/Scripts/wpt-import --auto-import wpt -Tools/Scripts/wpt-import --auto-import css -``` - -## Manually Importing New W3C Tests - -Updating the set of tests run by Blink requires commit access to Chromium like -anything else, so make sure you have that first. - -We control which tests are imported via -[LayoutTests/W3CImportExpectations](https://code.google.com/p/chromium/codesearch?q=W3CImportExpectations#chromium/src/third_party/WebKit/LayoutTests/W3CImportExpectations), -which has a list of directories to skip during import. This means that any new -tests and directories that show up in the W3C repos are automatically imported. - -To pull the latest versions of the tests that are currently being imported -(i.e., you don't need to change the blocklist), all you have to do is run: - -```none -Tools/Scripts/wpt-import wpt -Tools/Scripts/wpt-import css -``` - -That script will pull the latest version of the tests from our mirrors of the -W3C repos. If any new versions of tests are found, they will be committed -locally to your local repository. You may then upload the changes. - -If you wish to add more tests (by un-skipping some of the directories currently -skipped in -[W3CImportExpectations](https://code.google.com/p/chromium/codesearch?q=W3CImportExpectations#chromium/src/third_party/WebKit/LayoutTests/W3CImportExpectations)), -you can modify that file locally and commit it, and on the next auto-import, the -new tests should be imported. If you want to import immediately, you can also -run wpt-import --allow-local-commits. - -## Contributing Blink tests back to the W3C - -### If you need to make changes to [Web Platform Tests](https://github.com/w3c/web-platform-tests), just commit your changes directly to our version in [LayoutTests/external/wpt](https://cs.chromium.org/chromium/src/third_party/WebKit/LayoutTests/external/wpt/) and the changes will be automatically upstreamed within 24 hours. - -Note: if you’re adding a new test in external/wpt, you’ll need to re-generate -MANIFEST.json manually until <https://crrev.com/2644783003> is landed. The -command to do so is: - -```none -third_party/WebKit/Tools/Scripts/webkitpy/thirdparty/wpt/wpt/manifest \ -``` - -```none ---work \ -``` - -```none ---tests-root=third_party/WebKit/LayoutTests/external/wpt -``` - -### Where can I find the code for the WPT import and export tools? - - Exporter: - [//third_party/WebKit/Tools/Scripts/wpt-export](https://cs.chromium.org/chromium/src/third_party/WebKit/Tools/Scripts/wpt-export) - - Importer: - [//third_party/WebKit/Tools/Scripts/wpt-import](https://cs.chromium.org/chromium/src/third_party/WebKit/Tools/Scripts/wpt-import) - - Libraries: - [//third_party/WebKit/Tools/Scripts/webkitpy/w3c/](https://cs.chromium.org/chromium/src/third_party/WebKit/Tools/Scripts/webkitpy/w3c/?q=local_wpt&sq=package:chromium) - -### Will the exported commits be linked to my GitHub profile? - -The email you commit with (e.g. user@chromium.org) will be the author of the -commit on GitHub. You can [add it as a secondary address on your GitHub -account](https://help.github.com/articles/adding-an-email-address-to-your-github-account/) -to link your exported commits to your GitHub profile. - -### What if there are conflicts? - -This cannot be avoided entirely as the two repositories are independent, but -should be rare with frequent imports and exports. When it does happen, manual -intervention will be needed and in non-trivial cases you may be asked to help -resolve the conflict. - -### Direct pull requests - -It's still possible to make direct pull requests to web-platform-tests. The -processes for getting new tests committed the W3C repos are at -<http://testthewebforward.org/docs/>. Some specifics are at -<http://testthewebforward.org/docs/github-101.html>.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/index.md b/chromium/docs/website/site/blink/index.md deleted file mode 100644 index 5bb3c45ac85..00000000000 --- a/chromium/docs/website/site/blink/index.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -breadcrumbs: [] -page_name: blink -title: Blink (Rendering Engine) ---- - -[TOC] - -## Mission - -Make the Web the premier platform for experiencing the world’s information and -deliver the world’s best implementation of the Web platform. - -## What is Blink? - -Blink is the name of the [rendering -engine](https://en.wikipedia.org/wiki/Web_browser_engine) used by Chromium and -particularly refers to the code living under -***[src/third_party/blink](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/).*** - -## Participating - -[Chromium](http://chromium.org) is an -[inclusive](https://chromium.googlesource.com/chromium/src/+/HEAD/CODE_OF_CONDUCT.md) -open-source community that values fostering a supportive culture. - -### Discussions - -We value transparency and open collaboration. Our goal is for everyone to be -able to participate, regardless of organizational affiliation. There are several -areas where developer discussions take place: - -* [blink-dev@chromium.org](https://groups.google.com/a/chromium.org/group/blink-dev/topics) - is the general list for discussions relevant to the design and - implementation of web platform features. -* Technical Discussion Groups - - [Groups](/developers/technical-discussion-groups) dedicated to the - discussion of specific areas of the codebase. -* Slack (#blink): We hang out on the #blink channel on - [chromium.slack.com](https://chromium.slack.com) to have quick, - informal discussions and answer questions. - -### Reporting Issues - -We use Chromium's [issue -tracker](https://bugs.chromium.org/p/chromium/issues/list) (aka -[crbug.com](http://crbug.com)). Web Platform issues live under components in -[Blink](https://bugs.chromium.org/p/chromium/issues/list?q=component%3Ablink&can=2) -and -[Internals](https://bugs.chromium.org/p/chromium/issues/list?q=component%3Ainternals&can=2). - -### Tracking features - -For developers interested in tracking new features, there are several dedicated -channels for staying up-to-date: - -* [Beta Blog Posts](https://blog.chromium.org/search/label/beta): For - each new Chrome Beta release (~every six weeks), the Chrome team - publishes [blog posts](https://blog.chromium.org/search/label/beta) - outlining the changes to the web platform and the Chrome Apps & - Extensions APIs. -* Chrome Developer Relations: Chrome DevRel posts about new features - on [web.dev](https://web.dev/), Twitter - ([@ChromiumDev](https://twitter.com/ChromiumDev)), and - [YouTube](https://www.youtube.com/user/ChromeDevelopers/) (Google - Chrome Developers channel). -* [chromestatus.com](https://www.chromestatus.com/): A dashboard where - we track new feature development. -* [bit.ly/blinkintents](https://bit.ly/blinkintents): A Google - Spreadsheet that lists all ["Intent" - threads](/blink#TOC-Web-Platform-Changes:-Process) and their - approval status. - -## Developing - -### Learning about Blink Development - -Blink is implemented on top of an abstract platform and thus cannot be run by -itself. The [Chromium Content module](/developers/content-module) provides the -implementation of this abstract platform required for running Blink. - -* [How Blink - works](https://docs.google.com/document/d/1aitSOucL0VHZa9Z2vbRJSyAIsAz24kX8LFByQ5xQnUg) - is a high-level overview of Blink architecture. -* [Chromium Content module](/developers/content-module) - Details on - the abstract platform required to run Blink. -* [Getting Started with Blink - Debugging](/blink/getting-started-with-blink-debugging) - Best - practices on how to debug Blink (using Content Shell). -* [Chromium Development](/developers) - Guides and best practices for - Chromium development -* YouTube ([Chrome - University](https://www.youtube.com/playlist?list=PLNYkxOF6rcICgS7eFJrGDhMBwWtdTgzpx) - Playlist) - Introductory lessons that cover the fundamental concepts - for Chromium development. - -### Committing and reviewing code - -Blink follows all standard [Chromium](/developers) practices, including those on -[contributing -code](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/contributing.md) -and [becoming a committer](/getting-involved/become-a-committer). Code living in -*[src/third_party/blink](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/)* -follows the [Blink Coding Style Guidelines](/blink/coding-style). - -### Launching and Removing Features - -* [How we think about making changes to the - platform](/blink/guidelines/web-platform-changes-guidelines) -* [Launching a Web Platform Feature](/blink/launching-features) -* [Removing a Web Platform Feature](/blink/deprecating-features) -* (Video) [Intent to Explain: Demystifying the Blink shipping - process](https://www.youtube.com/watch?v=y3EZx_b-7tk) - -### Page Directory - -{% subpages collections.all %} diff --git a/chromium/docs/website/site/blink/intent-security-triage/index.md b/chromium/docs/website/site/blink/intent-security-triage/index.md deleted file mode 100644 index e5efee9249d..00000000000 --- a/chromium/docs/website/site/blink/intent-security-triage/index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: intent-security-triage -title: '"Intent to {Implement,Ship}" Security Triage' ---- - -Blink's [launch process](/blink#TOC-Web-Platform-Changes:-Process) ensures that -interesting features show up as "Intent" threads on the -[blink-dev@chromium.org](https://groups.google.com/a/chromium.org/group/blink-dev/topics) -mailing list. These threads provide a forum for discussion of new features, and -go/no-go decisions from API OWNERS, and are a pretty comprehensive view of the -feature set that we're planning on providing to developers. - -Feature owners generally want the security team to sign off on features before -shipping them to the web, and benefit from a contact they can poke with security -questions. To that end, it behooves us to proactively skim through these threads -to give feedback early, when it's easily actionable. That's where you come in, -you wonderful security-minded person, you: - -## Triage Workflow - - Visit <https://bit.ly/blinkintents> and find the as-yet untriaged "Intent" - threads. - - Read through each feature proposed in an "Intent to Implement" or "Intent to - Implement and Ship" thread, with an eye for security concerns or interesting - side effects that the feature's author might not have considered. - - *Note: we're assuming here that anything at the "Intent to Ship" stage has - gone through wide review, and that deprecation is generally - security-positive. If those turn out not to be reasonable assumptions, we - can reevaluate what threads we care about.* - - If you end up with questions, post them to the thread. In particular, it's a - good idea to encourage developers to include an explicit "Security - Considerations" section in their specification and to read through things - like the TAG's [self-review - questionnaire](https://w3ctag.github.io/security-questionnaire/) (bonus - points for filing spec bugs if there's a clear way to do so). - - If substantial questions are raised, flagging the feature for wider review - before launch is reasonable. This could range from a simple comment on the - launch bug up through preemptively flipping the Launch-Security flag to - "No", depending on how the conversation goes. - - If you determine that a particular feature has no security implications at - all, head over to the launch bug and flip the Launch-Security flag to NA, - along with a comment to that effect. - - At the end of your triage shift, send a report to - [security-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/security-dev) - with a short description of what you looked at, and how it went (the - [net-dev@ triage - thread](https://groups.google.com/a/chromium.org/d/msg/net-dev/zhd-eJLjGi0/9Z-83U6vCAAJ) - is a great model for this). - -## Hello, feature owner! - -This triage rotation is not meant as an approval step. Lack of comments from the -security team on an "Intent" thread should not be interpreted as blanket -approval. It's meant simply as a mechanism to get more eyes on features earlier -in the process, and will hopefully speed up the process of getting those flags -flipped on your important launches.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/launching-features/OWNERS b/chromium/docs/website/site/blink/launching-features/OWNERS deleted file mode 100644 index 78c78a3feb6..00000000000 --- a/chromium/docs/website/site/blink/launching-features/OWNERS +++ /dev/null @@ -1,2 +0,0 @@ -miketaylr@chromium.org -chrishtr@chromium.org diff --git a/chromium/docs/website/site/blink/launching-features/how-chrome-status-communicates/index.md b/chromium/docs/website/site/blink/launching-features/how-chrome-status-communicates/index.md deleted file mode 100644 index 5cbad453452..00000000000 --- a/chromium/docs/website/site/blink/launching-features/how-chrome-status-communicates/index.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/launching-features - - Launching Features -page_name: how-chrome-status-communicates -title: How Chrome Status Communicates with Web Developers ---- - -Chrome Status is the first level of communication with the web development -community about new web platform and related features. Its audience is not, as -many believe, exclusively Chromium engineers. - -# Summary - -Provide one or two complete sentences explaining the feature to web developers -followed by one or two sentences explaining either how it helps web developers -or how it improves the web platform. Do this even if it seems obvious to you. - -* Use complete sentences. -* Exclude returns in the text. They will not be shown in some views. - -Tips: - -* Omit needless words. This is from "[The Elements of - Style](https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X/ref=pd_bxgy_14_img_3?_encoding=UTF8&pd_rd_i=020530902X&pd_rd_r=de87e78e-8526-11e8-914f-9f4b0c666b45&pd_rd_w=mZsdS&pd_rd_wg=bq1yC&pf_rd_i=desktop-dp-sims&pf_rd_m=ATVPDKIKX0DER&pf_rd_p=3914568618330124508&pf_rd_r=KQZKKVTXAZHWAEFD7SR9&pf_rd_s=desktop-dp-sims&pf_rd_t=40701&psc=1&refRID=KQZKKVTXAZHWAEFD7SR9)". - Most people have words in their writing that can be removed without - affecting comprehension or meaning. -* Do not take shortcuts at the cost of clarity. If you cut so many - words the meaning is obscured, then you have gone too far in - omitting needless words. This is also from "The Elements of Style." -* If you absolutely, positively cannot describe your feature in the - space required, continue the description in the comments box. - -# Chromium Status - -**Behind a flag**—Applies to one of two conditions. - -* The flag is listed in chrome://flags AND it is disabled by default. -* The flag is listed in chrome://flags with a value of 'default' and - is disabled by default somewhere in the compiled code. - -Additionally: - -* Origin trials have their own labels. -* This does NOT apply to Finch or test flags. - -**Enabled by default**—Applies to one of three conditions. - -* There is no flag in chrome://flags because the feature is available - to all users. -* The flag is listed in chrome://flags AND it is enabled by default. -* The flag is listed in chrome://flags with a value of 'default' and - is enabled by default somewhere in the compiled code.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/launching-features/index.md b/chromium/docs/website/site/blink/launching-features/index.md deleted file mode 100644 index 47393a09cc4..00000000000 --- a/chromium/docs/website/site/blink/launching-features/index.md +++ /dev/null @@ -1,629 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: launching-features -title: Launching Features ---- - -If you have concerns about your feature not fitting into this process, or any -other questions, general concerns or discussion of this process, please e-mail -[blink-api-owners-discuss@chromium.org](mailto:blink-api-owners-discuss@chromium.org). -If you'd like to provide feedback on this page or the process it describes, -leave feedback on the [Google Doc -draft](https://docs.google.com/document/d/1R_2V5_rukVM8S5Hg2XKxiEOVRxvB7NqZOI2lfni2YwE/edit?usp=sharing) -of this page. - -## Exempt features - -You do not need to use this process if your change does not [affect web API -behavior to the point that developers need to be aware of -it](/blink/guidelines/web-exposed). (e.g. no significant behavioral changes, and -no web-facing API changes.) The rest of this document doesn’t apply to this type -of change, although such features might still have to go through a different -launch process. Large projects should have public design docs that are also -shared on blink-dev@chromium.org (or chromium-dev@, for projects that have -significant parts outside of Blink) for feedback (this is also a good way to get -the attention of other relevant leads). - -## Frequently asked questions - -**Q**: *Do I need any of this if my project is just refactoring or -re-architecting the code? Do the [API owners](/blink/guidelines/api-owners) need -to be involved?* - -**A**: No. The API owners oversee the **process** of shipping [web-exposed](/blink/guidelines/web-exposed) API changes. They are not necessarily leads or -overseers of any of the code. Instead, you should get the buy-in of the leads of -the code areas touched by your project. If there may be side effects of your -change, you should follow the "Architectural change" process below. In addition, -such large projects should have public design docs that are also shared on -[blink-dev@chromium.org](mailto:blink-dev@chromium.org) (or -[chromium-dev@chromium.org](mailto:chromium-dev@chromium.org), for projects that -have significant parts outside of third_party/blink) for feedback (this is also -a good way to get the attention of relevant leads you might not have thought -of). - -For code-related questions, you can email -[platform-architecture-dev@chromium.org](mailto:platform-architecture-dev@chromium.org) -in addition to blink-dev@ as a catch-all option when the code ownership is not -clear or the feature needs large-scale refactoring changes. - -**Q**: *What if I want to add some code to third_party/blink that is for a -non-web-exposed feature? Is that allowed?* - -**A**: In general, no. On a case-by-case basis an exception could be given if -there is no other reasonable way to implement the feature. Ask for permission -from leads of the code area as well as the API owners. (The API owners need to -be involved only to help understand if the feature really is not web-exposed; -this can be a very subtle question.) - -**Q**: *I am not sure of the right approach for my feature. What should I do?* - -**A**: Please reach out to the API owners for help! While they are not -gatekeepers for everything, they are very happy to give advice and unblock your -feature. An email to -[blink-api-owners-discuss@chromium.org](mailto:blink-api-owners-discuss@chromium.org) -is the best way; if a public-facing email is not possible, please email the [API -owners](/blink/guidelines/api-owners) directly. - -## The Feature Types - -The first thing you will need to do is identify what type of feature you are -building: - -### New feature incubation - -This is the normal path when we are incubating and -defining new features from scratch - e.g., most -[Fugu](/teams/web-capabilities-fugu) features follow this pattern, and any -feature where we start without an already-defined standard for the feature. -This also covers changes that are extending existing features (e.g., -defining a new value and behavior for an existing standard feature). This -type of feature has the most associated process steps, as it is charting new -territory. - -### Implementation of existing standard - -This type of feature has a -lighter-weight “fast track” process, but this process can only be used when -the feature has already been defined in a consensus standards document - -e.g. a W3C Working Group has already agreed on the design, it has already -been merged into a WHATWG standard, or the feature has already been -implemented in another engine. - -### Deprecation - -Removal of already-shipped features. - -### Web developer facing change to existing code - -This is generally a public -service announcement- “This is a web-developer-facing change to existing -code without API changes, but you may see side effects.” This may be due to -large-scale code refactoring or rewriting, where the goal is to cause no -behavioral changes (but due to scope of change, side effects are likely), or -this may encompass changes to current code that fix a bug or implement new -changes to the spec without changes to the API shape itself. - -### Changing stages - -It is possible to change types later in the process - for example, if you start -out implementing an already existing standard, but discover you need to incubate -a new API during the process, you can change the feature type and move back -stages. Note that there are few [strictly required gates to the Chromium -process](/blink/guidelines/api-owners/procedures) (e.g., 3 LGTMs from API owners -on an intent-to-ship) - particularly in the earlier stages we want to encourage -experimentation. However, there are required fields for most stages in the -[ChromeStatus tool](https://www.chromestatus.com/), and it’s important to -consider all the steps listed below; this will maximize your chance of success -on an intent-to-ship and reduce the risk of having to redo parts of your design -or implementation. - -## The Chromium process to launch a new feature - -### Step 0: Create a ChromeStatus entry, and choose your feature type. - -For all types of features, the first step is to create a ChromeStatus entry. Go -to <https://www.chromestatus.com/features>, ensure you are logged in (see the -upper right corner), and click “Add new feature”. If you do no have access to -create a new feature, please send an email to -[webstatus-request@google.com](mailto:webstatus-request@google.com) to request -access. Follow the directions to name your feature and give a short summary, and -select the appropriate feature type. - -For Chrome, some launches will require a formal[ Chrome launch -review](https://bugs.chromium.org/p/chromium/issues/entry?template=Chrome+Launch+Feature) -(especially if your feature has security, privacy, legal, or UI implications). -This is the point where you should file a launch bug if this applies to you. We -are working on making this process more open and transparent outside Google. - -From this point on, the process changes a little depending on the type of -feature you’re adding. - -### For New Feature Incubations - -#### Step 1: Incubating: Write up use cases and scenarios in an explainer - -Press the "Start" button next to "Start Incubating", fill out the “Motivation” -section with a brief summary, and then write up the use cases and scenarios in -an explainer for the feature (typically hosted in a public personal Github repo -in Markdown form) and hit "Submit". - -We have a [program for to provide mentorship for specification -writing](/blink/spec-mentors); If you are a Googler you must file a -[request](https://docs.google.com/forms/d/e/1FAIpQLSfCYE4U13GkZ11rAWBUjOb3Lza-u4m2k3TklQHXe7Zfn3Qo1g/viewform) -for a spec mentor, and ask them to review this early explainer before -proceeding. If you are not a Googler, you are welcome to make use of this but -not required to. - -You can then put a link to your public explainer in the feature entry. You will -then need to publish this explainer, and kick off "standards incubation" by -proposing this to a relevant standards venue (frequently, this means you should -[make a WICG proposal](https://github.com/WICG/admin#contributing-new-proposals) -and start socializing the problem with other vendors and developers. Enter a -reference to the public proposal in “Initial Public Proposal” field; if there is -interest in the WICG proposal and it can be moved into the WICG at this point, -do so. The WICG co-chairs can help you.) It’s also a good idea to discuss your -idea with the team/team lead (TL) or area expert in the feature area, prior to -checking in code in the area. - -Start sketching out a proposed solution in your (public) explainer, detailing -API design (IDL) in your incubation. If you are a Googler, you may wish to -review this with your specification mentor before proceeding. - -#### Step 2: Prototyping - -Proceed to the “Start Prototyping” stage in ChromeStatus - this will generate an -“Intent to Prototype” mail for you. Send that email to -[blink-dev](mailto:blink-dev@chromium.org) and start checking in prototype code -to Chromium under a runtime flag. You should do your detailed API design in the -open, in your public repository, and response to feedback filed there. You -should continue pushing for public engagement (from other vendors and web -developers), and to move into WICG, or other incubation venues, if you haven’t -already. During this stage, you should expand on the explainer with a full -design doc (this may also have implementation-specific details), and consider -creating a specification (or writing up a pull request with changes to an -existing spec). - -Note that any CLs landing at this stage should be [behind a feature -flag](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/platform/RuntimeEnabledFeatures.md). -Consider adding a[ UseCounter](/blink/platform-predictability/compat-tools) to -track usage of your new feature in the wild, and be sure to write integration -tests for your feature as[ -web-platform-tests](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/web_platform_tests.md) -as you go. Continue to work with your API mentor if there are any design -changes. - -Ensure you have an API overview and descriptions for all IDL methods and -properties (these are probably in your specification or explainer, but -developers will need them to try your feature out), and at least a basic sample. - -As soon as you have a functional and reasonably complete implementation of your -initial design ready for developers to try out behind a flag, proceed to the -next step. - -#### Step 3: Feature Complete behind a feature flag: iteration on design - -Once you have a functional and reasonably complete feature implementation -available as a runtime enabled feature, request a -[TAG](https://github.com/w3ctag/design-reviews/issues) review of your design and -proceed to the “Dev Trials” stage in ChromeStatus. This will generate a “Ready -for Trial” email that you should send to -[blink-dev](mailto:blink-dev@chromium.org) to notify the community they can try -out the feature. At this point, you should consider ask other browser vendors -and the web developer community for [signals on their opinion of the -API](https://docs.google.com/document/d/1xkHRXnFS8GDqZi7E0SSbR3a7CZsGScdxPUWBsNgo-oo/edit#heading=h.tgzhprxcmw4u). - -This is the main iterating stage of feature development and helps you assess -product-market-fit early on before you corner yourself (does your API address a -problem with meaningful demand? did we get the ergonomics right?). You may wish -to send more than one Ready for Trial emails, if you make substantial changes to -the API shape while iterating. You should work with the TAG to complete their -review and address any issues raised during this stage, and should address any -issues raised by other horizontal reviews (accessibility, privacy, -internationalization, etc.). - -#### Step 4: Evaluate readiness to ship - -Once you believe you have addressed all major open issues, you should proceed to -the “Evaluating readiness to ship” stage in ChromeStatus. If you haven't already -received [signals on their opinion of the -API](https://docs.google.com/document/d/1xkHRXnFS8GDqZi7E0SSbR3a7CZsGScdxPUWBsNgo-oo/edit#heading=h.tgzhprxcmw4u) -from other browser vendors and the web developer community, now is the time to -pursue getting those signals. - -You should also work with the documentation team to ensure your features will be -documented when shipped, and estimate when (in what milestone) you would like to -target shipping. - -You should also decide if an Origin Trial would help gather significant data for -your feature. - -By this stage, you need to have a complete specification available that matches -what you have implemented. The only exception is if you plan to do an Origin -Trial, and expect that trial feedback could change the shape of the API -significantly or result in it being scrapped altogether. In that case it might -be OK to delay writing a specification until the Origin Trial is underway or -completes. But be careful: writing a good spec can be a lot of work, and -producing a good enough spec to meet the shipping bar can take longer than the -~12-16 weeks of an Origin Trial, so starting the spec-writing process too late -might delay your feature launch. - -#### Step 5 (Optional): Origin Trial - -If you want to gather data on the usability of your feature that an [Origin -Trial](/blink/origin-trials/running-an-origin-trial) can help collect, proceed -to the “Origin Trial” stage in ChromeStatus and fill out the required fields -detailing what you hope to learn from the origin trial. This will generate an -[Intent to -Experiment](https://docs.google.com/document/d/1vlTlsQKThwaX0-lj_iZbVTzyqY7LioqERU8DK3u3XjI/edit) -mail that you should send to [blink-dev](mailto:blink-dev@chromium.org). After -receiving at least [one LGTM](/blink/guidelines/api-owners/procedures) from the -API owners, you can proceed with your origin trial release. Collect data and -respond to any issues. From here, you may wish to return to Dev Trials, proceed -to Prepare to Ship, or park the feature. - -As noted above, a specification is recommended but not required for an Origin -Trial. - -Please note that Origin Trials are not exempt from requiring cross-functional -approvals from the Chrome launch review process. - -Depending on your feature and your experimentation goals, running an experiment -via Finch on a percentage of the stable or beta populations may be useful -([example](https://groups.google.com/a/chromium.org/g/blink-api-owners-discuss/c/WoQvWPCxKdU/m/e93bxrzwAQAJ)). -In these cases, an Intent to Experiment explaining why this non-typical path is -requested and the corresponding LGTM(s) are still required before proceeding. - -#### Step 6: Prepare to Ship - -At this point, if you are a Googler you should get a final spec review from your -standards mentor, and discuss options for moving your spec to a final -standardization venue. You should have TAG sign-off on your API design by now, -or have ongoing discussions on the TAG review without any outstanding major -concerns. You should update ChromeStatus with a target milestone for shipping -(and remember to keep this updated, if things change). You should get final -signoff from Documentation, and update for any changes in vendor signals. - -Proceed to the “Prepare to Ship” stage in ChromeStatus; this will generate an -[Intent to -Ship](https://docs.google.com/document/d/1vlTlsQKThwaX0-lj_iZbVTzyqY7LioqERU8DK3u3XjI/edit#bookmark=id.w8j30a6lypz0) -mail that you should send to [blink-dev](mailto:blink-dev@chromium.org). This -will spark a conversation with the API owners; address any feedback from them, -and once you get [3 LGTMs from the API -owners](/blink/guidelines/api-owners/procedures), you may enable the feature by -default. You can learn more about the policies and guidelines the API owners -evaluate [here](/blink/guidelines). Requirements for new API owners are -[here](/blink/blink-api-owners-requirements). Email -blink-api-owners-discuss@chromium.org or reach out to one of the[ API -owners](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/API_OWNERS) -if there is no open/unaddressed feedback and you are still blocked on LGTMs -after 5 days. - -Once you have shipped your feature, proceed to the "Ship" stage in ChromeStatus. - -The approval status of various stages of the intent process is tracked by the -API owners in [this spreadsheet](https://bit.ly/blinkintents). - -### Implementations of already-defined consensus-based standards - -#### Step 1: Write up use cases and scenarios, start coding - -Fill out the “Motivation” section with a brief summary, and then write up the -use cases and scenarios. If this is a large feature, or a combination of -multiple attributes/properties/methods/events, you may wish to do this in a -separate explainer file. - -Proceed to the “Start Prototyping” stage in ChromeStatus - this will generate an -“Intent to Prototype” mail for you. Send that email to -[blink-dev](mailto:blink-dev@chromium.org) and start checking in prototype code -to Chromium as [runtime enabled features](/blink/runtime-enabled-features). -Ensure there are adequate -[web-platform-tests](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/web_platform_tests.md) -for this feature. Also ensure you have an API overview and descriptions for all -IDL methods and properties (this is probably already in the consensus standard -specification, or even on MDN), and at least a basic sample. - -As soon as you have a functional and reasonably complete implementation of the -feature ready for developers to try out under a flag, proceed to the next step. - -#### Step 2: Feature Complete behind a flag and implementation refinement - -If the TAG has not already reviewed the consensus specification, request a -[TAG](https://github.com/w3ctag/design-reviews/issues) review and proceed to the -“Dev Trials” stage in ChromeStatus. This will generate a “Ready for Trial” email -that you should send to [blink-dev](mailto:blink-dev@chromium.org) to notify the -community they can try out the feature. - -After you have addressed any issues that the community finds, you should proceed -to the “Evaluating readiness to ship” stage in ChromeStatus. You should also -work with the documentation team to ensure your feature will be documented when -shipped, and estimate when (in what milestone) you would like to target -shipping. You should also decide if an Origin Trial would help gather -significant data for your feature. - -#### Step 3 (Optional): Origin Trial - -If you want to gather data on the usability of your feature that an [Origin -Trial](/blink/origin-trials/running-an-origin-trial) can help collect, proceed -to the “Origin Trial” stage in ChromeStatus and fill out the required fields -detailing what you hope to learn from the origin trial. This will generate an -[Intent to -Experiment](https://docs.google.com/document/d/1vlTlsQKThwaX0-lj_iZbVTzyqY7LioqERU8DK3u3XjI/edit) -mail that you should send to [blink-dev](mailto:blink-dev@chromium.org). After -receiving at least [one LGTM](/blink/guidelines/api-owners/procedures) from the -API owners, you can proceed with your origin trial release. Collect data and -respond to any issues. From here, you may wish to return to Dev Trials, proceed -to Prepare to Ship, or park the feature. - -Please note that origin trials are not exempt from requiring cross-functional -approvals from the Chrome launch review process. Details[ -here](/blink/origin-trials/running-an-origin-trial). - -An initial origin trial for a feature may only run for *6 milestones of Chromium*. -Each request to extend beyond that limit may only be for *3 milestones* at a time, -and will not be approved unless substantial progress is demonstrated in all of -these areas: -* Draft spec (early draft is ok, but must be spec-like and associated with the - appropriate standardization venue, or WICG) -* TAG review -* bit.ly/blink-signals requests -* Outreach for feedback from the spec community -* WPT tests - -Each subsequent request to extend an origin trial must provide substantial -*additional* progress on top of the previous extension request. - -[Note: the required breaking period was removed in April 2022. This removal will run -for 12 months, after which the API owners will consider making the change permanent.] -~~If an Origin Trial happens, then there is a [required breaking -period](https://docs.google.com/document/d/1oSlxRwsc8vTUGDGAPU6CaJ8dXRdvCdxvZJGxDp9IC3M/edit#heading=h.r5cdr0aazfpm) -before shipping in step 4. If you wish to skip the breaking period, meaning that -sites participating in the Origin Trial will not see an interruption in support -for the feature between Origin Trial and launch (\*), you may request an -exception. The process to do so is to include this request in your Intent to -Ship email. In the request, you must show clear evidence that developers engaged -with the Origin Trial and that their concerns were taken into account in the -final API design and implementation. LGTMs for the Intent to Ship imply approval -of the request.~~ - -(\*) "Not see an interruption" means that if the origin trial ends at milestone -N, and the feature is shipped in milestone N+1, sites opting into the origin -trial will continue to be able to use the feature on Chromium milestone N up to -(and even after, for those users who have not upgraded) N+1 ships. - -#### Step 4: Prepare to Ship - -You should update ChromeStatus with a target milestone for shipping (and -remember to keep this updated, if things change). You should get final signoff -from Documentation, and update for any changes in vendor signals. - -Proceed to the “Prepare to Ship” stage in ChromeStatus; this will generate an -[Intent to -Ship](https://docs.google.com/document/d/1vlTlsQKThwaX0-lj_iZbVTzyqY7LioqERU8DK3u3XjI/edit#bookmark=id.w8j30a6lypz0) -mail that you should send to [blink-dev](mailto:blink-dev@chromium.org). This -will spark a conversation with the API owners; address any feedback from them, -and once you [get 3 LGTMs](/blink/guidelines/api-owners/procedures) from the API -owners, you may enable the feature by default. See[ -here](/blink/guidelines/web-platform-changes-guidelines) for the principles the -API owners will apply in evaluating whether the feature is mature enough to -ship. (API owners requirements are listed[ -here](/blink/blink-api-owners-requirements) - email -blink-api-owners-discuss@chromium.org or reach out to one of the[ API -owners](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/API_OWNERS) -if no open/unaddressed feedback and you are still blocked on LGTMs after 5 -days.) - -Once you have shipped your feature, proceed to the "Ship" stage in ChromeStatus. - -### Feature deprecations - -#### Lessons from the first years of deprecations and removals ([thread](https://groups.google.com/a/chromium.org/forum/#!topic/blink-dev/1wWhVoKWztY)) - -We should weigh the benefits of removing an API more against the cost it -has. Percent of page views by itself is not the only metric we care about. - -The cost of removing an API is not accurately reflected by the UseCounter -for older, widely implemented APIs. It's more likely that there's a -longer-tail of legacy content that we're breaking. - -We shouldn't remove APIs that have small value on the path towards a removal -that has significant value. Getting rid of attribute nodes \*is\* valuable -and would benefit the platform. Getting rid of half the attribute node -methods is not. So we should evaluate the usage of all the APIs we need to -remove together in order to get there. Also, if we remove them, we should -remove them all in the same release. Breaking people once is better than -breaking them repeatedly in small ways. - -We should be more hesitant to remove older, widely implemented APIs. - -For cases where we're particularly concerned about the compatibility hit, we -should do the removal behind a flag so that we can easily re-enable the API -on stable as we don't know the compat hit until the release has been on -stable for a couple weeks. - -Enterprise users have additional difficulties reacting to breaking changes, -but we also have additional tools to help them. See[ shipping changes that -are enterprise-friendly](/developers/enterprise-changes) for best practices. - -High-usage APIs may require much more work to land successfully. See -[here](https://docs.google.com/document/d/1-_5MagztiYclsMccY4Z66XI465WaasT5I5y2dnhRvoE/edit#heading=h.n49iymp16hl6) -for a good example of how this worked in practice with the deprecation and -removal of the Web Components v0 APIs. - -#### Step 1: Write up motivation - -Deprecations and removals must have strong reasons, explicitly balanced against -the cost of removal. Deprecations should be clear and actionable for developers. -First, read the [guidelines for deprecating a -feature](https://docs.google.com/a/chromium.org/document/d/1LdqUfUILyzM5WEcOgeAWGupQILKrZHidEXrUxevyi_Y/edit?usp=sharing). -Measure feature usage in the wild. [ Various -tools](/blink/platform-predictability/compat-tools) are available, but typically -this is accomplished by simply adding your feature to the[ UseCounter::Feature -enum](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/core/frame/UseCounter.h&sq=package:chromium&type=cs&q=file:UseCounter.h%20Feature) -and adding MeasureAs=<your enum value> to the feature's IDL definition. - -Fill out the “Motivation” section with a brief summary, and then write up the -use cases and scenarios. Proceed to the “Write Up Motivation” stage in -ChromeStatus - this will generate an “Intent to Deprecate and Remove” mail for -you. Send that email to [blink-dev](mailto:blink-dev@chromium.org) and start -checking in your code removing the feature to Chromium as a [runtime enabled -feature](/blink/runtime-enabled-features). Make sure to provide suggested -alternatives to the feature being deprecated. As soon as you have a functional -removal of the feature ready for developers to try out under a flag, proceed to -the next step. - -#### Step 2: Dev trial of deprecation - -Proceed to the “Dev Trials” stage in ChromeStatus. This will generate a “Ready -for Trial” email that you should send to -[blink-dev](mailto:blink-dev@chromium.org) to notify the community they can try -out the feature deprecation. - -At this point, you should also notify developers by adding a deprecation console -message, pointing to the updated status entry in the console message. You should -also continue to measure usage by adding the API to the big switch in[ -UseCounter::deprecationMessage](http://src.chromium.org/viewvc/blink/trunk/Source/core/frame/UseCounter.cpp#l120). -Give developers as many milestones as possible to respond to the deprecation. - -Instrument your code by either adding DeprecateAs=\[your enum value here\] to -the feature's IDL definition.\* -- See window.performance.webkitGetEntries., or -adding a call to UseCounter::countDeprecation somewhere relevant. - -You should work with the documentation team to ensure the community is prepared -for this feature deprecation, and estimate when (in what milestone) you would -like to target shipping. You should also decide (possibly based on data from the -dev trial) if a deprecation trial is going to be necessary to help smooth the -removal of this feature from the web platform. - -#### Step 3 (Optional): Deprecation Trial - -If you are concerned that there are going to be web developers who need -additional time to fix up their implementations, and will want to delay your -feature deprecation, you can file for a [Deprecation -Trial](https://groups.google.com/a/chromium.org/forum/#!msg/blink-api-owners-discuss/uNWSTCUzIcU/0jyBWgLlDgAJ). -This will let you disable the feature by default, but let developers request an -origin trial token to re-enable the feature, for a limited period of time after -the feature deprecation. You will need to decide how long to keep the -deprecation trial open and enter that milestone in the tool for planning -purposes, and then select “Draft Request for Deprecation Trial email” in -ChromeStatus, and send the resulting “Request for Deprecation Trial” email to -[blink-dev](mailto:blink-dev@chromium.org). After receiving at least [one -LGTM](/blink/guidelines/api-owners/procedures) from the API owners, email -[experimentation-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/experimentation-dev) -letting them know you plan to run a deprecation trial, ensure your removal is -integrated with the origin trials framework ([see -details](/blink/origin-trials/running-an-origin-trial#integrate-feature)), and -Googlers can request a trial for their feature at -[go/new-origin-trial](http://goto.google.com/new-origin-trial). Once your -Deprecation Trial is in place, proceed to the next step. - -#### Step 4: Prepare to Ship - -You should update ChromeStatus with a target milestone for deprecating the -feature (and remember to keep this updated, if things change). You should get -final signoff from the Documentation team. - -Proceed to the “Prepare to Ship” stage in ChromeStatus; this will generate an -[Intent to -Ship](https://docs.google.com/document/d/1vlTlsQKThwaX0-lj_iZbVTzyqY7LioqERU8DK3u3XjI/edit#bookmark=id.w8j30a6lypz0) -mail that you should send to [blink-dev](mailto:blink-dev@chromium.org). This -will spark a conversation with the API owners; address any feedback from them, -and once you get [3 LGT](/blink/guidelines/api-owners/procedures)Ms from the API -owners, you may proceed. - -#### Step 5: Disable the feature - -Disable the feature by default. Update ChromeStatus to either “Disabled” or -“Disabled with Deprecation Trial”. - -#### Step 6: Remove Code - -If you are running a Deprecation Trial, wait until the Deprecation Trial period -has ended. (If you need to extend the Deprecation Trial, notify -[experimentation-dev@chromium.org](mailto:experimentation-dev@chromium.org) and -click “Generate an Intent to Extend Deprecation Trial” in ChromeStatus and send -the resulting notification to blink-dev.) - -Once the feature is no longer available, remove the code (typically waiting a -couple of milestone cycles to insure the code is no longer needed), and set the -ChromeStatus to “Removed.” - -If you are unsure of when a feature could be removed, or would like to -discourage usage, you may deprecate a feature without a removal deadline. This -is strongly discouraged and will require significant justification: - -* Email blink-dev using the ["Intent to Deprecate" template](https://docs.google.com/a/chromium.org/document/d/1Z7bbuD5ZMzvvLcUs9kAgYzd65ld80d5-p4Cl2a04bV0/edit). - -* [1 LGTM](/blink/guidelines/api-owners/procedures) necessary from the API owners - -* Must justify why there is no removal date - -\* It takes 12-18 weeks to hit Stable once you enable instrumentation. If there -is time pressure you may be able to get permission to merge UseCounter changes -into an existing dev/beta branch, and make provisional decisions based on data -from beta channel. - -### Web-developer-facing change to existing code (PSA) - -#### Step 1: Write up motivation and implement code - -Fill out the “Motivation” section with a brief summary, and proceed to the -“Implementing” stage in ChromeStatus. - -#### Step 2: (Optional) Dev trial - -If you want to try out this change before shipping it, put your code in Chromium -as [runtime enabled features](/blink/runtime-enabled-features), and set the -status to “Dev Trial” in ChromeStatus. This will generate a “Ready for Trial” -email that you should send to [blink-dev](mailto:blink-dev@chromium.org) to -notify the community they can try out code change. - -#### Step 3: Prepare to Ship - -You should update ChromeStatus with a target milestone for shipping (and -remember to keep this updated, if things change). Proceed to the “Prepare to -Ship” stage in ChromeStatus; this will generate a “Web-Facing Change PSA” mail -for you. Send that email to [blink-dev](mailto:blink-dev@chromium.org) with the -summary of the code change and the expected milestone. - -#### Step 4: (Optional) Finch trial - -You may wish to use [Finch](http://go/finch) to increase confidence in the new -code as you deploy it. - -#### Step 5: Ship - -Ship it, and set the status to “Shipped”. - -## Post Launch - -After launching a new feature, watch for crashes, regressions caused by your -feature and any substantive spec feedback. Review [UseCounter](/blink/platform-predictability/compat-tools) and other metrics. -Update the intent-to-ship thread and ChromeStatus if non-trivial issues -(like web compatibility or serious design questions) arise. When in doubt, -email blink-dev@ (or blink-api-owners-discuss@ if you prefer a smaller -audience) for advice. - -Once a new API is on by default, continue to support other implementations -(for instance, clarifying the spec, improving the tests, fixing bugs, and -updating support status in ChromeStatus) until the feature is broadly -supported and works the same across engines. Remember, your job is to move -the web forward, not simply add features to Chrome. - -Review MDN docs for technical accuracy and clarity. Feel free to make edits -directly or reach out to jmedley@. - -When you are convinced enabling the feature by default has “stuck” -(typically 2 milestones), remove any unused code including -RuntimeEnabledFeatures entries. - -## Related - -For an overview, and explanation of motivations, please see: - -* Video presentation: [Intent to explain: Demystifying the Blink - shipping process (Chrome Dev Summit - 2019)](https://www.youtube.com/watch?v=y3EZx_b-7tk&list=PLNYkxOF6rcIDA1uGhqy45bqlul0VcvKMr&index=17) -* Blog post: [Intent to Explain: Demystifying the Blink Shipping - Process](https://blog.chromium.org/2019/11/intent-to-explain-demystifying-blink.html) diff --git a/chromium/docs/website/site/blink/launching-features/let-developers-know/index.md b/chromium/docs/website/site/blink/launching-features/let-developers-know/index.md deleted file mode 100644 index 67ec6b43bd5..00000000000 --- a/chromium/docs/website/site/blink/launching-features/let-developers-know/index.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/launching-features - - Launching Features -page_name: let-developers-know -title: Let Web Developers Know about New Features ---- - -So, You're Building a Feature. Now what? - -Web developers need to know about it so they can use it. - -Chrome Developer Relations has a process for that, but we need a little help -from you. The big picture is that we use a release blog to post information -about every new developer-facing or developer-affecting feature in every Chrome -beta version. Developer Relations writes articles about some of these features. -(We're not big enough to write about all of them.) This blog attracts the -attention of the tech press. They write news stories about those features and -usually link to our articles. - -If you miss getting your feature mentioned in the beta release post, you miss -the best opportunity to tell the world about what you built. - -# The Process - -1. Write a good Chrome Status description. - This is your first opportunity to communicate to the world what you're - doing. Chrome Status autogenerates an Intent email for you, but the summary - is public. If you write this well, it will appear as-is in the beta release - post later. You can find a few [guidelines - here](/blink/launching-features/how-chrome-status-communicates). -2. Feature freeze (four weeks before beta): Let Developer Relations - know that you plan to ship your feature in the upcoming beta. (See - [Contacts](#Contacts), below.) - **Inform us no matter how small the chance of shipping.** Waiting until you - know for sure does us no favor. Preparing for a released feature at the last - minute is difficult. Holding back text for a feature that wasn't released is - trivial. - If you're not sure that something is shipping you probably shouldn't update - your Chrome Status entry. But you must tell us. Shipping in this case means - available by default or available in an origin trial. It does not mean other - types of flags. -3. You may be asked at some point to review a longer article for - technical accuracy. Developer Relations is a small group. We don't - have the resources to write about everything. - -That's it. **Your communication responsibilities are complete.** If you want to -confirm that something is on our radar follow -[go/what's-shipping](https://docs.google.com/spreadsheets/d/155euqrhdqVhtbAID7ydaUPjBstLIYZ4PJkpFmqJ6j-o/edit#gid=1093066458) -(externally accessible with permission) to see what DevRel already knows about. -(Note: we keep a separate planning doc because so we can track things that may -not be ready for Chrome Status.) - -# What Happens Next? - -Obviously, that's not the end of the story. I threw a bunch of information at -you at the top, which I'll now explain. - -1. Between feature freeze and beta, Chrome Developer Relations creates - [articles](https://web.dev/blog/) and - [videos](https://www.youtube.com/channel/UCnUYZLuoy1rq1aVMwx4aTzw) - about the new features. We also draft a [beta release - post](https://blog.chromium.org/search/label/beta) for the [Chromium - blog](https://blog.chromium.org/). -2. As soon as Chrome beta is released, the beta release post is - published on the Chromium blog. A member of our team tweets a blog - post link to [@ChromiumDev](https://twitter.com/ChromiumDev). - -# What about Non-Google Engineers - -I haven't forgotten that engineers from outside Google work on Chromium. We want -to give proper credit where it is due, but are still working on the most -appropriate way to do this. We still want to let developers know about features -you've built. Please, let us know what you've added to Chromium and we'll make -sure it gets in the beta release post. - -**Frequently Asked Questions** - -**My feature, which adds a missing method or property, is only a bug. Do I need -to tell you?** - -Yes. We need to know everything. - -**My feature is an update to the spec. Do I need to tell you?** - -Yes. We need to know everything. - -**I’m hoping to get 3 LGTMs before beta, but I haven’t written an intent yet. Do -I need to tell you?** - -Yes. We need to know everything. - -(Are detecting a theme yet.) - -**I don’t think I’ll be done until after the branch point, but I’m hoping to -merge to the current beta. Do I need to tell you?** - -Yes. We need to know everything. - -**My feature fixes a regression in a recent version of Chrome. Do I need to tell -you?** - -We don’t need it for the beta release, but we may need to update MDN. Please let -us know anyway. In other words, yes. We need to know everything. - -# Contacts - -Joe Medley - Help with getting the word out on your new feature. -([jmedley@google.com](mailto:jmedley@google.com)) -Paul Kinlan - Head of Developer Relations for Chrome and the web platform. -([paulkinlan@google.com](mailto:paulkinlan@google.com)) -Kayce Basques - Lead technical writer for Chrome and the web platform. -([kayce@google.com](mailto:kayce@google.com))
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/launching-features/old-process/index.md b/chromium/docs/website/site/blink/launching-features/old-process/index.md deleted file mode 100644 index 91efeb416b9..00000000000 --- a/chromium/docs/website/site/blink/launching-features/old-process/index.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/launching-features - - Launching Features -page_name: old-process -title: old-process ---- - -<table> -<tr> - -<td>## \[This documentation is now obsolete! Please refer <a href="/blink/launching-features">here</a> for the current process\]</td> - -<td>## The process to launch a new feature</td> - -<td><b>Note:</b> You can combine the intent-to-implement email with an -intent-to-experiment or with an intent-to-ship. You must still complete steps 2 -- 4.</td> - -1. <td>Email blink-dev using the <a - href="https://docs.google.com/document/d/1vlTlsQKThwaX0-lj_iZbVTzyqY7LioqERU8DK3u3XjI/edit#bookmark=kix.p5nalpch13qw">“Intent - to Implement” template</a>. </td> - * <td>Formal approval isn't necessary to proceed with - implementation</td> - * <td>Code cannot be checked into trunk without an LGTM in code - review</td> - * <td>Opposition on the "Implement" thread will likely resurface - when you try to ship, so try to resolve issues early</td> -2. <td>Create an entry on <a - href="http://chromestatus.com/">chromestatus</a>.</td> - * <td>You'll need to use an @chromium.org account for - chromestatus.com. If you don't have one, please fill out this - form.</td> - * <td>If you have trouble with chromestatus, please open an issue - on GitHub.</td> -3. <td>File an OWP launch tracking bug</td> - * <td>Some launches may require a formal Chrome review. If your - feature has privacy, legal, or UI impact, please email - web-platform-pms@google.com to set a review in motion.</td> -4. <td>Most changes should start a <a - href="https://w3ctag.github.io/workmode/#specification-reviews">TAG - review</a>. If you're not sure, file one. And link to the bug - tracker for that to make it easy.</td> -5. <td>Implement your change as a Runtime-Enabled Feature.</td> -6. <td>Your feature should have interop tests, preferably - web-platform-tests. If Chrome is the first one implementing a spec, - the requirements for web-platform-tests coverage + quality will be - fairly high for shipping.</td> -7. <td>Optionally, run an <a href="/blink/origin-trials">origin - trial</a> for your feature to collect developer feedback/data, as - input to the standardization process.</td> - * <td>If you answer “no” to all of the following questions, an - origin trial is unnecessary (see caveat in \[1\]).</td> - * <td>Is there disagreement about how well this API satisfies - its intended use case?</td> - * <td>Are you unsure about what API shape will be the most - ergonomic in real world scenarios?</td> - * <td>Is it hard to quantify performance gains without testing - on real world sites?</td> - * <td>Is there a reason that this API needs to be deployed to - real users, rather than behind a flag, for data to be - meaningful?</td> - * <td>If you decide to run a trial, or are unsure, please first - consult with the Origin Trials core team. </td> - * <td>Email <a - href="mailto:experimentation-dev@chromium.org">experimentation-dev@chromium.org</a>. - Google employees can alternatively schedule a meeting - directly with <a - href="mailto:origin-trials-core@google.com">origin-trials-core@google.com</a>.</td> - * <td>If you've decided to run an origin trial, do the following - steps. If not then skip to step 8 of the launch process.</td> - * <td>Follow the instructions on <a - href="/blink/origin-trials/running-an-origin-trial">how to - run an origin trial</a>. Google employees should see <a - href="http://goto.google.com/running-an-origin-trial">go/running-an-origin-trial</a>.</td> - * <td>Email blink-dev using the <a - href="https://docs.google.com/document/d/1vlTlsQKThwaX0-lj_iZbVTzyqY7LioqERU8DK3u3XjI/edit#bookmark=id.pygli2e122ic">“Intent - to Experiment” template</a>. Wait for LGTM from at least 1 - API Owner (again see caveat in \[1\]).</td> - * <td>At the start of every subsequent release, post an update - on usage of the feature on the intent to experiment thread - in blink-dev.</td> - * <td>There is an automatic and mandatory 1 week period when - your feature is disabled at the end of the origin trial, - before it potentially graduates to Stable. Tokens will - expire 1 week before the earliest stable channel launch - date, but note that a stable launch takes many days to - deploy to users. This exists to encourage feature authors to - make breaking changes, if appropriate, before the feature - lands in stable, and to make clear to clients of the origin - trial feature that in all circumstances the feature will be - disabled (hopefully only briefly) at some point.</td> -8. <td>When your feature is ready to ship, email blink-dev using the <a - href="https://docs.google.com/document/d/1vlTlsQKThwaX0-lj_iZbVTzyqY7LioqERU8DK3u3XjI/edit#bookmark=id.w8j30a6lypz0">“Intent - to Ship” template</a>. </td> - * <td>Respond to any feedback or questions raised in the - thread</td> - * <td>You need at least 3 LGTMs from API owners to launch.</td> - * <td>If you have resolved all feedback and are blocked on API - owner LGTMs, add blink-api-owners-discuss@chromium.org - requesting final approval.</td> -9. <td>Enable by default.</td> - -<td>\[1\] Origin trials should be run for a specific reason. These questions are -guidance to identifying that reason. However, there is still debate about the -right reasons, so the guidance may change. You can join the conversation in <a -href="https://docs.google.com/document/d/1oSlxRwsc8vTUGDGAPU6CaJ8dXRdvCdxvZJGxDp9IC3M/edit#heading=h.eeiog2sf7oht">this -doc</a>.</td> - -</tr> -</table>
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/index.md b/chromium/docs/website/site/blink/layoutng/index.md deleted file mode 100644 index 2594ace79cf..00000000000 --- a/chromium/docs/website/site/blink/layoutng/index.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: layoutng -title: LayoutNG ---- - -LayoutNG is a new layout engine for Chromium that has been designed for the -needs of modern scalable web applications. It was released in Chrome 77. - -It provides improved performance isolation, better support for scripts other -than Latin, and fixes many issues around floats and margins. It also fixes a -large number of web compatibility issues. - -Please note that LayoutNG will be launched in stages. In Chrome 77 LayoutNG is -used for inline and block layout. Other layout primitives (such as table, -flexbox, grid, and block fragmentation) will be replaced in subsequent releases. - -Last updated: Wed Oct 23, 2019 by [Emil](mailto:eae@chromium.org) - -# Developer Visible Changes - -Although the user visible impact should be minimal, LayoutNG changes some -behavior in very subtle ways, fixes hundreds of tests, and improves -compatibility with other browsers. Despite our best efforts, it is likely that -this will cause some sites and applications to render or behave slightly -differently. \[[CRBug -query](https://bugs.chromium.org/p/chromium/issues/list?colspec=ID%20Pri%20M%20Stars%20ReleaseBlock%20Component%20Status%20Owner%20Summary%20OS%20Modified&q=Type%3DBug-Regression%20Label%3ALayoutNG&can=1)\] - -The performance characteristics are also quite different; although performance -on a whole is similar or slightly better than before, certain use cases are -likely to see performance improvements, while others are expected to regress -somewhat, at least short-term. - -## Floats - -LayoutNG reimplements support for floating elements (float: left and float: -right) fixing a number of correctness issues around placement of floats in -relation to other content. - -### Superimposed Content - -The legacy float implementation didn’t correctly account for margins when -placing content around a floating element, resulting in the content partially or -fully overlapping the float itself. The most common manifestation of this bug is -when positioning images besides paragraphs of text where the avoidance logic -fails to account for the height of a line ([issue -861540](https://crbug.com/861540)). - -<img alt="image" src="/blink/layoutng/legacy_float_margin.png"> - -*Fig 1a, Legacy layout.* -*Text overlaps the floating image to the right.* - -<img alt="image" src="/blink/layoutng/ng_float_margin.png"> - -*Fig 1b, LayoutNG.* -floating image* *Text is positioned beside the -to the right.* - -The same problem may occur within a single line. The example below shows a block -element with a negative margin following a floating element ([issue -895962](https://crbug.com/895962)). The text should not overlap with the float. - -<img alt="image" src="/blink/layoutng/legacy_float_overlap.png"> - -*Fig 2a, Legacy layout.* -*Text overlaps the floating orange element.* - -<img alt="image" src="/blink/layoutng/ng_float_overlap.png"> - -*Fig 2b, LayoutNG.* -*Text is positioned beside the floating orange element.* - -### Formatting Context Positioning - -When an element forming a block formatting context is sized next to floats -Chromium would try size the block a fixed number of times before giving up. This -resulted in unpredictable and unstable behavior and didn't match other -implementations. In LayoutNG all floats are taken into account when sizing the -block ([issue 548033](https://crbug.com/548033)). - -Absolute/fixed positioning has been reimplemented and is more spec compliant -than the old implementation. It also better matches the behavior in other -browsers. The differences between the two are most visible in the areas where -the old implementation did not follow the spec: - -* **Multi-line Inline Containing Blocks:** If an abspos containing - block spanned multiple lines, the legacy engine might incorrectly - use only a subset of the lines to compute the containing block - bounds. -* **Writing Modes:** The legacy engine had many problems placing out - of flow elements to default position in vertical writing modes. See - the next section for more details around improved writing mode - support. - -## RTL & Writing Modes - -LayoutNG was designed from the ground up to support vertical writing modes and -bi-directional content. This fixes numerous issues around both writing modes, -right-to-left inlines, and orthogonal flows. - -### Bidirectional Text - -LayoutNG supports the most up-to-date Unicode bidirectional algorithm defined by -The Unicode Standard. Not only does it fix various cases where rendering was not -correct, it also includes missing features in the old engine such as paired -bracket support ([issue 302469](https://crbug.com/302469)). - -### Orthogonal Flows - -LayoutNG improves vertical flow layout correctness, for more correct positioning -of absolute positioned objects, sizing of orthogonal flow boxes especially when -percent is used, and so forth. Among the 1,258 tests in W3C test suites, 103 -tests that failed in the old engine pass in LayoutNG. - -### Intrinsic Sizing - -Intrinsic sizes are now calculated correctly when a LayoutNG block contains -children in an orthogonal writing mode. - -## Text Layout & Line Breaking - -The old layout engine in Chromium does text layout element-by-element and -line-by-line. This has historically worked well but requires a lot of extra -complexity to support complex scripts and to get good performance. It's also -prone to inconsistencies in measurements which tend to manifest themselves as -subtle differences in sizing of size-to-content containers and their content or -unnecessary line breaks. - -In LayoutNG text layout is done on a paragraph level and is then split into -lines. This allows for better performance, higher quality text rendering, and -more consistent line breaking.The most notable differences here from a developer -and user standpoint are detailed below. - -### Joining across Element Boundaries - -In some scripts graphemes join with adjacent ones and changes presentation. In -LayoutNG this works even if the graphemes are in different elements, allowing -the joins to be preserved even if different styling is applied ([issue -6122](https://crbug.com/6122)). - -The example below shows the rendering of the following HTML in legacy layout and -LayoutNG respectively: - -<div>نسق</div> -<div>نس<span>ق</span></div> - -<img alt="image" src="/blink/layoutng/legacy_shape.png"> - -*Fig 3a, Legacy layout.* -*Note how the form of the second letter changes.* - -<img alt="image" src="/blink/layoutng/ng_shape.png"> - -*Fig 3b, LayoutNG.* -*Note how the form of the second letter is identical between the two.* - -### CJK Ligatures - -Although Chromium already supports ligatures and enable them by default, there -are some limitations. Ligatures involving multiple CJK codepoints are not -supported in the legacy engine due to a rendering optimization. LayoutNG removes -these restrictions and supports ligatures regardless of script. - -The example below shows the rendering of three discretionary ligatures using the -Adobe SourceHanSansJP font. - -<img alt="image" src="/blink/layoutng/legacy_dlig_jp.png"> - -*Fig 4a, Legacy layout.* -*MHz correctly forms a ligature but マンション and* -*10点 does not.* - -<img alt="image" src="/blink/layoutng/ng_dlig_jp.png"> - -*Fig 4b, LayoutNG.* -*All three groups form ligatures as expected.* - -### Size to Content - -For elements that size to content (such as inline blocks) the current layout -engine computes the size of the block first and then performs layout on the -content. In some cases, such as when a font kerns aggressively, this may result -in a mismatch between the size of the content and the block. In LayoutNG this -failure mode has been eliminated as the block is sized based on the actual -content. - -The example below shows a yellow block sized to content. It uses the Lato font -which uses kerning to adjust the spacing between T and -. The bounds of the -yellow box should match the bounds of the text. - -<img alt="image" src="/blink/layoutng/kern_legacy.png"> - -*Fig 5a, Legacy layout.* -*Note the trailing whitespace after the last T.* - -<img alt="image" src="/blink/layoutng/kern-ng.png"> - -*Fig 5b, LayoutNG.* -*Note how the left and right edges of the box match the bounds of the text.* - -### Line Wrapping - -Similar to the problem described above, if the content of a size-to-content -block is larger (wider) than the block, this can cause the content to wrap -unnecessarily. This is quite rare but sometimes happens for mixed-directionality -content. - -<img alt="image" src="/blink/layoutng/legacy_ar_wrap.png"> - -*Fig 6a, Legacy layout.* -*Note the unnecessary line break and extra space on the right.* - -<img alt="image" src="/blink/layoutng/ng_ar_wrap.png"> - -*Fig 6b, LayoutNG.* -*Note how the left and right edges of the box match the bounds of the text.* - -# Further Information - -For more information about LayoutNG, please see the -[documentation](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/core/layout/ng/README.md), -[design -document](https://docs.google.com/document/d/1uxbDh4uONFQOiGuiumlJBLGgO4KDWB8ZEkp7Rd47fw4/) -and overall [tracking bug](https://crbug.com/591099). - -For more detailed information about the specific compatibility issues and bugs -fixed by LayoutNG, please see the issues linked above or search the Chromium bug -database for bugs marked -[Fixed-In-LayoutNG](https://bugs.chromium.org/p/chromium/issues/list?can=1&q=label%3AFixed-In-LayoutNG). - -If you suspect that LayoutNG may have caused a web site to break, please [file a -bug -report](https://bugs.chromium.org/p/chromium/issues/entry?summary=%5BLayoutNG%5D+Enter+one-line+summary&labels=LayoutNG&components=Blink%3ELayout) -and we'll investigate.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/kern-ng.png.sha1 b/chromium/docs/website/site/blink/layoutng/kern-ng.png.sha1 deleted file mode 100644 index 32acc238fbb..00000000000 --- a/chromium/docs/website/site/blink/layoutng/kern-ng.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -16f6a8cb2e8db8141fcbc7e8fc3a3a1d6d1ec058
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/kern_legacy.png.sha1 b/chromium/docs/website/site/blink/layoutng/kern_legacy.png.sha1 deleted file mode 100644 index 301b0a4218c..00000000000 --- a/chromium/docs/website/site/blink/layoutng/kern_legacy.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -08d36d90e6e0afb8f4f21b03927ff2f692c4dc3e
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/legacy_ar_wrap.png.sha1 b/chromium/docs/website/site/blink/layoutng/legacy_ar_wrap.png.sha1 deleted file mode 100644 index c2a62dd501a..00000000000 --- a/chromium/docs/website/site/blink/layoutng/legacy_ar_wrap.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -8a0fa1708fff0169b715f50d441a08341c10e93c
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/legacy_dlig_jp.png.sha1 b/chromium/docs/website/site/blink/layoutng/legacy_dlig_jp.png.sha1 deleted file mode 100644 index 7802bcf4426..00000000000 --- a/chromium/docs/website/site/blink/layoutng/legacy_dlig_jp.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -9c5a49a0bf8df18e4e449e360f7efe5d3a328bbe
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/legacy_float_margin.png.sha1 b/chromium/docs/website/site/blink/layoutng/legacy_float_margin.png.sha1 deleted file mode 100644 index f63c74c31ef..00000000000 --- a/chromium/docs/website/site/blink/layoutng/legacy_float_margin.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -f8121274b9d56f615a923494c27aa132671d0173
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/legacy_float_overlap.png.sha1 b/chromium/docs/website/site/blink/layoutng/legacy_float_overlap.png.sha1 deleted file mode 100644 index be3da51a0f0..00000000000 --- a/chromium/docs/website/site/blink/layoutng/legacy_float_overlap.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -02be5b4abf948edc75b9cd8fac17744a4e9a628c
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/legacy_shape.png.sha1 b/chromium/docs/website/site/blink/layoutng/legacy_shape.png.sha1 deleted file mode 100644 index e472226d4db..00000000000 --- a/chromium/docs/website/site/blink/layoutng/legacy_shape.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -db3e05b9b8fd46a71634ec65ca073e0a9eba6d38
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/ng_ar_wrap.png.sha1 b/chromium/docs/website/site/blink/layoutng/ng_ar_wrap.png.sha1 deleted file mode 100644 index bc262ec2a59..00000000000 --- a/chromium/docs/website/site/blink/layoutng/ng_ar_wrap.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -c339b8ef2467d9dd3a2d46a83685f739d4029a0e
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/ng_dlig_jp.png.sha1 b/chromium/docs/website/site/blink/layoutng/ng_dlig_jp.png.sha1 deleted file mode 100644 index c6472674fa3..00000000000 --- a/chromium/docs/website/site/blink/layoutng/ng_dlig_jp.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -483fb7cd1b597324a9659af3ebf751c7eaf14ff8
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/ng_float_margin.png.sha1 b/chromium/docs/website/site/blink/layoutng/ng_float_margin.png.sha1 deleted file mode 100644 index 93ae27670e9..00000000000 --- a/chromium/docs/website/site/blink/layoutng/ng_float_margin.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -be07dc29ac991ced4a945a78e4c7d5edf3060f0f
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/ng_float_overlap.png.sha1 b/chromium/docs/website/site/blink/layoutng/ng_float_overlap.png.sha1 deleted file mode 100644 index fda24e9ed89..00000000000 --- a/chromium/docs/website/site/blink/layoutng/ng_float_overlap.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -cb98cf5749d6afa42dc821acd075db6eaa634913
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/layoutng/ng_shape.png.sha1 b/chromium/docs/website/site/blink/layoutng/ng_shape.png.sha1 deleted file mode 100644 index f440bf9938b..00000000000 --- a/chromium/docs/website/site/blink/layoutng/ng_shape.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -f797e81520a319f4e00ef89d37f076269e928353
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/memory-team/index.md b/chromium/docs/website/site/blink/memory-team/index.md deleted file mode 100644 index 412a634e598..00000000000 --- a/chromium/docs/website/site/blink/memory-team/index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: memory-team -title: Memory Team ---- - -## Goals - -* [Memory team OKRs](https://easyokrs.googleplex.com/edit/memory-dev/) - (Google-internal only) - -## Projects - -* Shipping Oilpan - ([Overview](https://docs.google.com/document/d/1_zHanQ8o1lZt1NA_X_2Uo4Tk_wXEkik5JXs8nSSu2Rs/edit#heading=h.ljp56sfuikn2), - [Weekly - status](https://docs.google.com/document/d/1E9NxBmI6FRZ9AgGKhcTcyYV4_19WutY-KgbqBcIoHgI/edit?pli=1)) -* Memory reduction in Blink - ([Overview](https://docs.google.com/presentation/d/1soWvmqxWuZQ_ZchvPZFgf5frAQBBlq5f2tJTuDDPZI8/edit#slide=id.g437b0e633_00), - [Weekly - status](https://docs.google.com/document/d/1Ss64pHLncbpmkmQcWqdL7fiPAH0oy_5XSvjBO3aXf60/edit#heading=h.edmjmaqgarcl)) -* Instant tab restore - ([Overview](https://docs.google.com/document/d/1tOgHctJ1Pwdf0U2n7_y9ZDrpLehy4MKpIxjJPj9J33c/edit?pli=1), - [Weekly - status](https://docs.google.com/document/d/1Vni5m6ohMBkgZFgwI6jjEx-qWUN-4_o7rybyZ330jPY/edit#)) - -We're sending weekly snippets to -[blink-dev@](https://groups.google.com/a/chromium.org/forum/#!forum/blink-dev) -(Search "memory team snippet"). - -## Members - -haraken@chromium.org (TL) -bashi@chromium.org -hajimehoshi@chromium.org -keishi@chromium.org -kouhei@chromium.org -peria@chromium.org -sigbjornf@opera.com -tasak@chromium.org -tzik@chromium.org -yukishiino@chromium.org -yutak@chromium.org -Contact project-trim@chromium.org if you have any feedback or questions.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/origin-trials/index.md b/chromium/docs/website/site/blink/origin-trials/index.md deleted file mode 100644 index 219f5bcb8aa..00000000000 --- a/chromium/docs/website/site/blink/origin-trials/index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: origin-trials -title: Origin Trials ---- - -Origin trials are an approach to enable safe experimentation with web platform -features. For more, see <https://github.com/GoogleChrome/OriginTrials>. - -Googlers should also refer to the internal documentation at -[go/origin-trials](http://goto.google.com/origin-trials). - -<div class="two-column-container"> -<div class="column"> - -**For Blink Contributors / Feature Authors** - -So, you're a Blink contributor, and maybe want to run an origin trial for your -feature? Please see our [Feature Author -Guide](/blink/origin-trials/running-an-origin-trial). - -</div> -<div class="column"> - -**For Web Developers** - -Please see our [Web Developer -Guide](https://github.com/GoogleChrome/OriginTrials/blob/gh-pages/developer-guide.md). - -**Links** - -* Do you have a trial token, but not sure if it's working? We have a - [page to check - tokens](https://googlechrome.github.io/OriginTrials/check-token.html). -* [Current - Trials](https://github.com/GoogleChrome/OriginTrials/blob/gh-pages/available-trials.md) -* [Completed - Trials](https://github.com/GoogleChrome/OriginTrials/blob/gh-pages/completed-trials.md) - -</div> -</div> - -Questions or comments? Contact us at -[experimentation-dev@chromium.org](mailto:experimentation-dev@chromium.org).
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/origin-trials/portals/DevTools_Breakpoint_Workaround.png.sha1 b/chromium/docs/website/site/blink/origin-trials/portals/DevTools_Breakpoint_Workaround.png.sha1 deleted file mode 100644 index 730133d330b..00000000000 --- a/chromium/docs/website/site/blink/origin-trials/portals/DevTools_Breakpoint_Workaround.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -508a4fe2de80b2266e2a33cf381ffc00a8f419c1
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/origin-trials/portals/consolewarning.png.sha1 b/chromium/docs/website/site/blink/origin-trials/portals/consolewarning.png.sha1 deleted file mode 100644 index 94ebe2abf8a..00000000000 --- a/chromium/docs/website/site/blink/origin-trials/portals/consolewarning.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -fcfeb2ef0af1c445f0d4fd4a9ade0d68a46c2e04
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/origin-trials/portals/index.md b/chromium/docs/website/site/blink/origin-trials/portals/index.md deleted file mode 100644 index 2cf0a4c7bb7..00000000000 --- a/chromium/docs/website/site/blink/origin-trials/portals/index.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/origin-trials - - Origin Trials -page_name: portals -title: Portals ---- - -**This origin trial is [now -available](https://developers.chrome.com/origintrials/#/view_trial/-7680889164480380927).** - ---- - -Google Chrome is running an [origin -trial](https://github.com/GoogleChrome/OriginTrials/blob/gh-pages/developer-guide.md) -to give developers an opportunity to experiment with the -[Portals](https://web.dev/hands-on-portals/) feature that we are working on, and -gather feedback about how we can make it better. - -## This experiment will begin in Chrome 85 and end after Chrome 86. During this experiment, you can use an origin trial token to experiment with using portals to load same-origin content (i.e. content served from the same origin as the main page). - -## Frequently Asked Questions - -### How do I sign up? - -### Go to the [Origin Trials developer console](https://developers.chrome.com/origintrials/#/view_trial/-7680889164480380927). - -Your tokens will periodically expire and need to be renewed using this console. - -### How can I provide feedback? - -Thanks for asking! When you renew your origin trial token, we’ll ask for your -feedback. This is the best place to explain how you’re using portals, what’s -working well, and what isn’t. -If you find bugs in Chrome’s implementation (for example, Chrome crashes when -you use portals), please [file a Chromium bug](https://crbug.com/new). Make sure -to mention Portals in your report so that the bug is triaged appropriately. - -If you identify specific issues with the [CG draft -specification](https://wicg.github.io/portals/) or the design of the feature -(for example, if it’s difficult to achieve the effect you’re looking for using -the available API), please [file a spec -issue](https://github.com/WICG/portals/issues/new). - -I've noticed some differences between what Chrome does and what the explainer -and/or spec say. What gives? - -We apologize for the inconvenience: both are a work in progress. - -In some places, the Chrome implementation contains features which haven't been -incorporated into the spec. For example: - - the <portal> element fires a [load - event](https://github.com/WICG/portals/issues/26) similar to <iframe> - - portal activation [can fail in some cases that aren't yet - explained](https://github.com/WICG/portals/issues/185), for example because - the page has not yet loaded or failed to load - - a portal is a single object as seen by screen readers and other - accessibility tools, and in this regard is more similar to a link or button - than a frame - - The Chrome implementation integrates with session history and the back - button, but this is not yet explained or specified. - -In other places, the explainer discusses changes we have not yet implemented in -Chrome. For example: - - the explainer discusses cross-origin portals, which are not permitted during - this origin trial - - integration with document.requestStorageAccess is alluded to, but not - currently implemented in Chrome - - some changes to how portals are sized and how they interact with rendering - and visibility APIs are explained in the API, but currently in Chrome - <portal> elements behave in the same way as <iframe> - - The explainer alludes to integration with feature policy via the allow="" - attribute, but this is not yet implemented in Chrome - -### Why was the page blocked from loading in a portal? - -For the duration of this experiment, pages are only permitted to load URLs that -match their origin. This means that the scheme (http or https), full hostname -(including subdomains) and port (if specified) must match. This restriction -applies to any URLs encountered by following redirects, and any navigations that -occur after loading within the portal. - -If your content attempts to load a cross-origin URL in a portal, it will be -blocked and the previously loaded page, if any, will be displayed instead. - -When this happens, a warning will be logged to the developer console, including -the origin of the URL that was blocked. - -[<img alt="Navigating a portal to cross-origin content (from -https://www.example.com) is not currently permitted and was blocked." -src="/blink/origin-trials/portals/consolewarning.png">](/blink/origin-trials/portals/consolewarning.png) - -Your load may also be blocked for other reasons. If either document has a -[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) -that does not permit embedding, Chrome will respect it. For example, if the URL -to be loaded in the portal has a -[frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors) -directive that does not include self (or your origin), the load will be blocked. - -### I was already using Portals, and I started seeing that warning message. What gives? - -First, thanks for trying out Portals! If Portals were previously working for -you, you are a developer who has previously turned on the Portals feature flag. -(Note that this is not recommended in your main browser, just in your -development environment where you're experimenting with Portals.) - -This origin trial allows developers like you to enable Portals for Chrome users. -Since this experiment does not yet cover loading cross-origin content, we've -changed the default behavior to be limited to same-origin content. To return to -allowing cross-origin content, enable the cross-origin portals flag via -chrome://flags/#enable-portals-cross-origin or run Chrome with the command-line -switch --enable-features=PortalsCrossOrigin. - -### I'm seeing a warning that a <portal> was moved to a document where it was not enabled. What does that mean? - -The origin trial enables the portals feature only for documents that supply an -origin trial token. If you attempt to make a portal element and then insert it -into another document, it will not be able to function correctly in that -document. - -### Why can’t I use this from a local file:// URL? - -Portals is a powerful feature, and we need to be able to establish the origin of -the content, and of the content it is loading in a portal, in order to ensure -that it is used safely. Unfortunately this means that you will need to run an -HTTP server in order to experiment with portals. - -## Known Issues - -### Breakpoints set in portalactivate event handlers don't pause execution - -When inspecting a page using Chrome DevTools (*Ctrl + Shift + I* or *Right Click -+ Inspect*), execution doesn't pause for breakpoints set inside a portalactivate -event handler after a portal activates. As a workaround, you can either use -console debugging, or inspect the portal page through chrome://inspect/#pages -before activation and set a breakpoint there. Breakpoints set when inspecting -pages through chrome://inspect work correctly, so they should also work when -using remote debugging (chrome://inspect/#devices) to debug a page running on a -remote device. This issue is tracked [here](https://crbug.com/1025761). - -[<img alt="Image showing chrome://inspect#pages" -src="/blink/origin-trials/portals/DevTools_Breakpoint_Workaround.png" height=203 -width=400>](/blink/origin-trials/portals/DevTools_Breakpoint_Workaround.png)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/origin-trials/running-an-origin-trial/index.md b/chromium/docs/website/site/blink/origin-trials/running-an-origin-trial/index.md deleted file mode 100644 index 4ca9328fe20..00000000000 --- a/chromium/docs/website/site/blink/origin-trials/running-an-origin-trial/index.md +++ /dev/null @@ -1,344 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/origin-trials - - Origin Trials -page_name: running-an-origin-trial -title: Running an Origin Trial ---- - -*For the full context on origin trials, please see the -[explainer](https://github.com/GoogleChrome/OriginTrials/blob/gh-pages/explainer.md). -This is the feature author guide for Blink contributors.* - -Here, we describe what is involved in running an origin trials experiment for a -new browser feature. Most importantly, origin trials are integrated into the -[launch process for new web platform features](/blink/launching-features). You -should be following that overall process (maybe you ended up here from that -page). - -[TOC] - -## Should you run an origin trial? - -Origin trials are intended to be used to ensure we design the best possible -features by getting feedback from developers before the standard is finalized. -They may also be used to prove developer interest in a feature proposal that is -otherwise undesired due to an expected lack of interest. Typically, you should -have a specific hypothesis that you wish to test by collecting data. - -If you answer “yes” to any of the following questions, you should consider -running an origin trial (see caveat in \[1\]). - -* Is there disagreement about how well this API satisfies its intended - use case? -* Are you unsure about what API shape will be the most ergonomic in - real world scenarios? -* Is it hard to quantify performance gains without testing on real - world sites? -* Is there a reason that this API needs to be deployed to real users, - rather than behind a flag, for data to be meaningful? - -\[1\] Origin trials should be run for a specific reason. These questions are -guidance to identifying that reason. However, there is still debate about the -right reasons, so the guidance may change. You can join the conversation in -[this -doc](https://docs.google.com/document/d/1oSlxRwsc8vTUGDGAPU6CaJ8dXRdvCdxvZJGxDp9IC3M/edit#heading=h.eeiog2sf7oht). - -*If you're planning to run an origin trial please contact the origin trials team -(OT team) to quickly talk over your feature and the reason for running the -trial.* You can email -[experimentation-dev@chromium.org](mailto:experimentation-dev@chromium.org) or -[chasej@chromium.org](mailto:chasej@chromium.org). Google employees can -alternatively contact -[origin-trials-core@google.com](mailto:origin-trials-core@google.com). - -## How do origin trials work in Chrome? - -The framework will enable features at runtime, on a per-execution-context basis -(practically, this will be per-document or per-worker). Features are disabled by -default, and only be enabled if a properly signed token, scoped to the origin -that it is being presented on, and scoped to the specific feature name, is -present in either: - -* an HTTP Origin-Trial header in the server response, -* an HTML <META> tag in the document's head, or -* (for Dedicated Workers only) the HTTP response or document head of - the parent document. - -The logic for enabling includes a check of your [runtime feature -flag](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/platform/RuntimeEnabledFeatures.md) -(even if the origin trials framework isn't being used). This means you can -easily test your feature locally, even without any trial tokens. -Origin trials are being enabled in documents (for both inline and external -scripts), and in service, shared, and dedicated workers. (Note that for service -workers and shared workers, HTTP headers are the only way to enable trials. -Dedicated workers will also inherit any trials enabled by their parent -document). -If an experiment gets out of hand (*way* too popular to be an experiment -anymore, for instance), we’ll be able to turn it off remotely, for all origins. -Similarly, if there turns out to be major problems with the implementation of -the framework itself, we’ll be able to turn it off completely, and disable all -trials. (Hopefully we don’t have to do that, but we're still in the early stages -of origin trials, and we’re being careful.) - -## Is your feature ready to be an origin trial? - -Before running an origin trial experiment, your feature needs to be ready for -both web developers and users. Your feature must satisfy the following: - -* Have an explainer for your feature - * There needs to be a description of the problems and use cases - the feature is intended to address. -* Have a draft spec for your feature - * Ideally this would be in the form of an actual spec -- or PR - against an existing spec -- in the format expected by the - eventual standards body (although the draft might be hosted - elsewhere while discussions are ongoing), but a detailed - explainer laying out all the details may suffice. The level of - detail needs to be enough so that (a) developers participating - in the origin trial know how it works, and (b) spec editors for - the relevant eventual specifications can see exactly how it - would affect that spec when added. -* Be approved by the internal Chrome launch review process - * Users may be exposed to your feature without opting in, so the - appropriate measures must be taken for privacy, security, etc. -* Have a way to remotely disable the feature - * Origin trials provides infrastructure to disable a feature (or a - specific origin), but this only applies to the exposure as an - origin trial. That means, any interface(s) controlled by the - trial will be disabled, but it will still be possible to enable - the feature via its runtime flag. As well, all of the token - validation/revocation happens in the renderer. - * If the previous point is not sufficient for disabling the - feature, you should implement a kill switch that allows your - feature to be disabled remotely via Finch. - * This can use the existing functionality in - PermissionContextBase or base::FeatureList, or be a - feature-specific implementation. - * Consult the Chrome feature launch process for [guidance for a - feature - flag](https://docs.google.com/document/d/1hJ1U8-7DNa7lGfTJWRgSgqQyNnOFO4Ks5Czr1-3--8I/edit#bookmark=id.xgrabupypw8w) - (Googlers only). If you would launch your feature by default - with a flag, then you should implement one for the origin trial. -* Have UMA metrics to track feature usage - * You should record usage with - [UseCounter](https://cs.chromium.org/chromium/src/third_party/blink/renderer/core/frame/use_counter.h), - as that can be automatically monitored by the origin trials - infrastructure. - * The feature must have a corresponding entry in the enum - [WebFeature](https://cs.chromium.org/chromium/src/third_party/blink/public/mojom/web_feature/web_feature.mojom). - * For any JavaScript-exposed API, usage can be recorded easily via - one of the - [\[Measure\]](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md#Measure_i_m_a_c) - or - [\[MeasureAs\]](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md#measureas_i_m_a_c) - IDL attributes. - * If not exposed via IDL, the appropriate UseCounter::count\*() - method can be used directly from your feature implementation. - * If it's not feasible to integrate with UseCounter (e.g. usage is - best tracked outside a renderer, .etc), please contact the OT - team. -* Have an established community for discussion of the feature - * At a minimum, this should be a WICG group, Github repo, etc. - Anywhere developers can find discussion or log issues about your - feature. - * The origin trials system will facilitate collecting feedback - from web developers. However, the goal is to have web developers - participate in the existing community around the feature. -* Prepared a blog post/article/landing page introducing the feature - * There needs to be single link that will provide details about - the feature. - * Should make it clear how developers provide feedback/log issues - for your feature. - * This could be the README.md in your Github repo, or any other - page of your choice. - * Should include details about availability via origin trials. - -## What is the timeline for running a trial and collecting feedback? - -Please see our [overview of the timeline for running a trial and collecting -feedback](https://docs.google.com/document/d/1ttgWkpQUtlJy0Q5HhXdaPKs2DHfITbNwLqtNRxqdKMI/edit). -Contact -[experimentation-dev@chromium.org](mailto:experimentation-dev@chromium.org) with -any questions. - -## What is the actual process to run an origin trial? - -First review the [Blink launch process](/blink/launching-features). Please -contact -[experimentation-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/experimentation-dev) -with any questions about these steps. If you don't have access to any of the -links below, the mailing list can help find someone to guide you. -Running an origin trial requires the following: - -* Make sure your feature is ready to run an origin trial experiment - ([see - above](/blink/origin-trials/running-an-origin-trial#is-feature-ready)). -* Email - [experimentation-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/experimentation-dev) - letting them know you plan to run an origin trial. -* Review - [go/ChromeLaunchProcess](https://goto.google.com/ChromeLaunchProcess) - and determine what launch approvals you require. -* Integrate with the origin trials framework ([see - below](/blink/origin-trials/running-an-origin-trial#integrate-feature)). -* Send an [Intent to Experiment](/blink/launching-features), via the - [ChromeStatus entry for your feature](https://chromestatus.com/). -* Request a trial for your feature at - [go/new-origin-trial](http://goto.google.com/new-origin-trial). - * This will ensure your trial is tracked correctly in - [go/origin-trials-feature-pipeline](http://goto.google.com/origin-trials-feature-pipeline/). -* Land the feature in Chrome prior to beta. -* Engage with external partners or large-scale developers for early - testing. - * Some issues may only found during large-scale use, so should be - tested even before beta (if possible). - * If feasible, this could include doing your own testing within - the developer's environment (any of test/staging/production). - * For an example, see [crbug.com/709211](http://crbug.com/709211). -* Publish a blog post on - [developers.google.com/web/updates](http://developers.google.com/web/updates) - about the feature when it lands beta. - * The OT team will add your feature to the [public developer - console](https://developers.chrome.com/origintrials). - * [See - below](/blink/origin-trials/running-an-origin-trial#add-to-signup-form) - for more details. -* Update the feature's entry on - [chromestatus.com](https://www.chromestatus.com/) to set the status - to "Origin trial". -* You can review the developer registrations for your feature (and - renewals) by following the instructions in the [feature author - guide](https://goto.google.com/running-an-origin-trial). - * In particular, be aware of any registrations that expect - >10,000 page views per day to be using the feature - -Note that these steps are not meant to be sequential. For example, you can -certainly start integrating your feature with origin trials prior to getting -various launch approvals. - -### Adding your feature to the public developer console - -The configuration of a trial in the [developer -console](https://developers.chrome.com/origintrials) requires basic information, -including some public landing page/documentation link ([see -above](/blink/origin-trials/running-an-origin-trial#is-feature-ready)). In some -cases, this may seem like a chicken-and-egg problem. For example, you may not -want to publish a blog post until the feature is ready for developers. If the -blog post has detailed information on joining the origin trial, it doesn't make -sense to publish and have web developers unable to register. Fortunately, a -trial can be configured in the developer console in advance, separately from -making it available to the public. - -Recommended process: - -* Request setup of the trial with an interim documentation link (e.g. - the README from the GitHub repo). - * The OT team can configure the trial in the developer console - (without making in public), and provide a permanent link to the - trial detail page. -* Publish the blog post for the feature when the beta release is - available. - * Include instructions about the origin trial, and a link to - either (1) the list of available trials or (2) the detail page - for your trial. -* Notify the OT team with the final link to the blog post. - * The link will be updated in the developer console and recorded - in - [go/origin-trials-feature-pipeline](http://goto.google.com/origin-trials-feature-pipeline/). -* Notify the OT team when the trial is ready for registration. - * OT team will activate the trial to make it available to the - public. - -## How long do Origin Trials typically last? - -Historically, origin trials have typically lasted 3 milestones (~18 weeks). -We've typically capped extensions to origin trials at 6 milestones total (~36 -weeks), unless presented with evidence that the risk of burn in is low; changes -to the API surface, etc). - -With the [shift to 4 week release -cycles](https://blog.chromium.org/2021/03/speeding-up-release-cycle.html), we -plan for origin trials to typically last 4 milestones (~16 weeks), with a cap of -9 milestones (~36 weeks) absent compelling evidence. - -## What is the process to extend an origin trial? - -Origin trials are not intended as a mechanism for shipping a feature early -without following the full launch process. This is one of the reasons that each -trial has a predefined end date (rather than running indefinitely until the -feature ships). That said, there are situations where it is beneficial to allow -experimentation to continue beyond the planned end date of the trial. - -There two general cases where experimentation may continue beyond the planned -end date: - -1. Unexpected delays in releasing - * With the 6 week Chrome release cycle, code may not land in the - intended release, meaning it is not shipped until the subsequent - release. Alternatively, the code may land in the release, but - the Chrome stable rollout is delayed, meaning it not - available/installed until much later than expected. When a trial - typically runs for 18 weeks (3 Chrome releases), such delays can - significantly impact the availability of the experimental - feature and the ability to collect sufficient data. For features - that transition from origin trial to shipping in consecutive - releases, the unavailability of the feature might extend well - beyond the intended 1 week gap. -2. Feature changes or new areas experimentation - * As the origin trial progress, you may determine that a feature - is not ready to be shipped, but do want to continuing - experimenting. For example, feedback indicates that changes are - needed to the feature (especially in API surface), but the - changes would benefit from further feedback. In other cases, the - hypothesis for the experiment may be proved or disproved, but - you uncover new hypotheses for experimentation. - -Consult with the OT team to figure out if you're in a situation where it makes -sense to continue experimenting. For unexpected delays (1), this generally means -requesting an extension to the trial end date, which generally should not be -more than 3-4 weeks. For feature changes and such (2), this generally means -starting a new origin trial, to follow the previous trial. - -### How to setup an extension or continued experiment? - -The process is as follows: - -* If desired, email - [experimentation-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/experimentation-dev) - to consult on the appropriate approach. If there are sensitive - details, Googlers can contact - [origin-trials-core@google.com](mailto:origin-trials-core@google.com). -* Send an Intent to Extend Origin Trial, via the [ChromeStatus entry - for your feature](https://chromestatus.com). -* Wait for 1 LGTM from at least one API owner (similar to the original - Intent to Experiment) -* If continuing to experiment via a new trial: - * This will officially be a new and separate trial, meaning a - separate entry in the list of trials, etc. - * Request another trial at - [go/new-origin-trial](http://goto.google.com/new-origin-trial), - with the appropriate naming to distinguish the old and new - trial. - * Update the integration with the framework - the code must use a - different trial name in Chromium ([see integration - below](/blink/origin-trials/running-an-origin-trial#integrate-feature)). -* If extending the end date of the existing trial: - * Notify the OT team of the change at - [go/extend-origin-trial](http://goto.google.com/extend-origin-trial). -* Upon approval, the OT team will setup the extension or new trial as - appropriate. - -## How to integrate your feature with the framework? - -The integration instructions now live in the Chromium source repo: -<https://chromium.googlesource.com/chromium/src/+/HEAD/docs/origin_trials_integration.md> - -## Roadmap - -All of this may change, as we respond to your feedback about the framework -itself. Please let us know how it works, and what's missing! -To follow the most up-to-date progress and plans, filter in crbug.com for -“[component:Internals>OriginTrials](https://bugs.chromium.org/p/chromium/issues/list?q=component:Internals%3EOriginTrials)”.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/platform-predictability/compat-tools/index.md b/chromium/docs/website/site/blink/platform-predictability/compat-tools/index.md deleted file mode 100644 index 6c0dd743a9c..00000000000 --- a/chromium/docs/website/site/blink/platform-predictability/compat-tools/index.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/platform-predictability - - Web Platform Predictability -page_name: compat-tools -title: Web compat analysis tools ---- - -When deprecating or changing web-exposed behavior, it's often important to get a -clear understanding of the compatibility impact. We have a variety of tools -available to you depending on the scenario. This page is designed to help you -choose the appropriate tool (in decreasing order of usage). For questions and -discussion, e-mail -[feature-control@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/feature-control). - -## UseCounter - -[UseCounter](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/use_counter_wiki.md) -is a framework in Blink which is used to record per-page anonymous aggregated -metrics on feature usage, often via the [\[Measure\] idl -attribute](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md#Measure_i_m_a_c). -Results are shown publicly on -[chromestatus.com](https://www.chromestatus.com/metrics/feature/popularity) (for -the [dominant milestone per -day](https://github.com/GoogleChrome/chromium-dashboard/issues/279)) . More -detailed break-downs are available to Google employees via the -[Blink.UseCounter.Features histogram using a formula with the PageVisits bucket -in the denominator](https://goto.google.com/uma-usecounter). Internally it's -also possible to look at UseCounter by the [fraction of users that hit it at -least once in a day](https://goto.google.com/uma-usecounter-peruser), and -UseCounters [hit within Android -WebView](https://goto.google.com/uma-usecounter-webview). In the vast majority -of cases, compat tradeoffs are made entirely based on public UseCounter data. - -**Pros:** - -* Reflects real Chrome usage - should be the primary source of all - compat discussions in blink -* Has huge coverage - reflects a wide fraction of all usage of Chrome - -**Cons:** - -* Requires at least a couple weeks to get any useful data (several - months to roll out to stable) -* Biased against scenarios where UMA tends to be disabled more often - (eg. enterprises) -* Can't be publicly used to get specific URLs. However, Googler's are - starting to be able to do this internally with - [CrUX](https://developers.google.com/web/tools/chrome-user-experience-report/) - data ("UKM"). While limited for privacy reasons, it's already - proving quite useful. - -## Simple web search - -Often it's useful to find examples of specific coding patterns in order to -understand the likely failure modes and formulate migration guidance. Use -technical web search engines like [nerdydata.com](https://nerdydata.com), or for -problems in specific libraries, ranking sites like -[libscore.com](https://libscore.com). - -**Pros:** - -* Simple, easy to use -* Results in specific URLs for further analysis - -**Cons:** - -* Strictly a dumb static search, can't reliably find all uses of an - API (especially due to Javascript minifiers which generate code like - "a\[b\]()"). - -## The HTTP Archive - -A slightly more advanced form of static web search is to use the [HTTP -Archive](http://httparchive.org/), a database of the top 500k websites, updated -by a crawl twice a month. See [HTTP Archive for web compat decision -making](https://docs.google.com/document/d/1cpjWFoXBiuFYI4zb9I7wHs7uYZ0ntbOgLwH-mgqXdEM/edit#heading=h.1m1gg72jnnrt) -for details on using it for compat analysis. - -**Pros:** - -* Can provide an absolute measure of risk ("only 10 sites in the top - 500k appear to use this API"). -* Now [includes UseCounter - data](https://groups.google.com/a/chromium.org/forum/#!topic/blink-api-owners-discuss/uxwEuxCRfGA), - so can go beyond simple static search to some dynamic behavior - -**Cons:** - -* Only captures behavior triggered during page load -* Only reflects the home page of the top 500k sites -* Analysis is more involved - -## Microsoft's CSS Usage Data - -[CSS usage on the web -platform](https://developer.microsoft.com/en-us/microsoft-edge/platform/data/) -is "from a Bing-powered scan" of lots of pages, and measures both CSS properties -and values. (Chrome use counters generally don't exist for values.) - -## GitHub and stackoverflow deprecation warning search - -Once a deprecation warning has been landed (or made it to stable), it can be -[extremely -informative](https://groups.google.com/a/chromium.org/forum/#!topic/intervention-dev/_0eSO-NjULo) -to search [GitHub](https://github.com/) issues (or other developer help sites -like [stackoverflow.com](https://stackoverflow.com/)) for discussion of the -warning generated on the console (eg. by searching for the chromestatus ID -present in the warning). - -**Pros:** - -* Helps identify the real-world pain experienced by developers -* Provides an avenue for outreach, and can [build - goodwill](https://twitter.com/jgwhite/status/832517528899448832) - -**Cons:** - -* Long turn-around time -* Lossy - absence of signal doesn't really indicate an absence of risk - -## GitHub code search - -Most of the popular libraries and frameworks are present on GitHub. -[Searching](https://github.com/search) for potentially impacted code can be -useful in better understanding the risk. - -**Pros:** - -* Provides unobfuscated access to code -* Provides an avenue to engage with developers to better understand - their use cases and their ability to apply mitigations. - -**Cons:** - -* Doesn't provide much signal on magnitude of impact -* Supports only either simple static searches. - -## On-demand crawl - -Occasionally it's useful to search top sites for a specific behavior (without -landing a UseCounter and waiting for the data to show up in HTTP Archive). For -advanced cases like this we can run a custom chromium build on the [telemetry -cluster](/developers/cluster-telemetry) to crawl the top 10k (or more) sites and -record whatever we like (with a temporary UseCounter). See [Using Cluster -Telemetry for UseCounter -analysis](https://docs.google.com/document/d/1FSzJm2L2ow6pZTM_CuyHNJecXuX7Mx3XmBzL4SFHyLA/edit#) -for details. - -**Pros:** - -* Can have fast turn-around time (hours) -* Usually used just for page load, but can be extended to trigger - other interactions (scroll, clicking on links, etc.). - -**Cons:** - -* Limited scope -* Complicated and brittle. Relies on some changes to telemetry that - cannot currently be landed. Generally found not to be worth the - effort compared to the alternatives above.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/platform-predictability/index.md b/chromium/docs/website/site/blink/platform-predictability/index.md deleted file mode 100644 index c6ac9cb7643..00000000000 --- a/chromium/docs/website/site/blink/platform-predictability/index.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: platform-predictability -title: Web Platform Predictability ---- - -Web developers say a big problem building for the web is all the surprises they -hit where something doesn't work the way they expected. The Chromium project -(along with other browsers and standards organizations) has long invested -heavily in reducing these problems. But we've lacked a coordinated effort to -track and improve the whole area. - -The Web Platform Predictability project is an effort to make developing for the -web more predictable, and as a result more enjoyable, cost-effective and -competitive with native mobile platforms. In particular, we intend to focus -primarily on problems caused by: - -* Different browsers / platforms behaving differently - (interoperability) -* Behavior changing from one version of a browser to another - (compatibility) -* APIs with surprising side effects or subtle behavior details - (footguns) - -For details see: - -* [BlinkOn 7: Platform - Predictability](https://docs.google.com/presentation/d/1pfu-wAxbkVN41Zgg9P3ln9tJB9AwKh9T3btyWvd17Rk/edit), - and - [web-platform-tests](https://docs.google.com/presentation/d/1s2Dick89wvJsuNJb4ia3pPt84NtMv8rZr0E_GFXJLrk/edit#slide=id.p) -* Chrome Dev Summit: [Predictability for the - Web](http://www.slideshare.net/robnyman/predictability-for-the-web/) - talk ([video](https://youtu.be/meAl-s77DuA)) -* [Platform Predictability vision - document](https://drive.google.com/open?id=1jx--r4elUfTP2EGo27UPGncLTAIW3ExF7N2JL7sjki4) -* [BlinkOn 6: Web Platform - Predictability](https://docs.google.com/presentation/d/1umK4QkfCvzicHVJKLNo2yDRyWSqQEamavW9QVFmugNY/edit) - talk - ([video](https://www.youtube.com/watch?v=ipfPyM-Kwyk&feature=youtu.be)) -* [Predictability mailing - list](https://groups.google.com/a/chromium.org/forum/#!forum/platform-predictability) -* [Ecosystem Infrastructure team - charter](https://docs.google.com/document/d/1MgcisuMnvh3z6QNIjDSvRbt4uoNtmI_cljcQkGXzNQ8/edit) - and [mailing - list](https://groups.google.com/a/chromium.org/forum/#!forum/ecosystem-infra): - the chromium team driving most of the interop-related work - -## The difficulties of web development - -* [The Double-Edged Sword of the - Web](https://ponyfoo.com/articles/double-edged-sword-web) -* [The Fucking Open - Web](https://hueniverse.com/2016/06/08/the-fucking-open-web/) -* [10 things I learned from reading (and writing) the PouchDB - source](https://pouchdb.com/2014/10/26/10-things-i-learned-from-reading-and-writing-the-pouchdb-source.html) -* [(Web) Development Sucks, and It's Not Getting Any - Better](http://blog.dantup.com/2014/05/web-development-sucks-and-its-not-getting-any-better/) -* [Make the Web Work For - Everyone](https://hacks.mozilla.org/2016/07/make-the-web-work-for-everyone/) - -## Advice for Blink developers - -* Blink's mission is to make the web better, fight the temptation to - focus narrowly on just making Chrome great! -* Prefer [web-platform-test changes in your - CLs](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/web_platform_tests.md) - over web_tests changes where practical -* What matters to web developers is eliminating surprises, so focus on - [pragmatic paths to - interop](https://docs.google.com/document/d/1LSuLWJDP02rlC9bOlidL6DzBV5kSkV5bW5Pled8HGC8/edit) - that maximize web compat. If 3+ engines violate a spec in the same - way, the bug is probably in the spec (especially when changing the - engines would break websites). Specs are much easier to change than - multiple implementations! -* For breaking changes, reach out to - platform-predictability@chromium.org for advice or read the [Blink - principles of web compatibility](https://bit.ly/blink-compat) -* Prioritize bugs in your areas that reflect real developer pain - eg. - [those most - starred](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=component:Blink&sort=-stars&colspec=ID%20Stars%20Pri%20Status%20Component%20Opened%20Summary), - [recent - regressions](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=type%3Dbug-regression+pri%3D0%2C1+component%3Ablink+opened-after%3Atoday-60&colspec=ID+Pri+Mstone+ReleaseBlock+OS+Area+Feature+Status+Owner+Summary&x=m&y=releaseblock&cells=tiles). -* Understand how your feature behaves on [all major - browsers](https://browserstack.com/), file bugs for differences (on - specs, other engines and/or blink). -* Make sure new APIs have feedback from several real world web - developers. -* Get to know your peers on other engines, you'll be surprised how - well your goals and interests are aligned! - -## Relevant issue trackers - -* Chromium Hotlist-Interop: key bugs that impact interoperability - * Useful queries: - [untriaged](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=Hotlist%3DInterop+status%3Duntriaged%2Cunconfirmed&sort=&groupby=&colspec=ID+Pri+Component+Status+Owner+Summary+Modified&nobtn=Update), - [high - priority](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=Hotlist%3DInterop+pri%3D0%2C1&colspec=ID+Pri+Component+Status+Owner+Summary+Modified&x=m&y=releaseblock&cells=ids), - [most - starred](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=Hotlist=Interop&sort=-stars&colspec=ID%20Stars%20Pri%20Component%20Status%20Owner%20Summary%20Modified) - * [New Hotlist-Interop - bug](https://bugs.chromium.org/p/chromium/issues/entry?template=Defect%20report%20from%20user&labels=Type-Bug,Pri-2,Cr-Blink,Hotlist-Interop) -* [Chromium - Blink>Infra>Ecosystem](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=component%3ABlink%3EInfra%3EEcosystem+&colspec=ID+Pri+Component+Status+Owner+Summary+Modified&x=m&y=releaseblock&cells=ids): - bugs for chromium infrastructure and tooling to promote - interoperability -* [Chromium - Internals>FeatureControl](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=component%3AInternals%3EFeatureControl+&colspec=ID+Pri+Component+Status+Owner+Summary+Modified&x=m&y=releaseblock&cells=ids): - bugs related to how web platform features are enabled and measured - (e.g. webexposed tests, UseCounters) -* [Chromium bugs filed by other browser - vendors](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=reporter:microsoft.com,mozilla,webkit.org,apple.com&sort=-opened+-modified&colspec=ID%20Reporter%20Pri%20Component%20Status%20Owner%20Summary%20Opened%20Modified) -* [GitHub issues for - Chromestatus.com](https://github.com/GoogleChrome/chromium-dashboard/issues) - -## Useful tools - -* [Compat analysis tools](/blink/platform-predictability/compat-tools) -* Cross browser testing: [BrowserStack](https://www.browserstack.com), - [Sauce Labs](https://saucelabs.com/) - -## Other Resources - -* [web-platform-tests](https://github.com/w3c/web-platform-tests/) -* [Webcompat.com](http://webcompat.com/) -* [BlinkOn5: Interoperability Case - Studies](https://docs.google.com/presentation/d/1pOZ8ppcxEsJ6N8KfnfrI0EXwPEvHwg3BHyxzXXw8lRE) - ([video](https://www.youtube.com/watch?v=a3-zFbwsoEs)) -* [W3C Web Platform Incubation Community - Group](https://www.w3.org/community/wicg/) -* [The elastic band of - compatibility](https://plus.google.com/+AlexKomoroske/posts/WNvcmeTFhzx)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/platform-predictability/objectives/index.md b/chromium/docs/website/site/blink/platform-predictability/objectives/index.md deleted file mode 100644 index 38b747ef775..00000000000 --- a/chromium/docs/website/site/blink/platform-predictability/objectives/index.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/platform-predictability - - Web Platform Predictability -page_name: objectives -title: Objectives ---- - -At Google we define and track progress against our goals using -["OKRs"](https://www.gv.com/lib/how-google-sets-goals-objectives-and-key-results-okrs) -(Objectives and Key Results). Here are the OKRs for the web platform -predictability infrastructure project. Note that these are **intentionally -aggressive** and so we will be happy if we deliver 60%-70% of them. Platform -predictability also includes broader efforts by other web platform teams (eg. -improving interop of the features they own), but those are owned by the -individual teams (eg. [input-dev](/teams/input-dev/input-objectives)) and so not -included here. - -## 2016 Q3 - - ### Improve interop testing - - Invest in a high quality test suite for the web platform as a whole. - - #### Imports happening daily via simplified import process. - - * Add a builder which tries to update, and aborts if an - automatic update couldn't be completed. - * Add a script to trigger try jobs to discover which new tests - are failing across different platforms. - * Add a mapping of directories to auto-update preferences, and - when updating, edit W3CImportExpectations/TestExpectations - and file bugs according to this mapping. - - #### Easier contribution to web-platform-tests - - Implement a way to contribute to WPT repository with Chromium tools. Our - tools assume that some configuration files are checked in to the target - repository, and we need to put such files to a separated repository for - WPT. - * Agreement on changes in our tools with chrome-infra - * Implement - * Land the first CL using the process to both of Chromium repo - and WPT repo - * Multiple Blink engineers landed CLs with the process - - #### Bugs filed for all automated web-platform-tests that fail on Chrome but pass on two other engines - - Use this to increase our understanding of the value of WPT - - #### Eliminate csswg-test build step - - Test harness runs unbuilt tests - - #### Eliminate csswg-test pull-request backlog - - 32 as of 6/20 - - #### W3C PointerEvent Tests: Complete automation through script injection - - shared with input-dev. - - ### Improve understanding of web compat - - Tools for better data for decision making that impacts compat, and process - improvements that reduces the risk/cost of regressions. - - #### Googlers can use bisect-builds.py to bisect regressions on Linux Chrome down to an individual commit position - - Internal only for now due to only official Chrome builds being archived. - Obviously doesn't include positions which fail to build, etc. - - #### Land scripts and publish instructions for using cluster telemetry for UseCounter analysis - - #### Fix fast shutdown and PageVisits issues in UseCounters in Chrome 54 - - <https://crbug.com/597963>, <https://crbug.com/236262> - - #### Web platform TLs regularly use a view of regression rates per component - - #### Extend Cluster telemetry to add new anlyasis page and support runs on 100k web pages - - Goal is developers can intuitively and easily schedule analysis runs - using Cluster Telemetry's new analysis page. Specific AIs: Make CT using - swarming. No waiting in queue. Add 200+ VMs to CT pool. Add support for - 100k pages. <http://skbug.com/5465>, <http://skbug.com/5316>, - <http://skbug.com/5245> - - #### Remove (or downgrade) deprecation warnings not on imminent path for removal - - Goal is developers can easily tell what things are highly likely to - impact them and when <https://crbug.com/568218> - - #### Concrete plan for deprecation API - - <https://crbug.com/564071> - - #### Establish regular triage of Hotlist-PredictabilityInfra bugs - - Combined with hotlist-interop triage? - - ### Improve web platform feature interoperability - - Partner with feature teams to invest in improving interop in specific - high-return areas (as an exception to the general rule that teams own their - own interop). - - #### Ship the unprefixed Fullscreen API - - #### Ship the fullscreen top-layer rewrite - - Shared with layout-dev - - #### Concrete standards proposal and tests for event loop behavior - - <https://github.com/atotic/event-loop> - * Land interop tests for promise resolution behavior, file - bugs for failures in all browsers - * Specify that some events fire just before rAF - * Engage other vendors in discussion about which events should - be defined to be coupled to rAF, and to what extent their - order should be defined - * Write interop tests for rAF-coupled events - - #### At least bi-weekly triage of Hotlist-Interop issues - - Triage process here: - <https://docs.google.com/document/d/1fDE3cFjQta0i7zx7JY1Icx0NNRS20HACz4uKb3Wo3hI/edit?pref=2&pli=1> - - #### STRETCH: Concrete shipping plan for unprefixed fullscreen in WebKit, EdgeHTML and Gecko - - ### Improve communication with web developers - - #### Own chromestatus.com and drive its improvement - - * Take ownership of codebase, understand its structure - * Chromestatus is instrumented and we understand where people - are going on the site - * Meet with teams to discuss pain points and areas for - improvement for Chromestatus - * Best practices and guidance for using Chromestatus are - documented and visible \*on Chromestatus\* - * Meet with Mozilla, Microsoft, Opera to discuss merging all - status trackers - - #### Create and distribute a GCS / Endor survey to inform developer survey - - #### Reach consensus within Google on our developer feedback strategy - - go/webdevfeedback - - #### Create and distribute a comprehensive developer survey - - * Buy in from all major parties on survey including primary - learnings we want - * First draft of survey completed - * Final draft of survey agreed upon by all major parties - * Survey distributed and gathering feedback - - ### Reduce footguns in the web platform - - Make it easier for web developers to reason about behavior of their - applications, especially when they're composed of multiple 3rd-party - components. - * **Initial implementation of Feature Policy (behind a flag)** - * Parse response header to construct policy - * Remove features based on policy - (document.{write,cookie,domain}, SyncXHR, WebRTC) - * Propagate removal to embedded frames - * **V1 Feature policy spec feature-complete** - * converge on v1 set of must-have features - * figure out all the spec plumbing and interop bits - * draft explainer, engage other browser vendors + developers - * **Integrate permission delegation with feature policy** - * Enforce API permissions based on parsed feature policy
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/public-c-api/index.md b/chromium/docs/website/site/blink/public-c-api/index.md deleted file mode 100644 index a8d604f56d6..00000000000 --- a/chromium/docs/website/site/blink/public-c-api/index.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: public-c-api -title: Public C++ API ---- - -## [TOC] - -## Overview - -The Blink public API (formerly known as the WebKit API) is the C++ embedding -layer by which Blink and its embedder (Chromium) communicate with each other. -The API is divided into two parts - the web API, located in -[public/web](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/blink/public/web/)/, -and the platform API located in -[public/platform/](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/blink/public/platform/). -The embedder uses the web API to talk to Blink and Blink uses the platform API -to ask the embedder to perform lower-level tasks. The platform API also provides -common types and functionality used in both the web and platform APIs. - -This shows the overall dependency layers. Things higher up in the diagram depend -only on things below them. - -+-------------------------------------------+ - -| Embedder (Chromium) | - -+-------------------------------------------+ - -| Blink public web API | - -+---------------------+ | - -| Blink internals | | - -+-------------------------------------------+ - -| Blink public platform API | - -+-------------------------------------------+ - -| Embedder-provided platform implementation | - -+-------------------------------------------+ - -The web API covers concepts like the DOM, frames, widgets and input handling. -The embedder typically owns a -[WebView](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/blink/public/web/web_view.h) -which represents a page and navigates -[WebFrame](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/blink/public/web/web_frame.h)s -within the page. Many objects in the web API are actually thin wrappers around -internal Blink objects. - -The platform API covers concepts like graphics, networking, database access and -other low-level primitives. The platform API is accessible to nearly all of -Blink's internals. The platform API is provided through an implementation of the -pure virtual blink::Platform interface provided when Blink is initialized. Most -of the platform API is expressed by pure virtual interfaces implemented by the -embedder. - -### Conventions and common idioms - -#### Naming - -The Blink API follows the [Blink coding -conventions](https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/c++/blink-c++.md). - -All public Blink API types and classes are in the namespace `blink` and have the -prefix `Web`, both mostly for historical reasons. Types that are thin wrappers -around Blink internal classes have the same name as the internal class except -for the prefix. For instance, `blink::WebFrame` is a wrapper around -`blink::Frame`. - -Enums in the public Blink API prefix their values with the name of the enum. For -example: - -```none -enum WebMyEnum { - kWebMyEnumValueOne, - kWebMyEnumValueTwo, - ... -}; -``` - -No prefixes are needed for "`enum class`". - -```none -enum class WebMyEnum { - kValueOne, - kValueTwo, - ... -}; -``` - -#### WebFoo / WebFooClient - -Many classes in the Blink API are associated with a client. This is typically -done when the API type is a wrapper around a Blink internals class and the -client is provided by the embedder. In this pattern, the `WebFooClient` and the -`WebFoo` are created by the embedder and the embedder is responsible for -ensuring that the lifetime of the `WebFooClient` is longer than that of the -`WebFoo`. For example, the embedder creates a `WebView` with a `WebViewClient*` -that it owns (see -[`WebView::create`](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/blink/public/web/web_view.h&q=WebView::create&sq=package:chromium&type=cs)). - -#### Wrapping a RefCounted Blink class - -Many public API types are value types that contain references to Blink objects -that are reference counted. For example, -[WebNode](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/public/web/WebNode.h) -contains a reference to a -[Node](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/core/dom/Node.h). -To do this, `web_node.h` has a forward declaration of `Node` and `WebNode` has a -single member of type -[`WebPrivatePtr`](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/public/platform/WebPrivatePtr.h)`<Node>`. -`WebNode` also exports a `WebNode::reset()` that can dereference this member -(and thus potentially invoke the `Node` destructor). There's also a -[`WebPrivateOwnPtr`](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/public/platform/WebPrivateOwnPtr.h)`<T>` -for wrapping types that are single ownership.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/removing-features/index.md b/chromium/docs/website/site/blink/removing-features/index.md deleted file mode 100644 index 09794f69c0a..00000000000 --- a/chromium/docs/website/site/blink/removing-features/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: removing-features -title: Breaking changes ---- - -## This page has been deprecated, refer to - -* ## Deprecating Features in [Launching - Features](/blink/launching-features#TOC-Feature-deprecations)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/runtime-enabled-features/index.md b/chromium/docs/website/site/blink/runtime-enabled-features/index.md deleted file mode 100644 index bf700b18dac..00000000000 --- a/chromium/docs/website/site/blink/runtime-enabled-features/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: runtime-enabled-features -title: Runtime Enabled Features ---- - -## This content has moved to the Chromium source tree. - -## See the [Runtime Enabled Features guide](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/platform/RuntimeEnabledFeatures.md) there.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/serviceworker/getting-started/index.md b/chromium/docs/website/site/blink/serviceworker/getting-started/index.md deleted file mode 100644 index 26d12293e62..00000000000 --- a/chromium/docs/website/site/blink/serviceworker/getting-started/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/serviceworker - - Service workers -page_name: getting-started -title: Getting Started ---- - -### For web developer documentation, see: - -* [Jake Archibald's - "simple-serviceworker-tutorial"](https://github.com/jakearchibald/simple-serviceworker-tutorial) -* ["Introduction to Service - Worker"](http://www.html5rocks.com/en/tutorials/service-worker/introduction/) - at html5rocks.com -* ["The Offline - Cookbook"](http://jakearchibald.com/2014/offline-cookbook/) -* ["Is Service Worker Ready - Yet?"](https://jakearchibald.github.io/isserviceworkerready/) - -If you are a Chromium developer, read on! - -Here's how to get a demo Service Worker up and running: - -**Steps:** - -1. Open the demo at - <https://googlechrome.github.io/samples/service-worker/basic/index.html> - ([source](https://github.com/GoogleChrome/samples)) -2. Open the Inspector. Things are logged there later on. -3. Try visiting Cleveland and get a 404. Go back. -4. Click the 'Register' button, watch the Inspector console, then try - visiting Cleveland again... ***oooh***. -5. Go to chrome://inspect#service-workers and click on Inspect to open - the Inspector and debug your Service Worker. - -### Running it locally - -* Clone the [git repo](https://github.com/GoogleChrome/samples) -* Navigate to the samples/service-worker/basic folder -* Start a local webserver (see below) -* Open http://localhost:8080/index.html (or whatever path and port you - set up.) -* Feel free to edit the JS and try some new things! - -### How to run a local server - -On a system with python: - -$ python -m SimpleHTTPServer 8080 - -On Android use Chrome Developer Tools' [port -forwarding](https://developer.chrome.com/devtools/docs/remote-debugging#enable-reverse-port-forwarding). - -### Development flow - -In order to guarantee that the latest version of your Service Worker script is -being used, follow these instructions: - -1. Configure your local server to serve your Service Worker script as - non-cacheable (cache-control: no-cache) -2. After you made changes to your service worker script: - 1. **close all but one** of the tabs pointing to your web - application - 2. hit **shift-reload** to bypass the service worker as to ensure - that the remaining tab isn't under the control of a service - worker - 3. hit **reload** to let the newer version of the Service Worker - control the page. - -### Documentation - -* For an overview of the possibilities: Jake's [ServiceWorker is - coming, look busy](https://www.youtube.com/watch?v=SmZ9XcTpMS4) talk - (30min)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/serviceworker/index.md b/chromium/docs/website/site/blink/serviceworker/index.md deleted file mode 100644 index 695f40a84dd..00000000000 --- a/chromium/docs/website/site/blink/serviceworker/index.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: serviceworker -title: Service workers ---- - -<div class="two-column-container"> -<div class="column"> - -## For Web Developers - -## What is service worker? - -See the [service -worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) -documentation at Mozilla Developer Network. - -### Debugging - -Working with a service worker is a little different than normal debugging. Check -out [Service Worker Debugging](/blink/serviceworker/service-worker-faq) for -details. - -## Track Status - -Service workers shipped in Chrome 40 (which was promoted to stable channel in -January 2015). - -[Is Service Worker -Ready?](https://jakearchibald.github.io/isserviceworkerready/) tracks the -implementation status of service worker at a fine-grained, feature-by-feature -level in many popular browsers. - -### File Bugs - -Go to <http://crbug.com/new> and include "service worker" in the summary. You -should get a response from an engineer in about one week. - -If the browser **crashed** while you were doing Service Worker development, go -to chrome://crashes and cut and paste the Crash ID into the bug report. This -kind of bug report is very valuable to us. (If you do not see crashes in -chrome://crashes it may be because you chose not to send usage statistics and -crash reports to Google. You can change this option in chrome://settings .) - -To give feedback about service worker that is not specific to Chromium, use -W3C's [public-webapps mailing -list](http://lists.w3.org/Archives/Public/public-webapps/). Use [the spec issue -tracker](https://github.com/slightlyoff/ServiceWorker) to file bugs against the -service worker spec. - -### Discuss - -For detailed questions about usage: ask us on -[StackOverflow](http://stackoverflow.com) with the -"[service-worker](http://stackoverflow.com/questions/tagged/service-worker)" -tag. - -For important announcements and technical discussion about Service Worker, [join -us at -service-worker-discuss@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/service-worker-discuss). - -</div> -<div class="column"> - -## For Chromium & Blink Contributors - -...interested web developers are welcome to poke around too! - -### Links - -* Spec [issues](https://github.com/slightlyoff/ServiceWorker), - [FPWD](http://www.w3.org/TR/2014/WD-service-workers-20140508/), - [ED](https://slightlyoff.github.io/ServiceWorker/spec/service_worker/) -* [Testing](/blink/serviceworker/testing) -* Implementation bugs use the - [Blink>ServiceWorker](https://bugs.chromium.org/p/chromium/issues/list?q=component:Blink%3EServiceWorker) - component. If you sign-in, you can subscribe to get e-mail updates - at Profile > Saved Queries. -* Mailing lists: we use - [blink-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/blink-dev) - for public discussion. -* Code reviews: subscribe to the - [serviceworker-reviews@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/serviceworker-reviews) - group to get a copy of all code review requests. -* Docs: - * [Hitchhiker's guide to Service Worker - classes](https://docs.google.com/a/chromium.org/document/d/1DoueYsm-UOvqDyqIPd9aGAWWQ1XZKX89CsJXDF7j_2Q/edit) - * [How to Implement a Web Platform Feature on Service - Workers](https://docs.google.com/document/d/1cBZay5IbPHFLtDpFPu7q9XevtydiuTKbqXKIFaBZDJQ/edit?usp=sharing) - -</div> -</div>
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/serviceworker/service-worker-faq/index.md b/chromium/docs/website/site/blink/serviceworker/service-worker-faq/index.md deleted file mode 100644 index a944787941d..00000000000 --- a/chromium/docs/website/site/blink/serviceworker/service-worker-faq/index.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/serviceworker - - Service workers -page_name: service-worker-faq -title: Service Worker Debugging ---- - -**Q: How do I debug?** - -A: From a page on the same origin, go to Developer Tools > Application > -Service Workers. - -You can also use chrome://inspect/#service-workers to find all running service -workers. - -To poke around at the internals (usually only Chromium developers should need -this), visit chrome://serviceworker-internals . - -**Q: When I have Developer Tools open, requests go straight to the network; the -Service Worker does not get a fetch event.** - -A: On the Developer Tools' Network tab, if Disable cache is checked, requests -will go to the network instead of the Service Worker. Uncheck that. - -**Q: I get an error message about "Only secure origins are allowed". Why?** - -A: Service workers are only available to "secure origins" (HTTPS sites, -basically) in line with a policy to [prefer secure origins for powerful new -features](/Home/chromium-security/prefer-secure-origins-for-powerful-new-features). -However http://localhost is also considered a secure origin, so if you can, -developing on localhost is an easy way to avoid this error. - -You can also use the --unsafely-treat-insecure-origin-as-secure command-line -flag to explicitly list a HTTP Origin. For example: - -**$ ./chrome ---unsafely-treat-insecure-origin-as-secure=http://your.insecure.site:8080** - -([Prior to Chrome -62](https://chromium.googlesource.com/chromium/src/+/55dab613843031ab360193116f5d80d0d23308fb), -you must also include the --user-data-dir=/test/only/profile/dir to create a -fresh testing profile for the unsafely-treat-insecure-origin-as-secure flag to -work.) - -If you want to test on https://localhost with a self-signed certificate, do: - -**$ ./chrome --allow-insecure-localhost https://localhost** - -You might also find the --ignore-certificate-errors flag useful. - -**Q: I made a change to my service worker. How do I reload?** - -A: From Developer Tools > Application > Service Workers, check "Update on -reload" and reload the page. - -**Q: I have a different question.** - -A: Reach us out via -[service-worker-discuss](https://groups.google.com/a/chromium.org/forum/#!forum/service-worker-discuss) -or Stack Overflow with -"[service-worker](http://stackoverflow.com/questions/tagged/service-worker)" -hash tag. - -## Experimental Service Worker Debugging functionality - -### Step-wise SW debugging - -Chrome 44 required, but no experiments needed. Debugging message flow using -conventional breakpoint debugging on both ends (page and the sw). You can kill -the worker to debug its installation, you can debug the way it serves resources, -etc. - -### Active SW in Sources - -* Navigate to a page w/ service worker, opens DevTools -* Worker is displayed in the Threads list -* Service Workers tab lists Active Running service workers this page - (its iframes) belong to - -<img alt="image" -src="https://lh6.googleusercontent.com/e4cfdjN0GVnRqgeVr85oZ4FajaI5Lc8U-pkfTWoJ8HxyQ1Tigg40nzfpDDdRlEUIPu7M68wGM0qmsvJz-wu6lDvwInvNmfW-d8wP3gKpXCOomU-VTNVtH_VTWgmuZFTXJ8vU24A"> - -### Console execution - -* Console displays contexts for frames as well as workers -* One can execute expressions in the SW context and filter by context - -<img alt="image" -src="https://lh6.googleusercontent.com/HIP54ymxanAUqevqNfK4FzzgK3BsQSxoUJEM70K7i3oiJYImMvW9igdCXMwsMSLv1Uys6w6TObJdjCMklr0Eq_qW3BEpkHCyiDT7scgVz0ytNX7ma7bY9HUrAPdD6s-rPMEfpqc"> - -<img alt="image" -src="https://lh5.googleusercontent.com/UtOGH7s6zefhEmr9-uYHqKwhOPT6Iup5qM8Gy2FcA59FLiL2l-lw2zhEAiTK_vuiHpJjHSaptlvyXEINS6s2NyGBC_eVBECStddOdLQqJtxjOpCkJ_gkA_om7JtaC0JrruOzl9s"> - -### Console errors - -* Should there be any installation errors (syntax errors in main - script), they are available in the page console -* Clicking on the error message reveals the erroneous script - -<img alt="image" -src="https://lh6.googleusercontent.com/lYsWZUJ21KTbr23up6cV6gKkYQOrQ0VwORZ6Z_zPzrXhAaKzqFTVeEbRK3w6srjfS_gcb_aLvHrSEdEIe5KvC1Hm7oVHqac4RwUeVlhe2cpYJF_8fCZSzz9CcBLPVVymV_kXlvo"> - -### Breakpoints - -* User can set breakpoints in the service worker scripts -* Should user set the breakpoint, Stop the service worker and reload - the page, service worker will stop on that breakpoint - -<img alt="image" -src="https://lh5.googleusercontent.com/F9kDEzN4Bsec-TL5HOcUdRh_JvYrw7C0IjWQ0Kz8Usq-v6ZwlLlO8Ve-DBeTYrP0ETY5jjrOE2Ms2Df-LgYRktMBfJuSaCz-t4lpENLYivqgUqY9wH7qFoYGudOt0Xg0jQ2FxC8"> - -## SW debugging panel in Resources - -1. Turn on DevTools experiments (in `about:flags`) -2. In DevTools, Go to Settings -> Experiments, hit Shift 6 times -3. Check "Service worker inspection", close and reopen DevTools -4. Now you have this experiment enabled. - -This experiment unlocks a view in Resources just like you asked. -[<img alt="image" -src="/blink/serviceworker/service-worker-faq/resources-sw.png">](/blink/serviceworker/service-worker-faq/resources-sw.png) -Currently, to view network activity of the worker, click the "inspect" from -Resources to launch a dedicated devtools window for the worker itself.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/serviceworker/service-worker-faq/resources-sw.png.sha1 b/chromium/docs/website/site/blink/serviceworker/service-worker-faq/resources-sw.png.sha1 deleted file mode 100644 index c380da221d9..00000000000 --- a/chromium/docs/website/site/blink/serviceworker/service-worker-faq/resources-sw.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -acc9347f58424ba9013861bfadeebf190a76ef60
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/serviceworker/testing/index.md b/chromium/docs/website/site/blink/serviceworker/testing/index.md deleted file mode 100644 index 82ec1213e61..00000000000 --- a/chromium/docs/website/site/blink/serviceworker/testing/index.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/serviceworker - - Service workers -page_name: testing -title: Service Worker Testing ---- - -[TOC] - -Service Worker has multiple kinds of tests: Content Browser Tests, WebKit Unit -Tests, Telemetry Performance Tests, and Blink Layout Tests. - -## Performance Tests - -### [Issue 372759](https://code.google.com/p/chromium/issues/detail?id=372759) is tracking the development of Service Worker performance tests. - -How to run the performance tests: - -1. Build and install the content_shell_apk target per the [Android - build - instructions](https://code.google.com/p/chromium/wiki/AndroidBuildInstructions#Build_Content_shell). -2. Build the forwarder2 target. -3. tools/perf/run_benchmark --browser=android-content-shell - \[--device=xxxx\] service_worker.service_worker - -How to update the performance tests: - -1. Check out the [performance test - sources](https://github.com/coonsta/Service-Worker-Performance). Do - development, pull request, etc. -2. Run a local server in that directory, for example: twistd -n web - --path . --port 8091 (you must use that port number, it appears in - the test Python scripts.) -3. Build Linux Release Chromium - -[The update_wpr tool](https://source.chromium.org/chromium/chromium/src/+/main:tools/perf/recording_benchmarks.md) -automates the following steps for you: - -4. tools/perf/record_wpr --browser=release - --extra-browser-args='--enable-experimental-web-platform-features' - service_worker_page_set - Note: If you change the output directory of build (like 'out_desktop'), you - can use '--browser=exact --browser-executable=path/to/your/chrome' instead - of '--browser=release'. -5. Briefly sanity check the - tools/perf/page_sets/data/service_worker_nnn.wpr file to see that it - doesn't contain requests that should have been handled by a Service - Worker (look for GET and browse through the URLs.) -6. Add the new SHA1 hash file (use git status to find it) and upload - for review, commit as usual. Mention the path and commit hash from - step 1. - -## Web Tests Style - -If your test needs to interact with the Service Worker as a client (many do), -open an iframe with a URL controlled by the Service Worker. - -Prefix Service Worker scopes with "scope/" when appropriate. This helps prevent -unintentionally registering a Service Worker that controls resources in the test -directory. - -Prefix each test by unregistering the Service Worker. If a previous test run -failed or was interrupted, it may have left a Service Worker registration in -place. Unregistering the existing Service Worker first, if any, improves the -reliability of the test. - -Clean up resources when the test is done: Unregister the test's Service Worker -at the end of the test. Remove any iframes.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/sheriffing/index.md b/chromium/docs/website/site/blink/sheriffing/index.md deleted file mode 100644 index bc72f04211e..00000000000 --- a/chromium/docs/website/site/blink/sheriffing/index.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: sheriffing -title: Handling Blink failures ---- - -AKA gardening or sheriffing. See also [the documentation of the Test -Expectations -files](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/web_test_expectations.md), -the [generic sheriffing docs](/developers/tree-sheriffs), and the -[Chromium-specific sheriffing -docs](/developers/tree-sheriffs/sheriff-details-chromium). - -## Bots - -Chromium has many kinds of bots which run different kinds of builds and tests. -The [chromium.webkit](https://build.chromium.org/p/chromium.webkit/waterfall) -builders run the Blink-specific tests. - -You can monitor them using -[Sheriff-o-matic](https://sheriff-o-matic.appspot.com/) , just like the -non-Blink bots. - -Even among the WebKit bots, there are several different kinds of bots: - -* ["Layout" - bots](https://build.chromium.org/p/chromium.webkit/waterfall?category=layout&failures_only=true) - and [non-Oilpan - bots](https://build.chromium.org/p/chromium.webkit/waterfall?builder=WebKit+Win+non-Oilpan&builder=WebKit+Win+non-Oilpan+(dbg)&builder=WebKit+Mac+non-Oilpan&builder=WebKit+Mac+non-Oilpan+(dbg)&builder=WebKit+Linux+non-Oilpan&builder=WebKit+Linux+non-Oilpan+(dbg)) - * This is where most of the action is, because these bots run - Blink's many test suites. The bots are called "layout" bots - because one of the biggest test suites "Web Tests" was called - LayoutTests, which is found in third_party/blink/web_tests and - run as part of the webkit_tests step on these bots. Web tests - can have different expected results on different platforms. To - avoiding having to store a complete set of results for each - platform, most platforms "fall back" to the results used by - other platforms if they don't have specific results. Here's a - [diagram of the expected results fallback - graph](https://docs.google.com/a/chromium.org/drawings/d/1KBTihR80H42GB0be0qK2CyM-pPUoMdnHqYaOsNK85vI/edit). -* Leak bots - * These are just like the layout bots, except that if you need to - suppress a failure, use the - [web_tests/LeakExpectations](https://cs.chromium.org/chromium/src/third_party/blink/web_tests/LeakExpectations) - file instead. You can find some additional information in - [Gardening Leak - Bots](https://docs.google.com/a/google.com/document/d/11C7zFNKydrorESnE6Nbq98QNmKRMrhSwVMGxkx4fiZM/edit#heading=h.26irfde6145p) -* [ASAN - bot](http://build.chromium.org/p/chromium.webkit/waterfall?show=WebKit%20Linux%20ASAN) - * This also runs tests, but generally speaking we only care about - memory failures on that bot. You can suppress ASAN-specific - failures using the - [web_tests/ASANExpectations](https://cs.chromium.org/chromium/src/third_party/blink/web_tests/ASANExpectations) - file. -* [MSAN - bot](https://build.chromium.org/p/chromium.webkit/builders/WebKit%20Linux%20MSAN) - * Same deal as the ASAN bot, but catches a different class of - failures. You can suppress MSAN-specific failures using the - [web_tests/MSANExpectations](https://cs.chromium.org/chromium/src/third_party/blink/web_tests/MSANExpectations) - file. - -## Tools - -Generally speaking, developers are not supposed to land changes that knowingly -break the bots (and the try jobs and the commit queue are supposed to catch -failures ahead of time). However, sometimes things slip through ... - -### Sheriff-O-Matic - -[Sheriff-O-Matic](http://sheriff-o-matic.appspot.com/) is a tool that watches -the builders and clusters test failures with the changes that might have caused -the failures. The tool also lets you examine the failures. [There is more -documentation here](/developers/tree-sheriffs/sheriff-o-matic). - -### Rolling back patches - -To roll back patches, you can use either git revert or -[drover](/developers/how-tos/drover). You can also use "Revert" button on -Gerrit. - -### Flakiness dashboard - -The [flakiness -dashboard](http://test-results.appspot.com/dashboards/flakiness_dashboard.html#useWebKitCanary=true) -is a tool for understanding a test’s behavior over time. Originally designed for -managing flaky tests, the dashboard shows a timeline view of the test’s behavior -over time. The tool may be overwhelming at first, but [the -documentation](/developers/testing/flakiness-dashboard) should help. - -### Contacting patch authors - -Comment on the CL or send an email to contact the author. It is patch author's -responsibility to reply promptly to your query. - -**Test Directories** - -The web platform team has a large number of tests that are flaky, ignored, or -unmaintained. We are in the process of finding [teams to monitor test -directories](https://docs.google.com/spreadsheets/d/1c7O3fJ7aTY92vB5Dfyi_x2VYu4eFdeEeNTys6ECOviQ/edit?ts=57112a09#gid=0), -so that we can track these test issues better. Please note that this should not -be an individual, but a team. If you have ideas/guesses about some of these -directories, please reach out to the team and update the sheet. This is the -first step, and the long term plan is to have this information on a -dashboard/tool somewhere. Watch this space for updates!
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/sheriffing/triaging-gasper-alerts/index.md b/chromium/docs/website/site/blink/sheriffing/triaging-gasper-alerts/index.md deleted file mode 100644 index de20d0c316e..00000000000 --- a/chromium/docs/website/site/blink/sheriffing/triaging-gasper-alerts/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/sheriffing - - Handling Blink failures -page_name: triaging-gasper-alerts -title: Triaging Gasper Alerts ---- - -## Obsolete. - -## More relevant updated information at: <https://chromium.googlesource.com/chromium/src/+/HEAD/docs/speed/perf_regression_sheriffing.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/slimming-paint/historical-documents/index.md b/chromium/docs/website/site/blink/slimming-paint/historical-documents/index.md deleted file mode 100644 index 2ec6e9fefbe..00000000000 --- a/chromium/docs/website/site/blink/slimming-paint/historical-documents/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/slimming-paint - - Slimming Paint (a.k.a. Redesigning Painting and Compositing) -page_name: historical-documents -title: Historical documents ---- - -## Early design docs and explorations - -[Skia Recording -Changes](https://docs.google.com/document/d/1qNPBk60388ah5FoHwVunwbNZJtv5-n0N97cGDj0LdHY/edit?usp=sharing) - -[Refactoring Blink Paint -Code](https://docs.google.com/document/d/1inRhmB8rtxvInvmPEo7Zd5mhOfb48VxwF-9Y1QoQNBE/edit?usp=sharing) - -[Where to store Display -Items](https://docs.google.com/document/d/1iGJdE1hD15ISQKDh-I7m1R3MYiamvTlmsyplxts5n0g/edit?usp=sharing) - -[Layerization based on display -lists](https://docs.google.com/document/d/1L6vb9JEPFoyt6eNjVla2AbzSUTGyQT93tQKgE3f1EMc/edit?usp=sharing) - -[Pitfalls in DisplayList Creation for Slimming -Paint](https://docs.google.com/document/d/15c8gxDdJvBTBptHpXuQH4N_7XV7r1_BTbl3_CMBrdkU/edit?usp=sharing) - -[Tracking slimming paint -performance](https://docs.google.com/document/d/1moskT1Tkg8GcHZylRNQakyrCjk3LR_O5Yys9fDriVcY/edit#)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/slimming-paint/index.md b/chromium/docs/website/site/blink/slimming-paint/index.md deleted file mode 100644 index 12ef91d7e56..00000000000 --- a/chromium/docs/website/site/blink/slimming-paint/index.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: slimming-paint -title: Slimming Paint (a.k.a. Redesigning Painting and Compositing) ---- - -## Slimming Paint is a [Paint team](/teams/paint-team) project to re-implement the Blink<->cc picture recording API to work in terms of a global display list rather than a tree of cc::Layers (~aka GraphicsLayer in Blink terminology). It will result in a drastic simplification of the way that composited layers are represented in Blink and cc, which in turn will yield improved performance, correctness and flexibility. - -To get a sense of the extent of this rewrite, one side-effect will be the -deletion of the code in core/rendering/compositing/. - -## Phases - -SlimmingPaintV1 - paint using display items ([Status: launched in -M45](https://groups.google.com/a/chromium.org/forum/#!searchin/blink-dev/slimming$20paint/blink-dev/qq4NEaqSrKM/OKiNzm3PkSkJ)) - -SlimmingPaintInvalidation - rewrite of paint invalidation using display items, -property trees introduced in blink ([Status: launched in -M58](https://groups.google.com/a/chromium.org/forum/#!searchin/blink-dev/slimming$20paint/blink-dev/YXcuTl6PbDk/7jAte1CDBAAJ)) - -SlimmingPaintV175 - uses property trees for painting in blink, introduces paint -chunks, uses paint chunks for raster invalidation ([Status: launched in -M67](https://bugs.chromium.org/p/chromium/issues/detail?id=771643)) - -[BlinkGenPropertyTrees](https://docs.google.com/document/d/17GKr2uIH2O5GthdTyvJpv1qZjoHYoLgrzvCkbCHoID4/view#) -- sends a layer list instead of a tree, and generates final property trees in -blink instead of re-generating them in cc ([Status: launched in -M75](https://crbug.com/836884)) - -[CompositeAfterPaint](https://docs.google.com/document/d/114ie7KJY3e850ZmGh4YfNq8Vq10jGrunZJpaG6trWsQ/edit) -- compositing decisions made after paint. - -## Presentations - -[BlinkOn 3.0 -Presentation](https://docs.google.com/presentation/d/1zpGlx75eTNILTGf3s_F6cQP03OGaN2-HACsZwEobMqY/edit?usp=sharing), -[video](https://www.youtube.com/watch?v=5Xv2A7aqJ9Y) (start here to find out -more about the project) - -[BlinkOn 4 -presentation](https://docs.google.com/presentation/d/17k62tf1zc5opvIfhCXMiL4UdI9UGvtCJbUEKMPlWZDY/edit) - -[Blink Property -Trees](https://docs.google.com/presentation/d/1ak7YVrJITGXxqQ7tyRbwOuXB1dsLJlfpgC4wP7lykeo) -(also reviews the Composite-After-Paint (formerly "SPV2") design) - -[BlinkOn 9 -presentation](https://docs.google.com/presentation/d/1Iko1oIYb-VHwOOFU3rBPUcOO_9lAd3NutYluATgzV_0/view#slide=id.g36f1b50c08_0_1902) -covering current compositing architecture - -### Core team members - -Chris Harrelson (chrishtr@), overall TL - -Mason Freed (masonfreed@) Blink - -Philip Rogers (pdr@) Blink - -Stephen Chenney (schenney@) Blink - -Xianzhu Wang (wangxianzhu@) Blink - -Adrienne Walker (enne@) cc - -Robert Flack (flackr@) animations - -David Bokan (bokan@) viewports - -#### Close relatives - -Fredrik Söderquist (fs@opera.com) Blink - -Erik Dahlstrom (ed@opera.com) Blink - -Florin Malita (fmalita@) Blink / Skia - -Mike Klein (mtklein@) Skia - -Mike Reed (reed@) Skia - -A number of other people are involved at least tangentially for design -discussions and related projects. - -## Resources and Design Docs - -[core/paint/README.md](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/core/paint/README.md) - -[Slimming paint -invalidation](https://docs.google.com/document/d/1M669yu7nsF9Wrkm7nQFi3Pp2r-QmCMqm4K7fPPo-doA) - -[Representation and implementation of display lists in -Blink](https://docs.google.com/document/d/1fWvFIY41BJHtB4qBHw3_IZYqScurID4KmE2_a6Be0J4/edit?usp=sharing) - -[Layerization based on display -lists](https://docs.google.com/a/google.com/document/d/1L6vb9JEPFoyt6eNjVla2AbzSUTGyQT93tQKgE3f1EMc/edit) - -[Blink paintlist update algorithm -details](https://docs.google.com/document/d/1bvEdFo9avr11S-2k1-gT1opdYWnPWga68CK3MdoYV7k/edit?usp=sharing) - -==[Bounding Rectangle Strategy for Slimming -Paint](https://docs.google.com/a/chromium.org/document/d/12G3rfM3EkLYDCRcO1EpEObfeoU24Sqof9S0sPHgELU4/edit?usp=sharing)== - -[Slimming Paint for UI -Compositor](https://docs.google.com/a/chromium.org/document/d/1Oxa3E-ymCqY2-7AlMrL1GEqAtyFE__0PRzhg9EEZt7Y/edit) - -[Display Item -Debugging](https://docs.google.com/a/chromium.org/document/d/1XDz2paww41UjviZam1iTThS9XKx0KRcmzI83QuNLeR8/edit#) - -Some out of date/historical docs are -[here](/blink/slimming-paint/historical-documents).
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/spec-mentors/index.md b/chromium/docs/website/site/blink/spec-mentors/index.md deleted file mode 100644 index 4ba5584847e..00000000000 --- a/chromium/docs/website/site/blink/spec-mentors/index.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: spec-mentors -title: Chromium Specification Mentors ---- - -*Quick link:* [mentor request -form](https://docs.google.com/forms/d/e/1FAIpQLSfCYE4U13GkZ11rAWBUjOb3Lza-u4m2k3TklQHXe7Zfn3Qo1g/viewform) - -## Introduction - -Introducing a new feature to the web platform requires writing a specification, -which is a separate skill set from writing code. It involves API design, -cross-company collaboration, and balancing the needs of the web's various -stakeholders. - -Specification mentors apply their experience in this area to ensure that -explainers and specifications put out by the Chromium project are of high -quality and ready to present to the world. For folks new to the standardization -process, mentors can provide guidance and review. And for those who are already -experienced, mentors provide the equivalent of code review: a second perspective -to help raise questions early or spot things you might have missed. - -This process aims to improve the quality of explainers and specifications, and -thus uphold the Chromium project's commitment to an open, interoperable, and -well-designed web platform. It should also make the process of launching a new -feature more predictable and less painful for Chromium engineers. - -## How we work - -### Pairing up with your mentor - -Before sending an Intent to Prototype, you are encouraged to find a spec mentor -to work with. They can review your explainer, as well as the Intent to Prototype -itself, to make sure your feature is presenting a good face to the world. - -For Googlers, a specification mentor is required at this stage. For other -Chromium contributors, you're welcome to reach out if you find one helpful. - -To find a specification mentor, you can draw upon your existing contacts (e.g., -your team lead or coworkers), or you can [fill out our -form](https://docs.google.com/forms/d/e/1FAIpQLSfCYE4U13GkZ11rAWBUjOb3Lza-u4m2k3TklQHXe7Zfn3Qo1g/viewform) -with the relevant information. In the latter case, we will get back to you with -a proposed mentor within 2 business days; we want to make sure your Intent to -Prototype proceeds as quickly as possible. - -### What to expect - -Your mentor will be available for you to ask questions or ask for reviews -throughout the lifetime of your feature. In particular, if you would like -someone to review your explainer or specification work, you can collaborate with -them directly, e.g. using video calls, GitHub pull request reviews, or Google -Docs. - -There are three specific points at which you'll want to request detailed -specification review from your mentor, so that they can help ensure that your -public artifacts are high-quality: - -- (Optional) For your explainer and TAG review request, before sending them - out in the Intent to Prototype process. - -- For your explainer and specification, before beginning a [Dev Trial](https://docs.google.com/document/d/1_FDhuZA_C6iY5bop-bjlPl3pFiqu8oFvuK1jzAcyWKU/edit) - or [Origin Trial](https://github.com/GoogleChrome/OriginTrials), at which - point these artifacts will be seen by wide review groups and other browser - vendors. - -- For your specification, before sending an Intent to Ship. - -You can also call on your mentor to review the Intents themselves, before you -send them off to blink-dev and the scrutiny of the API owners and the wider -world. - -Your mentor can optionally reply to the Intent to Prototype/Experiment/Ship -threads with a summary of how the review went. This can help bolster the API -owners' confidence in the explainer or specification. For example: - -> "The use cases for this feature make a lot of sense. I raised an issue to -> consider some alternate approaches, and noted a potential privacy risk that -> should be at least discussed, and ideally mitigated. We agreed to keep these -> in mind as the prototyping progresses." - -or - -> "This feature and the proposed API both look good to ship from my perspective. -> I filed a series of small issues on potential API improvements, which have -> been incorporated. And we tightened up the specification language around the X -> algorithm, which now has extensive web platform tests for the -> previously-ambiguous edge cases." - -If all goes well, then by the time you reach the Intent to Ship stage, your -explainer and spec will have been refined through mentorship and review to be -the best they can be. This will put you in a strong position with regard to some -of the most-often-problematic parts of the Intent to Ship, such as the the -Interoperability & Compatibility risks section, and thus smooth the path toward -API OWNER approval. - -## Can I join? - -Yes, please do! Becoming proficient in design reviews is a core engineering -skill, and one of the best ways to do that is to help other Chromium project -members with their explainers and specifications. And it's important for the -health of the Chromium community to have as many engineers as possible who -understand and can work successfully within the standards process. - -If you've ever written an explainer or specification before, you've probably -gotten a good amount of feedback from various audiences, both internal and -external. That means you're qualified to help others through the same process, -to pass on what you have learned. You won't be alone: the other mentors are -around to help with anything you're not sure of. - -The time commitment for being a specification mentor should be similar to a -commensurate amount of Chromium code reviews, i.e., not that bad. - -To join the program and start getting assigned features to help mentor, -subscribe to our mailing list, at -[spec-mentors@chromium.org](https://groups.google.com/a/chromium.org/g/spec-mentors). -When new features come in, feel free to reply that you'd be willing to help; -otherwise, [domenic@chromium.org](mailto:domenic@chromium.org) will assign -features to mentors according to his best judgment.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/unittesting/index.md b/chromium/docs/website/site/blink/unittesting/index.md deleted file mode 100644 index dfd2b64faa1..00000000000 --- a/chromium/docs/website/site/blink/unittesting/index.md +++ /dev/null @@ -1,473 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: unittesting -title: Unit Testing in Blink ---- - -**WARNING: This document is a work in progress!** - -[TOC] - -## Unit Testing Tools - -GTest and GMock are both imported into Blink and can be used in unit tests. Most -existing tests are purely GTest based, but GMock is slowly being used more. - -### GTest - Google Unit Testing Framework - -> *"Google's framework for writing C++ tests on a variety of platforms (Linux, -> Mac OS X, Windows, Cygwin, Windows CE, and Symbian). Based on the xUnit -> architecture. Supports automatic test discovery, a rich set of assertions, -> user-defined assertions, death tests, fatal and non-fatal failures, value- and -> type-parameterized tests, various options for running the tests, and XML test -> report generation."* - -#### Further Documentation - -* GTest Project Website - <https://code.google.com/p/googletest/> -* Primer - <https://code.google.com/p/googletest/wiki/Primer> -* FAQ - <https://code.google.com/p/googletest/wiki/FAQ> -* Advanced Guide - - <https://code.google.com/p/googletest/wiki/AdvancedGuide> - -#### Tip: GTest and regular expressions (regexp) - -If you are using gtest "[Death -Tests](https://code.google.com/p/googletest/wiki/AdvancedGuide#How_to_Write_a_Death_Test)" -or GMock's EXPECT_THAT with MatchesRegex or ContainsRegex, you have to **be very -careful with your regex**. - -There is no common syntax between all operating system for character class -matches; - -* Character class short cuts are NOT part of the POSIX regex standard - and **DO NOT** work on Mac OS X. It also **wont** give you a warning - saying the regex is invalid. - -```none -EXPECT_THAT("abc", MatchesRegex("\w*")) # Does NOT work on Mac OS X. -``` - -* Character classes (IE the square bracketed kind) **DO NOT** work - with the gtest internal regex engine, and thus on Windows. At least - it will warn you that the regex is invalid. - -```none - EXPECT_THAT("abc", MatchesRegex("[a-c]*")) # Does NOT work on Windows. -``` - -*(CL <https://codereview.chromium.org/55983002/> proposes making chromium only -use the gtest internal regex engine which would fix this problem.)* - -#### Tip: Using GMock matchers with GTest - -You can use GMock EXPECT_THAT and the GMock matchers inside a GTest test for -more powerful matching. - -Quick example; - -```none -EXPECT_THAT(Foo(), testing::StartsWith("Hello"));EXPECT_THAT(Bar(), testing::MatchesRegex("Line \\d+"));ASSERT_THAT(Baz(), testing::AllOf(testing::Ge(5), testing::Le(10)));Value of: Foo() Actual: "Hi, world!"Expected: starts with "Hello" -``` - -More information at; - -* [TotT: Making a Perfect - Matcher](http://googletesting.blogspot.com.au/2009/10/tott-making-perfect-matcher.html) -* [GMock Cookbook - Using Matchers in Google Test - Assertions](https://code.google.com/p/googlemock/wiki/CookBook#Using_Matchers_in_Google_Test_Assertions) - -#### Error: Has the "template<typename T> operator T\*()" private. - -More information at <https://code.google.com/p/googletest/issues/detail?id=442> - -Workaround: - -<pre><code><b>namespace</b> testing { -<b>namespace</b> internal { -// gtest tests won't compile with clang when trying to EXPECT_EQ a class that -// has the "template<typename T> operator T*()" private. -// (See <https://code.google.com/p/googletest/issues/detail?id=442)> -// -// Work around is to define this custom IsNullLiteralHelper. -<b>char</b>(&IsNullLiteralHelper(<b>const</b> WebCore::CSSValue&))[2]; -} -} -</code></pre> - -### GMock - Google C++ Mocking Framework - -<https://code.google.com/p/googlemock/> - -> *Inspired by jMock, EasyMock, and Hamcrest, and designed with C++'s specifics -> in mind, Google C++ Mocking Framework (or GMock for short) is a library for -> writing and using C++ mock classes.* - -#### Further Documentation - -* \[TODO\] - -#### Tip: GMock and regular expressions (regexp) - -GMock uses the gtest for doing the regexs, [see the section under gtest -above](/blink/unittesting#TOC-Tip:-GTest-and-regular-expressions-regexp-). - -#### Tip: Mocking non-virtual functions - -For speed reasons, a majority of Blink's functions are non-virtual. This can -make them quite hard to mock. Here are some tips for working around these -problems; - -#### Tip: Mock Injection (Dependency Injection) - -Useful documentation: - -* TotT: Testing Against Interfaces - - <http://googletesting.blogspot.com.au/2008/07/tott-testing-against-interfaces.html> -* TotT: Defeat "Static Cling" - - <http://googletesting.blogspot.com.au/2008/06/defeat-static-cling.html> - -Using a proxy interface internally in your class; - -<pre><code>// MyClass.h -// ------------------------------------------------------------ -<b>class</b> MyClass { -<b>private</b>: - <b>class</b> iExternal { - <b>public</b>: - <b>virtual</b> <b>void</b> function1(<b>int</b> a, <b>int</b> b); - <b>virtual</b> <b>bool</b> function2(); - <b>static</b> iExternal* instance() { <b>return</b> pInstance(); } - <b>static</b> <b>void</b> setInstanceForTesting(iExternal* newInstance) { pInstance(true, newInstance); } - <b>static</b> <b>void</b> clearInstanceForTesting() { pInstance(true, 0); } - <b>protected</b>: - iExternal() { } - <b>private</b>: - <b>inline</b> <b>static</b> iExternal* pInstance(<b>bool</b> set = false, iExternal* newInstance = 0) - { - <b>static</b> iExternal* defaultInstance = <b>new</b> iExternal(); - <b>static</b> iExternal* instance = defaultInstance; - <b>if</b> (set) { - <b>if</b> (!newInstance) { - newInstance = defaultInstance; - } - instance = newInstance; - } - <b>return</b> instance; - } - }; -<b>public</b>: - <b>void</b> aFunction() { - <b>if</b> (iExternal::instance()->function2()) { - iExternal::instance()->function1(1, 2); - } - } -} -</code></pre> - -<pre><code>// MyClassTest.cpp -// ------------------------------------------------------------ -<b>class</b> MyClassTest : <b>public</b> ::testing::Test { - <b>class</b> iExternalMock : <b>public</b> MyClass::iExternal { - <b>public</b>: - MOCK_METHOD0(function1, <b>void</b>(<b>int</b>, <b>int</b>)); - MOCK_METHOD0(function2, <b>bool</b>()); - }; - <b>void</b> setInstanceForTesting(MyClass::iExternal& mock) { - MyClass::iExternal::setInstanceForTesting(&mock); - } -}; -TEST_F(MyClassTest, aFunctionTest) -{ - iExternalMock externalMock; - EXPECT_CALL(externalMock, function2()) - .WillOnce(Return(true)) - .WillOnce(Return(false)); - EXPECT_CALL(externalMock, function1(1, 2)); - setInstanceForTesting(externalMock); - MyClass c; - c.aFunction(); -} -</code></pre> - -#### Tip: Mocks and OwnPtr (PassOwnPtr) - -OwnPtr and mocking objects can be tricky to get right, here is some important -information. - -***The Problem*** - -As normal, once you return an object via a PassOwnPtr you no longer control the -life cycle of the object. This means that you **must not** use the object as an -expectation (EXPECT_CALL) for another function call because; - -* On each call, GMock checks if any of the expectations match. -* On termination, if something went wrong GMock might try to print the - expectation (for both matched and unmatched expectations). - -Here is some example code which is **WRONG**: - -* At **(1)** myA1 has been deleted, but GMock will check **both** the - mockb EXPECT_CALLs. -* At **(2)** both myA1 and myA2 have been deleted, but if EXPECT_CALL - is not matched GMock may try to print myA1 and myA2. - -<pre><code>// Actual implementation -<b>class</b> A {}; -<b>class</b> B { - <b>virtual</b> use(A& a) {} {} -}; -<b>class</b> C { - B* m_b; - C(B* b): m_b(b) {} - <b>void</b> doIt(PassOwnPtr<A> myA) { - m_b->use(*myA); - // As we own myA it gets deleted here. - } -}; -// Mocks -<b>class</b> MockB : <b>public</b> B { - MOCK_METHOD0(use, <b>void</b>(A&)); -}; -// Test -TEST(MyTest, CDoItTest) -{ - OwnPtr<A> myA1 = adoptPtr(<b>new</b> A()); - OwnPtr<A> myA2 = adoptPtr(<b>new</b> A()); - MockB mockb; - EXPECT_CALL(mockb, use(Ref(*myA1.get()))); // Ref() means "is a reference to" - EXPECT_CALL(mockb, use(Ref(*myA2.get()))); - C c(&mockb); - c.doIt(myA1.release()); - c.doIt(myA2.release()); // <b>(1)</b> - // <b>(2)</b> -} -</code></pre> - -***Solutions that don't work*** - -Creating a specialization of OwnedPtrDeleter - -> `template <> struct OwnedPtrDeleter<MyClass> {}` - -> **Why?** - -> > The OwnedPtrDeleter specialization must be visible at the location that the -> > OwnPtr/PassOwnPtr is created. - -## Test Helpers - -Test helpers are an important part of making Blink easier to test for everyone. -The more test helpers that exist, the easier it is to write new unit tests as -you have to write less boilerplate code and find it easier to debug failing -tests. - -Test helpers include; - -* Pretty printing functions for types. -* Shared fake implementations of complex types. -* Quick creation functions for types. -* `operator==` definitions to allow `EXPECT_EQ` and comparisons in - `EXPECT_CALL` mocks to work. - -Test helpers **should;** - -* be define in a "XXXTestHelper.h" file, where XXX is the type (or - type group) that it helps (there might also be a XXXTestHelper.cpp - in rare cases). -* have some basic tests to make sure they work. **Nobody wants to - debug test helpers while writing their own tests!** - * This is specially important for PrintTo functions to make sure - they actually print what you expect. You can use the - `EXPECT_THAT` with Regex from GMock to make these tests easier - to write. - * These should be in a XXXTestHelperTest.cpp file (shouldn't need - a header file). - -### Operator== - -Both the `EXPECT_EQ` and the `EXPECT_CALL` methods use `a == b` to compare if -two objects are equal. However for many reasons you don't want this operator to -be generally available in Blink. You can define the operator in the test helper -instead and then it will only be available during tests. - -Unlike PrintTo, operator== is not a template so the normal type hierarchy -applies. - -<pre><code><b>bool</b> <b>operator</b>==(<b>const</b> TYPE& a, <b>const</b> TYPE& b) -{ - <b>return</b> SOMETHING -} -</code></pre> - -#### **Operator== Gotchas - Namespacing** - -The **operator==** MUST be define in the same namespace as the type for -`EXPECT_EQ` to work. For example, if type is `::WebCore::AnimatableValue` the -operator must be in the `::WebCore` namespace. - -### Pretty Printers - -Pretty printers make it much easier to see what is going on in your test and why -a match isn't working. They should be created for any simple type which has a -useful string representation. - -```none -void PrintTo(const A& a, ::std::ostream* os) -{ - *os << "A@" << &a; -} -``` - -More Information on creating pretty printers can be found at [GTest Advanced -Guide: Teaching Google Test How to Print Your -Values](https://code.google.com/p/googletest/wiki/AdvancedGuide#Teaching_Google_Test_How_to_Print_Your_Values). - -#### **Pretty Printers Gotchas - Namespace** - -Pretty Printers **must** be define in the same namespace as the class which it -is printing. - -<pre><code> -<b>namespace</b> A { - <b>class</b> A{}; -} -<b>namespace</b> { - <b>void</b> PrintTo(<b>const</b> A& a, ::std::ostream* os) {} // Never called -} -</code></pre> - -#### **Pretty Printers Gotchas - Type matching** - -Pretty Printers only work on **exact** and **known** type match. This means -that; - -* A PrintTo for a base class will not apply to children classes. -* A PrintTo for a specific class will not apply when that class is - referenced/pointed to as a base class. - -Further information at the gtest bug tracker - -<https://code.google.com/p/googletest/issues/detail?id=443> - -This is hard to understand, but shown by the following example (also attached as -printto-confusing.cpp). - -<pre><code> -#include <iostream> -#include <gtest/gtest.h> -<b>using</b> std::cout; -<b>using</b> testing::PrintToString; -<b>class</b> A {}; -<b>class</b> B : <b>public</b> A {}; -<b>class</b> C : <b>public</b> B {}; -<b>void</b> PrintTo(<b>const</b> A& a, ::std::ostream* os) -{ - *os << "A@" << &a; -} -<b>void</b> PrintTo(<b>const</b> B& b, ::std::ostream* os) -{ - *os << "B@" << &b; -} -<b>int</b> main() { - A a; - B b; - C c; - A* a_ptr1 = &a; - B* b_ptr = &b; - A* a_ptr2 = &b; - C* c_ptr = &c; - A* a_ptr3 = &c; - cout << PrintToString(a) << "\n"; // A@0xXXXXXXXX - cout << PrintToString(b) << "\n"; // B@0xYYYYYYYY - cout << PrintToString(c) << "\n"; // 1-byte object <60> - cout << PrintToString(*a_ptr1) << "\n"; // A@0xXXXXXXXX - cout << PrintToString(*b_ptr) << "\n"; // B@0xYYYYYYYY - cout << PrintToString(*a_ptr2) << "\n"; // A@0xYYYYYYYY -} -</code></pre> - -You can work around this problem by also defining a couple of extra PrintTo -methods (also attached as printto-workaround.cpp). - -<pre><code>#include <iostream> -#include <gtest/gtest.h> -<b>using</b> std::cout; -<b>using</b> testing::PrintToString; -#define OVERRIDE override -// MyClass.h -// --------------------------------------------------------------- -<b>class</b> MyClassA { -// As WebKit is compiled without RTTI, the following idiom is used to -// emulate RTTI type information. -<b>protected</b>: - <b>enum</b> MyClassType { - BType, - CType - }; - <b>virtual</b> MyClassType type() <b>const</b> = 0; -<b>public</b>: - <b>bool</b> isB() <b>const</b> { <b>return</b> type() == BType; } - <b>bool</b> isC() <b>const</b> { <b>return</b> type() == CType; } -}; -<b>class</b> MyClassB : <b>public</b> MyClassA { - <b>virtual</b> MyClassType type() <b>const</b> OVERRIDE { <b>return</b> BType; } -}; -<b>class</b> MyClassC : <b>public</b> MyClassB { - <b>virtual</b> MyClassType type() <b>const</b> OVERRIDE { <b>return</b> CType; } -}; -// MyClassTestHelper.h -// --------------------------------------------------------------- -<b>void</b> PrintTo(<b>const</b> MyClassB& b, ::std::ostream* os) -{ - *os << "B@" << &b; -} -// Make C use B's PrintTo -<b>void</b> PrintTo(<b>const</b> MyClassC& c, ::std::ostream* os) -{ - PrintTo(*<b>static_cast</b><<b>const</b> MyClassB*>(&c), os); -} -// Call the more specific subclass PrintTo method -// *WARNING*: The base class PrintTo must be defined *after* the other PrintTo -// methods otherwise it'll just call itself. -<b>void</b> PrintTo(<b>const</b> MyClassA& a, ::std::ostream* os) -{ - <b>if</b> (a.isB()) { - PrintTo(*<b>static_cast</b><<b>const</b> MyClassB*>(&a), os); - } <b>else</b> <b>if</b> (a.isC()) { - PrintTo(*<b>static_cast</b><<b>const</b> MyClassC*>(&a), os); - } <b>else</b> { - //ASSERT_NOT_REACHED(); - } -} -<b>int</b> main() { - MyClassB b; - MyClassC c; - MyClassB* b_ptr = &b; - MyClassA* a_ptr1 = &b; - MyClassC* c_ptr = &c; - MyClassA* a_ptr2 = &c; - cout << PrintToString(b) << "\n"; // B@0xYYYYYYYY - cout << PrintToString(*b_ptr) << "\n"; // B@0xYYYYYYYY - cout << PrintToString(*a_ptr1) << "\n"; // B@0xYYYYYYYY - cout << PrintToString(c) << "\n"; // B@0xAAAAAAAA - cout << PrintToString(*c_ptr) << "\n"; // B@0xAAAAAAAA - cout << PrintToString(*a_ptr2) << "\n"; // B@0xAAAAAAAA -} -</code></pre> - -## Future Proposals - -All these issues are up for discussion and have yet to be decided on; - -* Creation of high quality fake objects for core blink components. - Each fake should be created and maintained by the OWNERS that owns - the real implementation. See [Testing on the Toilet: Know Your Test - Doubles](http://googletesting.blogspot.com.au/2013/06/testing-on-toilet-fake-your-way-to.html), - TotT: Fake Your Way to Better Tests - - <http://googletesting.blogspot.com.au/2013/06/testing-on-toilet-fake-your-way-to.html> -* Creation of test helpers for all objects in Blink. -* Split unit tests into their own build unit rather then one big - "webkit_unittest" (faster test building and linking, ability to use - mocks via inclusion)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/unittesting/printto-confusing.cpp b/chromium/docs/website/site/blink/unittesting/printto-confusing.cpp deleted file mode 100644 index a82a35cc2de..00000000000 --- a/chromium/docs/website/site/blink/unittesting/printto-confusing.cpp +++ /dev/null @@ -1,39 +0,0 @@ -#include <iostream> -#include <gtest/gtest.h> - -using std::cout; -using testing::PrintToString; - -class A {}; -class B : public A {}; -class C : public B {}; - - -void PrintTo(const A& a, ::std::ostream* os) -{ - *os << "A@" << &a; -} - -void PrintTo(const B& b, ::std::ostream* os) -{ - *os << "B@" << &b; -} - -int main() { - A a; - B b; - C c; - - A* a_ptr1 = &a; - B* b_ptr = &b; - A* a_ptr2 = &b; - C* c_ptr = &c; - A* a_ptr3 = &c; - - cout << PrintToString(a) << "\n"; // A@0xXXXXXXXX - cout << PrintToString(b) << "\n"; // B@0xYYYYYYYY - cout << PrintToString(c) << "\n"; // 1-byte object <60> - cout << PrintToString(*a_ptr1) << "\n"; // A@0xXXXXXXXX - cout << PrintToString(*b_ptr) << "\n"; // B@0xYYYYYYYY - cout << PrintToString(*a_ptr2) << "\n"; // A@0xYYYYYYYY -} diff --git a/chromium/docs/website/site/blink/unittesting/printto-workaround.cpp b/chromium/docs/website/site/blink/unittesting/printto-workaround.cpp deleted file mode 100644 index e70e7622fc3..00000000000 --- a/chromium/docs/website/site/blink/unittesting/printto-workaround.cpp +++ /dev/null @@ -1,80 +0,0 @@ -#include <iostream> -#include <gtest/gtest.h> - -using std::cout; -using testing::PrintToString; - -#define OVERRIDE override - -// MyClass.h -// --------------------------------------------------------------- - -class MyClassA { - -// As WebKit is compiled without RTTI, the following idiom is used to -// emulate RTTI type information. -protected: - enum MyClassType { - BType, - CType - }; - - virtual MyClassType type() const = 0; - -public: - bool isB() const { return type() == BType; } - bool isC() const { return type() == CType; } -}; - -class MyClassB : public MyClassA { - virtual MyClassType type() const OVERRIDE { return BType; } -}; -class MyClassC : public MyClassB { - virtual MyClassType type() const OVERRIDE { return CType; } -}; - -// MyClassTestHelper.h -// --------------------------------------------------------------- - -void PrintTo(const MyClassB& b, ::std::ostream* os) -{ - *os << "B@" << &b; -} - -// Make C use B's PrintTo -void PrintTo(const MyClassC& c, ::std::ostream* os) -{ - PrintTo(*static_cast<const MyClassB*>(&c), os); -} - -// Call the more specific subclass PrintTo method -// *WARNING*: The base class PrintTo must be defined *after* the other PrintTo -// methods otherwise it'll just call itself. -void PrintTo(const MyClassA& a, ::std::ostream* os) -{ - if (a.isB()) { - PrintTo(*static_cast<const MyClassB*>(&a), os); - } else if (a.isC()) { - PrintTo(*static_cast<const MyClassC*>(&a), os); - } else { - //ASSERT_NOT_REACHED(); - } -} - -int main() { - MyClassB b; - MyClassC c; - - MyClassB* b_ptr = &b; - MyClassA* a_ptr1 = &b; - MyClassC* c_ptr = &c; - MyClassA* a_ptr2 = &c; - - cout << PrintToString(b) << "\n"; // B@0xYYYYYYYY - cout << PrintToString(*b_ptr) << "\n"; // B@0xYYYYYYYY - cout << PrintToString(*a_ptr1) << "\n"; // B@0xYYYYYYYY - - cout << PrintToString(c) << "\n"; // B@0xAAAAAAAA - cout << PrintToString(*c_ptr) << "\n"; // B@0xAAAAAAAA - cout << PrintToString(*a_ptr2) << "\n"; // B@0xAAAAAAAA -} diff --git a/chromium/docs/website/site/blink/v8-bindings/index.md b/chromium/docs/website/site/blink/v8-bindings/index.md deleted file mode 100644 index de201e8fe02..00000000000 --- a/chromium/docs/website/site/blink/v8-bindings/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: v8-bindings -title: V8 Bindings, Promises ---- - -* [Promise helpers design - doc](https://docs.google.com/a/chromium.org/document/d/1WphFrSM18-m6b4RFaBxwLL_zNlpOdCtEbuRclQ-S_ts/edit#)
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/web-workers/index.md b/chromium/docs/website/site/blink/web-workers/index.md deleted file mode 100644 index cbed93a0058..00000000000 --- a/chromium/docs/website/site/blink/web-workers/index.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: web-workers -title: Web Workers ---- - -Web Workers spec: -<http://www.whatwg.org/specs/web-apps/current-work/multipage/workers.html> - -As of Nov 2015, the most up-to-date documentation is: -<https://docs.google.com/document/d/1i3IA3TG00rpQ7MKlpNFYUF6EfLcV01_Cv3IYG_DjF7M/edit> - -Contents below are obsolete! - -As of Nov 2014, the most up-to-date documentation was: -<https://docs.google.com/a/chromium.org/document/d/1NYMYf-_P_K2iPKlSGyv5ou_x0yL_4IRwt-DPOYqRb0s/edit#> - -As of Oct 2013, Blink/Chromium's multi-process architecture Web Workers -(Dedicated and Shared Worker) was implemented as follows: - -* **Dedicated Worker** - * Runs in the same **renderer process** as its parent document, - but on a different thread (see - [Source/core/workers/WorkerThread.\*](https://code.google.com/p/chromium/codesearch#search/&q=file:WorkerThread.h&sq=package:chromium&type=cs) - in blink for details). Note that it’s NOT the chromium’s worker - process thread implemented in content/worker/worker_thread.\*. - * In Chromium the renderer process’s main thread is implemented by - content/renderer/render_thread_impl.\*, while the Blink’s worker - thread does NOT have corresponding message_loop/thread in - chromium (yet). You can use - [webkit_glue::WorkerTaskRunner](https://code.google.com/p/chromium/codesearch#chromium/src/webkit/child/worker_task_runner.h&l=19) - (webkit/child/worker_task_runner.\*) to post tasks to the - Blink’s worker threads in chromium. - * The embedder’s platform code in Chromium for Dedicated Worker is - [/content/renderer/\*](http://src.chromium.org/viewvc/chrome/trunk/src/content/renderer/) - (in addition to content/child/\*), but NOT content/worker/\*. - * Platform APIs are accessible in Worker contexts via - WebKit::Platform::current(), and it’s implemented in - [RendererWebKitPlatformSupport](https://code.google.com/p/chromium/codesearch#chromium/src/content/renderer/renderer_webkitplatformsupport_impl.h&l=47&q=RendererWebKitPlatformSupport&type=cs&sq=package:chromium) - (content/renderer/renderer_webkitplatformsupport_impl.cc) in - Chromium (as in the case for regular document contexts). - * Note that to call Platform APIs from Worker contexts it needs to - be implemented in a thread-safe way in the embedder code (e.g. - do not lazily create a shared object without lock), or the - worker code should explicitly relay the call onto the renderer’s - main thread in Blink (e.g. by - [WTF::callOnMainThread](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/wtf/MainThread.h&l=48&q=callOnMainThread&type=cs&sq=package:chromium)). -* **Shared Worker (the following was valid until April 2014)** - * Runs in its own separate process called **worker process** and - is connected to multiple renderer processes via the browser - process. Shared Worker also runs in its own worker thread. - * In Chromium the worker process’s main thread is implemented by - content/worker/worker_thread.\* (note that this is NOT the - worker thread you refer in Blink!!). As well as in Dedicated - Workers the Blink’s worker thread does not have corresponding - message_loop/thread in chromium. - * The embedder’s platform code in Chromium for Shared Worker is - [/content/worker/\*](http://src.chromium.org/viewvc/chrome/trunk/src/content/worker/) - (in addition to content/child/\*). - * Platform APIs are accessible in Worker contexts via - WebKit::Platform::current(), and it’s implemented in - [WorkerWebKitPlatformSupportImpl](https://code.google.com/p/chromium/codesearch#chromium/src/content/worker/worker_webkitplatformsupport_impl.h&q=WorkerWebKitPlatformSupport&sq=package:chromium&type=cs&l=30) - (content/worker/worker_webkitplatformsupport_impl.cc) in - Chromium. As well as for Dedicated Worker, to use a platform API - in Worker contexts the API needs to be implemented in a - thread-safe way in the embedder code, or Blink-side code should - explicitly relay the platform API access onto the main thread by - [WTF::callOnMainThread](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/wtf/MainThread.h&l=48&q=callOnMainThread&type=cs&sq=package:chromium).
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/webcrypto/index.md b/chromium/docs/website/site/blink/webcrypto/index.md deleted file mode 100644 index 35f926cb535..00000000000 --- a/chromium/docs/website/site/blink/webcrypto/index.md +++ /dev/null @@ -1,445 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: webcrypto -title: WebCrypto ---- - -[TOC] - -## Accessing it - -* The WebCrypto API was enabled by default starting in **Chrome 37** - (August 26, 2014) -* Access to the WebCrypto API is restricted to [secure - origins](http://www.chromium.org/Home/chromium-security/security-faq#TOC-Which-origins-are-secure-) - (which is to say https:// pages). - * Note: [In the spec](https://github.com/w3c/webcrypto/issues/28), - crypto.subtle is supposed to be undefined in insecure contexts, - whereas in Chrome it is defined however any operation on it - fails with NotSupportedError. (This will be updated in the - future). - -## Standards compliance - -Chromium's implementation follows the [Web Cryptography API Editor's -Draft](https://w3c.github.io/webcrypto/Overview.html). - -Be sure to refer to the copy of the spec on github **NOT the one hosted on -w3c.org**. - -The version on w3c.org is horribly out of date (as of October 3 2016). - -## Reporting bugs - -* Issues with the implementation should be filed on [Chromium's bug - tracker](https://code.google.com/p/chromium/issues/list), and given - the component - [Blink>WebCrypto](https://bugs.chromium.org/p/chromium/issues/list?q=component:Blink%3EWebCrypto). -* Issues with the [Web Cryptography - specification](https://w3c.github.io/webcrypto/Overview.html) should - be filed on the [github](https://github.com/w3c/webcrypto/issues). - -## Supported algorithms (as of Chrome 53) - -The WebCrypto specification does not mandate any particular algorithms. - -At this time Chromium implements all of the algorithms described by the main -specification: - -> <table> -> <tr> -> <td><b> Algorithm</b></td> -> <td><b> Supported</b></td> -> <td><b> Notes</b></td> -> </tr> -> <tr> -> <td> RSASSA-PKCS1-v1_5</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> RSA-PSS </td> -> <td> YES</td> -> </tr> -> <tr> -> <td> RSA-OAEP</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> ECDSA</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> ECDH</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> AES-CTR</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> AES-CBC</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> AES-GCM</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> AES-KW</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> HMAC</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> SHA-1</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> SHA-256</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> SHA-384</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> SHA-512</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> HKDF</td> -> <td> YES</td> -> </tr> -> <tr> -> <td> PBKDF2</td> -> <td> YES</td> -> </tr> -> </table> - -**Abandoned algorithms** - -Earlier drafts of the specification contained additional algorithms, which have -since been pulled from both the spec and from Chromium's implementation: - -> <table> -> <tr> -> <td><b> Algorithm</b></td> -> <td><b> Supported</b></td> -> <td><b> Notes</b></td> -> </tr> -> <tr> -> <td> AES-CMAC</td> -> <td> NO</td> - -> * <td>No longer part of the spec</td> -> * <td>Was never implemented by Chrome</td> - -> </tr> -> <tr> -> <td> AES-CFB</td> -> <td> NO</td> - -> * <td>No longer part of the spec</td> -> * <td>Was never implemented by Chrome</td> - -> </tr> -> <tr> -> <td> Diffie-Hellman</td> -> <td> NO</td> - -> * <td>No longer part of the spec</td> -> * <td>Was never implemented by Chrome</td> - -> </tr> -> <tr> -> <td> Concat KDF</td> -> <td> NO</td> - -> * <td>No longer part of the spec</td> -> * <td>Was never implemented by Chrome</td> - -> </tr> -> <tr> -> <td> HKDF-CTR</td> -> <td> NO</td> - -> * <td>No longer part of the spec</td> -> * <td>Was never implemented by Chrome</td> -> * <td>The spec has redefined this as <a - href="https://github.com/w3c/webcrypto/issues/27">redefined this - as HKDF</a></td> - -> </tr> -> <tr> -> <td> RSAES-PKCS1-v1_5</td> -> <td> NO</td> - -> * <td>No longer part of the spec.</td> -> * <td>Chrome supported this in early days before Web Crypto was - enabled by default, but has since dropped support.</td> - -> </tr> -> </table> - -> ### RSA support - - * The modulus length must be a multiple of 8 bits - * The modulus length must be >= 256 and <= 16384 bits - * When *generating* RSA keys the public exponent must be 3 or - 65537. This limitation does not apply when importing keys. - -> ### AES support - - * The supported key sizes are: - * 128 bits - * 256 bits - * 192 bit AES keys are not supported - -> ### EC support - - * The supported - [namedCurves](https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#dfn-NamedCurve) - are: - * P-256 - * P-384 - * P-521 - -## Supported key formats - -Chromium's WebCrypto implementation supports all of the key formats - "raw", -"spki", "pkcs8", "jwk", with the following caveats: - -* There are differences in DER key format handling between Web Crypto - implementations. Where possible for compatibility prefer using "raw" - keys or "jwk" which have better interoperability. -* When importing/exporting "spki" and "pkcs8" formats, the only OIDs - supported by Chromiumare those recognized by OpenSSL/BoringSSL. - - * Importing ECDH keys [does not accept - id-ecDH](https://bugs.chromium.org/p/chromium/issues/detail?id=532728). - The OID must instead be id-ecPublicKey (This can cause problems - importing keys generated by Firefox; use "raw" EC keys as a - workaround; Chromium in this case is not spec compliant) - * Importing RSA-PSS keys does not accept id-RSASSA-PSS. The OID - must instead be rsaEncryption - * Importing RSA-OAEP keys does not accept id-RSAES-OAEP. The OID - must instead be rsaEncryption. - * Exporting ECDH keys uses OID id-ecPublicKey, whereas the - WebCrypto spec says to use id-ecDH. - * Exporting RSA-PSS keys uses OID rsaEncryption, whereas the - WebCrypto spec says to use RSA-PSS. - * Exporting RSA-OAEP keys uses OID rsaEncryption, whereas the - WebCrypto spec says to use id-RSAES-OAEP. - -## Examples of how to use WebCrypto - -Some examples of using WebCrypto can be found in the [Blink -LayoutTests](https://chromium.googlesource.com/chromium/blink/+/HEAD/LayoutTests/crypto/). - -(These can't be run directly in the browser because they access functionality -from the test harness, however it gives an idea of how to call the various -operations) - -## Usage data for WebCrypto - -Google Chrome measures how commonly WebCrypto algorithms and methods are across -web pages. -To explore the data use the [Chromium feature stack rank -dashboard](https://www.chromestatus.com/metrics/feature/popularity). This counts -the number of pageloads that made use of the given feature (internal users can -navigate an equivalent histogram using "WebCore.FeatureObserver"). -For details on how the metrics are measured read the comment block in -[CryptoHistograms.h](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/modules/crypto/CryptoHistograms.h). -Here is the correspondence between the feature names found on the [Chromium -feature stack rank -dashboard](https://www.chromestatus.com/metrics/feature/popularity) and -WebCrypto's operations/algorithms: - -<table> -<tr> -<td> <b>Feature</b></td> -<td> <b>WebCrypto method</b></td> -</tr> -<tr> -<td> `CryptoGetRandomValues` </td> -<td> crypto.getRandomValues()</td> -</tr> -<tr> -<td> `SubtleCryptoEncrypt`</td> -<td> crypto.subtle.encrypt()</td> -</tr> -<tr> -<td> `SubtleCryptoDecrypt`</td> -<td> crypto.subtle.decrypt() </td> -</tr> -<tr> -<td> `SubtleCryptoSign`</td> -<td> crypto.subtle.sign() </td> -</tr> -<tr> -<td> `SubtleCryptoVerify`</td> -<td> crypto.subtle.verify() </td> -</tr> -<tr> -<td> `SubtleCryptoDigest`</td> -<td> crypto.subtle.digest()</td> -</tr> -<tr> -<td> `SubtleCryptoGenerateKey`</td> -<td> crypto.subtle.generateKey() </td> -</tr> -<tr> -<td> `SubtleCryptoImportKey`</td> -<td> crypto.subtle.importKey() </td> -</tr> -<tr> -<td> `SubtleCryptoExportKey`</td> -<td> crypto.subtle.exportKey() </td> -</tr> -<tr> -<td> `SubtleCryptoDeriveBits`</td> -<td> crypto.subtle.deriveBits()</td> -</tr> -<tr> -<td> `SubtleCryptoDeriveKey`</td> -<td> crypto.subtle.deriveKey() </td> -</tr> -<tr> -<td> `SubtleCryptoWrapKey`</td> -<td> crypto.subtle.wrapKey() </td> -</tr> -<tr> -<td> `SubtleCryptoUnwrapKey`</td> -<td> crypto.subtle.unwrapKey() </td> -</tr> -</table> - -<table> -<tr> -<td> <b>Feature</b></td> -<td><b>WebCrypto algorithm</b></td> -</tr> -<tr> -<td> CryptoAlgorithmAesCbc `</td> -<td> AES-CBC</td> -</tr> -<tr> -<td> `CryptoAlgorithmHmac`</td> -<td> HMAC</td> -</tr> -<tr> -<td> `CryptoAlgorithmRsaSsaPkcs1v1_5`</td> -<td> RSASSA-PKCS1-v1_5</td> -</tr> -<tr> -<td> `CryptoAlgorithmSha1`</td> -<td> SHA-1</td> -</tr> -<tr> -<td> `CryptoAlgorithmSha256`</td> -<td> SHA-256</td> -</tr> -<tr> -<td> `CryptoAlgorithmSha384`</td> -<td> SHA-384 </td> -</tr> -<tr> -<td> `CryptoAlgorithmSha512`</td> -<td> SHA-512</td> -</tr> -<tr> -<td> `CryptoAlgorithmAesGcm`</td> -<td> AES-GCM</td> -</tr> -<tr> -<td> `CryptoAlgorithmRsaOaep`</td> -<td> RSA-OAEP</td> -</tr> -<tr> -<td> `CryptoAlgorithmAesCtr`</td> -<td> AES-CTR</td> -</tr> -<tr> -<td> `CryptoAlgorithmAesKw`</td> -<td> AES-KW</td> -</tr> -<tr> -<td> `CryptoAlgorithmRsaPss`</td> -<td> RSA-PSS</td> -</tr> -<tr> -<td> `CryptoAlgorithmEcdsa`</td> -<td> ECDSA</td> -</tr> -<tr> -<td> `CryptoAlgorithmEcdh`</td> -<td> ECDH</td> -</tr> -<tr> -<td> `CryptoAlgorithmHkdf`</td> -<td> HKDF</td> -</tr> -<tr> -<td> `CryptoAlgorithmPbkdf2`</td> -<td> PBKDF2</td> -</tr> -</table> - -## Chromium developer's guide - -This section is intended for Chromium developers writing patches to address -WebCrypto bugs/features. - -### Code location reference - -* [src/components/webcrypto](https://chromium.googlesource.com/chromium/src/+/HEAD/components/webcrypto) - Contains the actual crypto algorithm implementations (HMAC, ECDH, RSA-PSS, - etc.). -* [src/components/test/data/webcrypto](https://chromium.googlesource.com/chromium/src/+/HEAD/components/test/data/webcrypto) - Test data used by - [src/components/webcrypto](https://chromium.googlesource.com/chromium/src/+/HEAD/components/webcrypto). - Note that more extensive tests live in LayoutTests, and these will - eventually be transitioned there too. -* [src/third_party/WebKit/LayoutTests/crypto](https://chromium.googlesource.com/chromium/blink/+/HEAD/LayoutTests/crypto) - The end-to-end Javascript tests that exercise WebCrypto's crypto.subtle.\* - methods. - -* [src/third_party/WebKit/public/platform/WebCrypto.h](https://chromium.googlesource.com/chromium/blink/+/HEAD/public/platform/WebCrypto.h) - Public interface that defines the Blink <--> Chromium layer -* [src/third_party/WebKit/Source/modules/crypto](https://chromium.googlesource.com/chromium/blink/+/HEAD/Source/modules/crypto) - The Blink layer (responsible for interacting with the Javascript), and then - calling into Chromium side using the WebCrypto interface. -* [src/third_party/WebKit/Source/bindings/modules/v8/ScriptValueSerializerForModules.cpp](https://chromium.googlesource.com/chromium/blink/+/HEAD/Source/bindings/modules/v8/ScriptValueSerializerForModules.cpp) - Implements the structured clone for CryptoKey - -### Running the Chromium unit-tests - -> `cd src` - -> `ninja -C out/Debug components_unittests` - -> `./out/Debug/components_unittests --gtest_filter="WebCrypto*"` - -### Running the Blink LayoutTests - -> ### `cd src/third_party/WebKit` - -> ### `ninja -C out/Debug blink_tests` - -> ### `./Tools/Scripts/run-webkit-tests --debug crypto` - -### Getting "XOpenDisplay failed" when running unittests - -Unfortunately `components_unittests` requires a display to run, even though -WebCrypto itself has no such dependency. If you are running from a terminal and -get this error the easiest fix is to use Xvfb to create a mock display server -(on port 4 in my example) - -> `#Run this in the background....` -> Xvfb :4 -screen 0 1024x768x24 -> # And once it is up, re-run the unit-tests with its display port -> DISPLAY:4 ./out/Debug/components_unittests --gtest_filter="WebCrypto\*"
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/webidl/blink-idl-extended-attributes/index.md b/chromium/docs/website/site/blink/webidl/blink-idl-extended-attributes/index.md deleted file mode 100644 index 34ccaac76b3..00000000000 --- a/chromium/docs/website/site/blink/webidl/blink-idl-extended-attributes/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -- - /blink/webidl - - Web IDL in Blink -page_name: blink-idl-extended-attributes -title: Blink IDL Extended Attributes ---- - -Documentation moved into the source tree: - -<https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/webidl/index.md b/chromium/docs/website/site/blink/webidl/index.md deleted file mode 100644 index 3165d6f2d15..00000000000 --- a/chromium/docs/website/site/blink/webidl/index.md +++ /dev/null @@ -1,682 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: webidl -title: Web IDL in Blink ---- - -*Blink developers (non-bindings development): for general IDL use, see [Web IDL -interfaces](/developers/web-idl-interfaces); for configuring bindings, see -[Blink IDL Extended Attributes](/blink/webidl/blink-idl-extended-attributes); -for IDL dictionaries use, see [IDL dictionaries in -Blink](https://docs.google.com/document/d/1mRB5zbfHd0lX2Y_Hr7g6grzP_L4Xc6_gBRjL-AE7sY8/edit?usp=sharing).* - -[TOC] - -## Overview - -[Web IDL](https://heycam.github.io/webidl/) is a language that defines how -Blink interfaces are bound to V8. You need to write IDL files (e.g. -xml_http_request.idl, element.idl, etc) to expose Blink interfaces to those -external languages. When Blink is built, the IDL files are parsed, and the code -to bind Blink implementations to V8 interfaces automatically generated. - -This document describes practical information about how the IDL bindings work -and how you can write IDL files in Blink. The syntax of IDL files is fairly well -documented in the [Web IDL spec](https://heycam.github.io/webidl/), but it is -too formal to read :-) and there are several differences between the Web IDL -spec and the Blink IDL due to implementation issues. For design docs on bindings -generation, see [IDL build](/developers/design-documents/idl-build) and [IDL -compiler](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLCompiler.md). - -For Blink developers, the main details of IDLs are the extended attributes, -which control implementation-specific behavior: see [Blink IDL Extended -Attributes](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md) -for extensive details. - -Our goal is to converge Blink's IDL and Web IDL. The grammar is almost -identical; see below. - -## Basics of IDL - -Here is an example of IDL files: - -```none -[CustomToV8] -interface Node { - const unsigned short ELEMENT_NODE = 1; - attribute Node parentNode; - [TreatReturnedNullStringAs=Null] attribute DOMString nodeName; - [Custom] Node appendChild(Node newChild); - void addEventListener(DOMString type, EventListener listener, optional boolean useCapture); -}; -``` - -Let us introduce some terms: - -* The above IDL file describes the `Node` **interface**. -* `ELEMENT_NODE` is a **constant** of the `Node` interface. -* `parentNode` and `nodeName` are **attributes** of the `Node` - interface. -* `appendChild(...)` and `addEventListener(...)` are **operations** of - the `Node` interface. -* `type`, `listener` and `useCapture` are **arguments** of the - `addEventListener` operation. -* `[CustomToV8]`, `[TreatReturnedNullStringAs=Null]` and `[Custom]` - are **extended attributes**. - -The key points are as follows: - -* An IDL file controls how the bindings code between JavaScript engine - and the Blink implementation is generated. -* Extended attributes enable you to control the bindings code more in - detail. -* There are ~60 extended attributes, explained in [a separate - page](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md). -* Extended attributes can be specified on interfaces, methods, - attributes, arguments, and types (but not constants, enums, etc.). - -The valid extended attributes depend on where they attach: interfaces and -methods have different extended attributes. - -A simple IDL file template looks like: - -```none -interface INTERFACE_NAME { - const unsigned long value = 12345; - attribute Node node; - void func(long argument, ...); -}; -``` - -With extended attributes, this looks like: - -```none -[ - EXTATTR, - EXTATTR, - ..., -] interface INTERFACE_NAME { - const unsigned long value = 12345; - [EXTATTR, EXTATTR, ...] attribute Node node; - [EXTATTR, EXTATTR, ...] void func([EXTATTR, EXTATTR, ...] optional [EXTATTR] long argument, ...); -}; -``` - -## Syntax - -Blink IDL is a dialect of Web IDL. The lexical syntax is identical, but the -phrase syntax is slightly different. - -Implementation-wise, the lexer and parser are written in -[PLY](http://www.dabeaz.com/ply/) (Python lex-yacc), an implementation of lex -and yacc for Python. A standard-compliant lexer is used (Chromium -[tools/idl_parser/idl_lexer.py](https://code.google.com/p/chromium/codesearch#chromium/src/tools/idl_parser/idl_lexer.py)). -The parser (Blink -[bindings/scripts/blink_idl_parser.py](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/scripts/blink_idl_parser.py)) -derives from a standard-compliant parser (Chromium -[tools/idl_parser/idl_parser.py](https://code.google.com/p/chromium/codesearch#chromium/src/tools/idl_parser/idl_parser.py)). - -Blink deviations from the Web IDL standard can be seen as the BNF production -rules in the derived parser. - -**Style** - -Style guidelines are to generally follow [Blink style](/blink/coding-style) for -C++, with a few points highlighted, addenda, and exceptions. These are not -enforced by a pre-submit test, but do assist legibility: - -* Include the [current Blink license - header](http://www.chromium.org/blink/coding-style#TOC-License) in - new files -* For IDL based on standards/specifications: - * Include a comment with the URL of the spec (and specific - section, if possible) where the IDL is defined. - * Follow any IDL samples given in specs. - * Keep the order of interface and dictionary members the same as - in the spec. - * Document any deviations from the spec with `// TODO(name or bug - link):` comments -* 4-space indent. -* Avoid line breaks, notably: - * Keeping extended attributes of members (attributes, constants, - and operations) on the same line as the member. - * Generally keep argument lists of methods on the same line as the - definition. Ok to break if it's v. long or for overloaded - methods. - * For overloaded methods, it is ok to use line breaks to group - arguments. E.g., if one method has arguments (a, b, c) and the - other has arguments (a, b, c, d, e, f), it is ok to include a - line break between c and d, to clarify the grouping. -* Alphabetize lists of extended attributes. -* For extended attributes on interface, put each on a separate line - with a trailing comma, except for the last one. Note that this is - *not* style used in the standard, which uses a horizontal list on - the line before the interface. Please omit the `[]` list if it's - empty. Examples of Blink style: - -```none -[ - A, - B /* No trailing commas on the last extended attribute */ -] interface Foo { - ... -}; -interface Bar { - ... -}; -``` - -* No spacing for horizontal alignment, except for lists of constants. -* For anonymous special operations, leave a space between the type and - the parenthesize argument list; if you don't, the type looks like a - function name! - -```none -getter DOMString (unsigned long index); // Not: DOMString(unsigned long index) -``` - -* For special operations, the (first) argument to indexed property - operations should be called `index`, and the (first) argument to - named property operations should be called `name`; the second - argument in property setters should be called `value`. For example: - -```none -// Indexed property operations -getter DOMString (unsigned long index); -setter DOMString (unsigned long index, DOMString value); -deleter boolean (unsigned long index); - -// Named property operations -getter DOMString (DOMString name); -setter DOMString (DOMString name, DOMString value); -deleter boolean (DOMString name); -``` - -## Semantics - -Web IDL exposes an interface to JavaScript, which is implemented in C++. Thus -its semantics bridge these two languages, though it is not identical to either. -Web IDL's semantics are much closer to C++ than to JavaScript – in practice, it -is a relatively thin abstraction layer over C++. Thus C++ implementations are -quite close to the IDL spec, though the resulting interface is somewhat -unnatural from a JavaScript perspective: it behaves differently from normal -JavaScript libraries. - -### Types - -*See: [Web IDL types](http://heycam.github.io/webidl/#idl-types).* - -[Primitive types](http://heycam.github.io/webidl/#dfn-primitive-type) in Web IDL -are very close to fundamental types in C++ (booleans, characters, integers, and -floats), though note that there is no `int` type in Web IDL (specs usually use -`long` instead). - -### undefined and null - -JavaScript has two special values, `undefined` and `null`, which are often -confusing and do not fit easily into C++. Indeed, precise behavior of -`undefined` in Web IDL has varied over time and is under discussion (see W3C Bug -[23532](https://www.w3.org/Bugs/Public/show_bug.cgi?id=23532) - Dealing with -undefined). - -Behavior on `undefined` and `null` **MUST** be tested in web tests, as these can -be passed and are easy to get wrong. If these tests are omitted, there may be -crashes (which will be caught by ClusterFuzz) or behavioral bugs (which will -show up as web pages or JavaScript libraries breaking). - -For the purposes of Blink, behavior can be summarized as follows: - -* `undefined` and `null` are valid values for **basic types**, and are - automatically converted. - * Conversion follows [ECMAScript type - mapping](http://heycam.github.io/webidl/#dfn-convert-ecmascript-to-idl-value), - which generally implements JavaScript [Type - Conversion](https://tc39.github.io/ecma262/#sec-type-conversion), - e.g. [ToBoolean](https://tc39.github.io/ecma262/#sec-toboolean), - [ToNumber](https://tc39.github.io/ecma262/#sec-tonumber), - [ToString](https://tc39.github.io/ecma262/#sec-tostring). - * They may be converted to different values, notably `"undefined"` - and `"null"` for `DOMString`. - * For numeric types, this can be affected by the extended - attributes `[Clamp]` and `[EnforceRange]`. - * `[Clamp]` changes the value so that it is valid. - * `[EnforceRange]` throws a `TypeError` on these invalid - values. -* for **interface types**, `undefined` and `null` are both treated as - `null`, which maps to `nullptr`. - * for nullable interface types, like `Node?`, `null` is a valid - value, and thus `nullptr` is passed to the C++ implementation - * for non-nullable interface types, like `Node` (no `?`), `null` - is *not* a valid value, and a `TypeError` is thrown, as in - JavaScript - [ToObject](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-toobject). - * *However,* this nullability check is *not* done by default: - it is only done if `[LegacyInterfaceTypeChecking]` is - specified on the interface or member (see Bug - [249598](https://code.google.com/p/chromium/issues/detail?id=249598): - Throw TypeError when null is specified to non-nullable - interface parameter) - * Thus if `[LegacyInterfaceTypeChecking]` is specified in the - IDL, you do *not* need to have a null check in the Blink - implementation, as the bindings code already does this, but - if `[LegacyInterfaceTypeChecking]` is not specified, you - *do* need to have a null check in the Blink implementation. -* for **dictionary types**, `undefined` and `null` both correspond to - an empty dictionary -* for **union types**, `undefined` and `null` are assigned to a type - that can accept them, if possible: null, empty dictionary, or - conversion to basic type -* **function resolution** - * `undefined` affects function resolution, both as an optional - argument and for overloaded operations, basically being omitted - if trailing (but some exceptions apply). This is complicated - (see W3C Bug - [23532](https://www.w3.org/Bugs/Public/show_bug.cgi?id=23532) - - Dealing with undefined) and not currently implemented. - Further, note that in some cases one wants different behavior for `f()` - and `f(undefined)`, which requires an explicit overload, not an optional - argument; a good example is `Window.alert()`, namely `alert()` vs. - `alert(undefined)` (see W3C Bug - [25686](https://www.w3.org/Bugs/Public/show_bug.cgi?id=25686)). - * `null` affects function resolution for overloaded operations, - due to preferring nullable types, but this is the only effect. - -### Function resolution - -Web IDL has *required* arguments and *optional* arguments. JavaScript does not: -omitted arguments have `undefined` value. In Web IDL, omitting optional -arguments is *not* the same as explicitly passing `undefined`: they call have -different behavior (defined in the spec prose), and internally call different -C++ functions implementing the operation. - -Thus if you have the following Web IDL function declaration: - -```none -interface A { - void foo(long x); - }; -``` - -...the JavaScript `a = new A(); a.foo()` will throw a `TypeError`. This is -specified in Web IDL, and thus done by the binding code. - -However, in JavaScript the corresponding function can be called without -arguments: - -```none -function foo(x) { return x } - foo() // undefined -``` - -Note that `foo()` and `foo(undefined)` are almost identical calls (and for this -function have identical behavior): it only changes the value of -`arguments.length`. - -To get *similar* behavior in Web IDL, the argument can be explicitly specified -as `optional` (or more precisely, `optional` with `undefined` as a default -value). However, these do *not* need to have the same behavior, and do *not* -generate the same code: the spec may define different behavior for these calls, -and the bindings call the implementing C++ functions with a different number of -arguments, which is resolved by C++ overloading, and these may be implemented by -different functions. - -For example, given an optional argument such as: - -```none -interface A { - void foo(optional long x); - }; -``` - -This results in a = new A(); a.foo() being legal, and calling the underlying -Blink C++ function implementing `foo` with no arguments, while -`a.foo(undefined)` calls the underlying Blink function with one argument. - -For *overloaded* operations, the situation is more complicated, and not -currently implemented in Blink (Bug -[293561](https://code.google.com/p/chromium/issues/detail?id=293561)). See the -[overload resolution -algorithm](http://heycam.github.io/webidl/#dfn-overload-resolution-algorithm) in -the spec for details. - -Pragmatically, passing `undefined` for an optional argument is necessary if you -wish to specify a value for a later argument, but not earlier ones, but does not -necessarily mean that you mean to pass in `undefined` explicitly; these instead -get the special value "missing". - -Passing `undefined` to the last optional argument has unclear behavior for the -value of the argument, but does mean that it resolves it to the operation with -the optional argument, rather than others. (It then prioritizes nullable types -and dictionary types, or unions thereof.) For example: - -```none -interface A { - void foo(optional long x); - void foo(Node x); - }; -``` - -This results in a = new A(); a.foo(undefined) resolving to the first `foo`, it -is not clear if the resulting call is `a.foo()`, to `a.foo` with "missing", or -(most likely) `a.foo(undefined)` (here using the first overloaded function): it -affect overload resolution, but perhaps not argument values. Note that -`undefined` is also a legitimate value for the argument of `Node` type, so it -would not be illegal, but the overload resolution algorithm first picks optional -arguments in this case. - -Note that Blink code implementing a function can also check arguments, and -similarly, JavaScript functions can check arguments, and access the number of -arguments via `arguments.length`, but these are not specified by the *language* -or checked by bindings. - -***Warning:*** `undefined` is a *valid value* for required arguments, and many -interfaces *depend* on this behavior particularly booleans, numbers, and -dictionaries. Explicitly passing `undefined`, as in `a.foo(undefined)`, does -*not* cause a type error (assuming `foo` is unary). It is clearer if the -parameter is marked as `optional` (this changes semantics: the argument can now -also be omitted, not just passed explicitly as `undefined`), but this is not -always done in the spec or in Blink's IDL files. - -## File organization - -The Web IDL spec treats the Web API as a single API, spread across various IDL -fragments. In practice these fragments are `.idl` files, stored in the codebase -alongside their implementation, with basename equal to the interface name. Thus -for example the fragment defining the `Node` interface is written in n`ode.idl`, -which is stored in the `third_party/blink/renderer/core/dom` directory, and is -accompanied by `node.h` and `node.cc` in the same directory. In some cases the -implementation has a different name, in which case there must be an -`[ImplementedAs=...]` extended attribute in the IDL file, and the `.h/.cc` files -have basename equal to the value of the `[ImplementedAs=...]`. - -For simplicity, each IDL file contains a *single* interface or dictionary, and -contains all information needed for that definition, except for dependencies -(below), notably any enumerations, implements statements, typedefs, and callback -functions. - -### Dependencies - -In principle (as a matter of the Web IDL spec) any IDL file can depend on any -other IDL file, and thus changing one file can require rebuilding all the -dependents. In practice there are 4 kinds of dependencies (since other required -definitions, like enumerations and typedefs, are contained in the IDL file for -the interface): - -* `partial interface` – a single interface can be spread across a - single main `interface` statement (in one file) and multiple other - `partial interface` statements, each in a separate file (each - `partial interface` statement is associated with a single main - `interface` statement). In this case the IDL file containing the - partial interface has some other name, often the actual interface - name plus some suffix, and is generally named after the implementing - class for the members it contains. From the point of view of spec - authors and compilation, the members are just treated as if they - appeared in the main definition. From the point of view of the - build, these are awkward to implement, since these are incoming - dependencies, and cannot be determined from looking at the main - interface IDL file itself, thus requiring a global dependency - resolution step. -* `implements` – this is essentially multiple inheritance: an - interface can implement multiple other interfaces, and a given - interface can be implemented by multiple other interfaces. This is - specified by implements statements in the implementing file (these - are outgoing dependencies), though from the perspective of the build - the interface → .idl filename of that interface data is required, - and is global information (because the .idl files are spread across - the source tree). -* **Ancestors** – an interface may have a parent, which in turn may - have a parent. The immediate parent can be determined from looking - at a single IDL file, but the more distant ancestors require - dependency resolution (computing an ancestor chain). -* **Used interfaces (cross dependencies)** – a given interface may - *use* other interfaces as *types* in its definitions; the contents - of the used interfaces *may* affect the bindings generated for the - using interface, though this is often a *shallow dependency* (see - below). - -In practice, what happens is that, when compiling a given interfaces, its -partial interfaces and the other interfaces it implements are merged into a -single data structure, and that is compiled. There is a small amount of data -recording where exactly a member came from (so the correct C++ class can be -called), and a few other extended attributes for switching the -partial/implemented interface on or off, but otherwise it is as if all members -were specified in a single `interface` statement. This is a **deep dependency** -relationship: *any* change in the partial/implemented interface changes the -bindings for the overall (merged) interface, since *all* the data is in fact -used. - -Bindings for interfaces in general do *not* depend on their ancestors, beyond -the name of their immediate parent. This is because the bindings just generate a -class, which refers to the parent class, but otherwise is subject to information -hiding. However, in a few cases bindings depend on whether the interface -inherits from some other interface (notably EventHandler or Node), and in a few -cases bindings depend on the extended attributes of ancestors (these extended -attributes are "inherited"; the list is -[compute_dependencies.INHERITED_EXTENDED_ATTRIBUTES](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/scripts/compute_interfaces_info_overall.py?q=INHERITED_EXTENDED_ATTRIBUTES&l=59), -and consists of extended attributes that affect memory management). There is -thus a **shallow dependency** on ancestors, specifically only on the ancestor -chain and on inherited extended attributes, not on the other contents of -ancestors. - -On the other hand, the dependencies on used interfaces – so-called **cross -dependencies** – are generally **shallow dependency** relationships: the using -interface does not need to know much about the used interface (currently just -the name of the implementing class, and whether the interface is a callback -interface or not). Thus *almost all changes* in the used interface do not change -the bindings for the using interface: the public information used by other -bindings is minimal. There is one exception, namely the `[PutForwards]` extended -attribute (in standard Web IDL), where the using interface needs to know the -type of an attribute in the used interface. This "generally shallow" -relationship may change in future, however, as being able to inspect the used -interface can simplify the code generator. This would require the using -interface to depend on used interfaces, either rebuilding all using interfaces -whenever a used interface is changed, or clearly specifying or computing the -public information (used by code generator of other interfaces) and depending -only on that. - -## IDL extended attribute validator - -To avoid bugs caused by typos in extended attributes in IDL files, the extended -attribute validator was introduced to the Blink build flow to check if all the -extended attributes used in IDL files are implemented in the code generator. If -you use an extended attribute not implemented in code generators, the extended -attribute validator fails, and the Blink build fails. - -A list of IDL attributes implemented in code generators is described in -[IDLExtendedAttributes.txt](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/IDLExtendedAttributes.txt). -If you want to add a new IDL attribute, you need to - -1. add the extended attribute to - Source/bindings/IDLExtendedAttributes.txt. -2. add the explanation to the extended attributes document. -3. add test cases to run-bindings-tests (explained below). - -Note that the validator checks for known extended attributes and their arguments -(if any), but does not enforce correct use of the the attributes. A warning will -not be issued if, for example, `[Clamp]` is specified on an interface. - -## Tests - -### Reference tests (run-bindings-tests) - -[third_party/blink/tools/run_bindings_tests.py](https://cs.chromium.org/chromium/src/third_party/blink/tools/run_bindings_tests.py) -tests the code generator, including its treatment of extended attributes. -Specifically, run_bindings_tests.py compiles the IDL files in -[bindings/tests/idls](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/tests/idls/), -and then compares the results against reference files in -[bindings/tests/results](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/tests/results/). -For example, run_bindings_tests.py reads test_object.idl, and then compares the -generated results against v8_test_object.h and v8_test_object.cc, reporting any -differences. - -If you change the behavior of the code generator or add a new extended -attribute, please add suitable test cases, preferably *reusing* existing IDL -files (this is to minimize size of diffs when making changes to overall -generated bindings). You can reset the run-bindings-tests results using the ---reset-results option: - -```none -third_party/blink/tools/run_bindings_tests.py --reset-results -``` - -run_bindings_tests.py is run in a presubmit script for any changes to -Source/bindings: this requires you to update test results when you change the -behavior of the code generator, and thus if test results get out of date, the -presubmit test will fail: you won't be able to upload your patch via git-cl, and -the CQ will refuse to process the patch. - -The objective of run-bindings-tests is to show you and reviewers how the code -generation is changed by your patch. **If you change the behavior of code -generators, you need to update the results of run-bindings-tests.** - -Despite these checks, sometimes the test results can get out of date; this is -primarily due to dcommitting or changes in real IDL files (not in -Source/bindings) that are used in test cases. If the results are out of date -*prior* to your CL, please rebaseline them separately, before committing your -CL, as otherwise it will be difficult to distinguish which changes are due to -your CL and which are due to rebaselining due to older CLs. - -Note that using real interfaces in test IDL files means changes to real IDL -files can break run-bindings-tests (e.g., Blink -[r174804](https://src.chromium.org/viewvc/blink?revision=174804&view=revision)/CL -[292503006](https://codereview.chromium.org/292503006/): Oilpan: add -\[WillBeGarbageCollected\] for Node., since Node is inherited by test files). -This is ok (we're not going to run run_bindings_tests.py on every IDL edit, and -it's easy to fix), but something to be aware of. - -It is also possible for run_bindings_tests.py to break for other reasons, since -it use the developer's local tree: it thus may pass locally but fail remotely, -or conversely. For example, renaming Python files can result in outdated -bytecode (.pyc files) being used locally and succeeding, even if -run_bindings_tests.py is incompatible with current Python source (.py), as -discussed and fixed in CL -[301743008](https://codereview.chromium.org/301743008/). - -### Behavior tests - -To test behavior, use [web -tests](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/web_tests.md), -most simply actual interfaces that use the behavior you're implementing. If -adding new behavior, it's preferable to make code generator changes and the -first actual use case in the same CL, so that it is properly tested, and the -changes appear in the context of an actual change. If this makes the CL too -large, these can be split into a CG-only CL and an actual use CL, committed in -sequence, but unused features should not be added to the CG. - -For general behavior, like type conversions, there are some internal tests, like -[bindings/webidl-type-mapping.html](https://cs.chromium.org/chromium/src/third_party/WebKit/LayoutTests/bindings/webidl-type-mapping.html), -which uses -[testing/type_conversions.idl](https://cs.chromium.org/chromium/src/third_party/blink/renderer/core/testing/type_conversions.idl). -There are also some other IDL files in -[testing](https://cs.chromium.org/chromium/src/third_party/blink/renderer/core/testing/), -like -[testing/internals.idl](https://cs.chromium.org/chromium/src/third_party/blink/renderer/core/testing/internals.idl). - -## Where is the bindings code generated? - -By reading this document you can learn how extended attributes work. However, -the best practice to understand extended attributes is to try to use some and -watch what kind of bindings code is generated. - -If you change an IDL file and rebuild (e.g., with ninja or Make), the bindings -for that IDL file (and possibly others, if there are dependents) will be -rebuilt. If the bindings have changed (in ninja), or even if they haven't (in -other build systems), it will also recompile the bindings code. Regenerating -bindings for a single IDL file is very fast, but regenerating all of them takes -several minutes of CPU time. - -In case of xxx.idl in the Release build, the bindings code is generated in the -following files ("Release" becomes "Debug" in the Debug build). - -```none -out/Release/gen/third_party/blink/renderer/bindings/{core,modules}/v8_xxx.{h,cc} -``` - -## Limitations and improvements - -A few parts of the Web IDL spec are not implemented; features are implemented on -an as-needed basis. See -[component:Blink>Bindings](https://bugs.chromium.org/p/chromium/issues/list?q=component:Blink%3EBindings) -for open bugs; please feel free to file bugs or contact bindings developers -([members of -blink-reviews-bindings](https://groups.google.com/a/chromium.org/forum/#!members/blink-reviews-bindings), -or -[bindings/OWNERS](https://cs.chromium.org/chromium/src/third_party/blink/renderer/bindings/OWNERS)) -if you have any questions, problems, or requests. - -Bindings generation can be controlled in many ways, generally by adding an -extended attribute to specify the behavior, sometimes by special-casing a -specific type, interface, or member. If the existing [extended -attributes](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md) -are not sufficient (or buggy), please file a bug and contact bindings -developers! - -Some commonly encountered limitations and suitable workarounds are listed below. -Generally limitations can be worked around by using custom bindings, but these -should be avoided if possible. If you need to work around a limitation, please -put a `TODO` with the bug number (as demonstrated below) in the IDL so that we -can remove the hack when the feature is implemented. - -### Syntax error causes infinite loop - -Some syntax errors cause the IDL parser to enter an infinite loop (Bug -[363830](https://code.google.com/p/chromium/issues/detail?id=363830)). Until -this is fixed, if the compiler hangs, please terminate the compiler and check -your syntax. - -### Type checking - -The bindings do not do full type checking (Bug -[321518](https://code.google.com/p/chromium/issues/detail?id=321518)). They do -some type checking, but not all. Notably nullability is not strictly enforced. -See `[TypeChecking]` under **undefined and null** above to see how to turn on -more standard type checking behavior for interfaces and members. - -## Bindings development - -### Mailing List - -## If working on bindings, you likely wish to join the [blink-reviews-bindings](https://groups.google.com/a/chromium.org/forum/#!forum/blink-reviews-bindings) mailing list. - -### See also - -* [Web IDL interfaces](/developers/web-idl-interfaces) – overview - how-to for Blink developers -* [Blink IDL Extended - Attributes](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/bindings/IDLExtendedAttributes.md) - – reference for Blink developers and bindings developers -* [IDL build](/developers/design-documents/idl-build) – design doc -* [IDL compiler](/developers/design-documents/idl-compiler) – design - doc - ---- - -Derived from: <http://trac.webkit.org/wiki/WebKitIDL> *Licensed under -[BSD](http://www.webkit.org/coding/bsd-license.html):* - -BSD License - -Copyright (C) 2009 Apple Inc. All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this -list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, -this list of conditions and the following disclaimer in the documentation and/or -other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS “AS IS” AND ANY -EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY -DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 3.19.28 PM.png.sha1 b/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 3.19.28 PM.png.sha1 deleted file mode 100644 index 634f26202b1..00000000000 --- a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 3.19.28 PM.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -24fa8fe76a3101f520cc1abdba58a56b80d02080
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 4.18.39 PM.png.sha1 b/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 4.18.39 PM.png.sha1 deleted file mode 100644 index 41b2e237cfe..00000000000 --- a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 4.18.39 PM.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -d97b12c7e4b46b4bfe3f557d5451f17d82e03889
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 5.36.49 PM.png.sha1 b/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 5.36.49 PM.png.sha1 deleted file mode 100644 index 16953f91f5e..00000000000 --- a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 5.36.49 PM.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -30bd04ee1100c35b45e6d53edc7c387fae4d3015
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 5.38.39 PM.png.sha1 b/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 5.38.39 PM.png.sha1 deleted file mode 100644 index 7e709772188..00000000000 --- a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Screen Shot 2015-04-04 at 5.38.39 PM.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -cbee8ae3b979389bb2a1efeaaebdf9e1788b1bab
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Untitled-5.fw.png.sha1 b/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Untitled-5.fw.png.sha1 deleted file mode 100644 index 61bb6c26d0c..00000000000 --- a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Untitled-5.fw.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -648431cdf8a5c8cec01bf1a0fe008ee67b915057
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/chromestatus42.png.sha1 b/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/chromestatus42.png.sha1 deleted file mode 100644 index 2f5bf4fae49..00000000000 --- a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/chromestatus42.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -77684e337dca9390b7e9e0dff297076b47f3e979
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/chromeversion.png.sha1 b/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/chromeversion.png.sha1 deleted file mode 100644 index 94498e343b1..00000000000 --- a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/chromeversion.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -799e36afd69e22f29a7c2b3f4d7258a958a27ab1
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/cr-commit-pos.png.sha1 b/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/cr-commit-pos.png.sha1 deleted file mode 100644 index a15970d32e4..00000000000 --- a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/cr-commit-pos.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -c50be4b92d119f7c225d816e9c8434cea100b861
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/f3a.png.sha1 b/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/f3a.png.sha1 deleted file mode 100644 index 19cb4347150..00000000000 --- a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/f3a.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -1ac11509cbb9e605d756b7d0c7cd1ff4b7bf4dd7
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/index.md b/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/index.md deleted file mode 100644 index 83386c4ea3f..00000000000 --- a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/index.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -breadcrumbs: -- - /blink - - Blink (Rendering Engine) -page_name: when-will-a-fix-ship-in-chrome-stable-or-canary -title: When will a fix ship in Chrome (stable or canary)? ---- - -Here's a quick guide on how to track changes as they make their way to releases -of Chrome. - -This includes all changes to Chrome, including stuff for HTML, CSS, DOM, & -DevTools. - -## On chromestatus.com? - -First things first, [chromestatus.com](http://chromestatus.com) was built for -this. If the feature is big, it will probably be there. - -On the left you can see all features currently in beta. Those should be in -stable soon. - -You can search for other features and view what release they are *Enabled by -default.* - -[<img alt="https://www.chromestatus.com/" -src="/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/chromestatus42.png" -width=500>](https://www.chromestatus.com/) - -## Not on Chromestatus? - -Alright, buckle up. This is fun stuff. - -It all comes down to tracking the **Chromium revision number.** - -* First, we're assuming you're looking at the bug somewhere in - [code.google.com/p/chromium/issues/](https://code.google.com/p/chromium/issues/list) -* Now, when a commit lands, an automated comment is added to the - Chromium bug. -* All commits have a git hash and an incremental revision number. -* You can see the commit below has **373417**. -* Take note of this number and follow on… - -[<img alt="image" -src="/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/cr-commit-pos.png">](/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/Untitled-5.fw.png) - -### Waiting for it to hit Chrome Stable? - -Generally it takes ~10 weeks from a commit landing to hit stable. - -Take the Chromium revision number (or the git SHA) and drop it into -[storage.googleapis.com/chromium-find-releases-static/](https://storage.googleapis.com/chromium-find-releases-static/index.html) -[<img alt="image" -src="/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/f3a.png">](/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/f3a.png) -Visit ==https://omahaproxy.appspot.com== for the version numbers of the current -releases of Chrome. - -**When does version X ship in stable channel?** - -* Chrome ships a new major version to stable generally every 6 weeks, - but in some cases we may choose to skip a release. -* [Chromium Development Calendar and Release - Info](/developers/calendar) contains "Estimated Stable Dates", which - are roughly 6 weeks apart. - -### Waiting for it to land in Canary or an Dev build? - -You could use the above technique... but here's the guide for hackers or folks -who don't want to wait for Canary or Dev Channel: - -#### Get a fresh Chromium build - -* Get the latest chromium in either of these two ways: [Download - Chromium](/getting-involved/download-chromium) - * These builds are generated every hour, so you should be fine. -* [Canary](http://www.paulirish.com/2012/chrome-canary-for-developers/) - is updated every day (at ~4am PST). -* Either way, open up either and go to about:version - -[<img alt="image" -src="/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/chromeversion.png">](/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/chromeversion.png) - -* At the end of the Revision line is the Chromium Rev. -* As long as that rev number is higher than the one you're interested - in... you're good! - * (Of course this assumes no reverts of either the commit or the - DEPS roll, but you'll probably have spotted those already) - -**Enjoy the fix or feature you've been waiting for!** - -Updated Oct 2016 - -Paul Irish
\ No newline at end of file diff --git a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/omahaprox.png.sha1 b/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/omahaprox.png.sha1 deleted file mode 100644 index 603c61aaad1..00000000000 --- a/chromium/docs/website/site/blink/when-will-a-fix-ship-in-chrome-stable-or-canary/omahaprox.png.sha1 +++ /dev/null @@ -1 +0,0 @@ -21b3a4bc7bf4a977a92485ddf1ba707522d4dbb5
\ No newline at end of file |
