diff --git a/docs/Building.md b/docs/Building.md index 13aeeb11df8..23acfd82abf 100644 --- a/docs/Building.md +++ b/docs/Building.md @@ -1,10 +1,3 @@ -> [!IMPORTANT] -> This page was copied from https://github.com/dart-lang/sdk/wiki and needs review. -> Please [contribute](../CONTRIBUTING.md) changes to bring it up-to-date - -> removing this header - or send a CL to delete the file. - ---- - [Dependencies](#dependencies) [Getting the source](#source) diff --git a/docs/Chrome-63-Dart-Web-Libraries.md b/docs/Chrome-63-Dart-Web-Libraries.md deleted file mode 100644 index 0cca85b8ebc..00000000000 --- a/docs/Chrome-63-Dart-Web-Libraries.md +++ /dev/null @@ -1,185 +0,0 @@ -> [!IMPORTANT] -> This page was copied from https://github.com/dart-lang/sdk/wiki and needs review. -> Please [contribute](../CONTRIBUTING.md) changes to bring it up-to-date - -> removing this header - or send a CL to delete the file. - ---- - -The Dart Web Libraries have not been updated since Chrome 50. With this release these libraries have been rev’d to the Chrome 63 APIs (WebIDLs). Below are the known differences between the Chrome 50 and Chrome 63 Dart Web libraries. These are the changes that have affected Dart user’s code: - -* Touch and TouchEvent change - - _initTouchEvent removed see [Chrome Change](https://www.chromestatus.com/features/4923255479599104) - - Example of [Migrating initTouchEvent to Map](https://developers.google.com/web/updates/2016/09/chrome-54-deprecations#use_of_inittouchevent_is_removed) -* TouchEvent constructor takes a map argument, strong mode catches these failures in our tests. -* Web_audio - - AudioBufferSourceNode extends AudioScheduledSourceNode there are two start methods - - AudioScheduledSourceNode.start can't be overloaded and will become operation void start2([num when]); - - AudioBufferSourceNode.start([num when, num grainOffset, num grainDuration]) is void start([num when, num grainOffset, num grainDuration]) -* Attributes of type double changed num see section "**Attributes Type Change double to num**" at the end of this document. -* onWheel event exposed -* Created for union of two kinds of canvas HTMLCanvasElement and OffscreenCanvas interface WebGLCanvas -* all other RenderingContext - - readonly attribute WebGLCanvas canvas; -* interface WebGLRenderingContext - - readonly attribute HTMLCanvasElement canvas; -* KeygenElement was removed in Chrome 57 -* IDBFactory.webkitGetDatabaseNames() constructor removed in Chrome -* Depreciated FileError and DomError have been removed use DomException - - error.code replaced with error.name (e.g., see fileapi_directory_test.dart) - - Additional because FileError is gone there is no easy way to determine which errors are File only errors. However, these are: - - NOT_FOUND_ERR - - SECURITY_ERR - - ABORT_ERR - - NO_MODIFICATION_ALLOWED_ERR - - INVALID_STATE_ERR - - SYNTAX_ERR - - INVALID_MODIFICATION_ERR - - QUOTA_EXCEEDED_ERR - - TYPE_MISMATCH_ERR -* registerElement and register maps to old style (Chrome 50) -* registerElement2 2nd parameter is a map {'prototype': xxx, 'extends': xxxx} not 2 separate arguments. -* List getClientRects() is now DomRectList getClientRects() -* Rectangle getBoundingClientRect() is now DomRect getBoundingClientRect() -* postMessage(/*any*/ message, String targetOrigin, [List transfer]) changed to void postMessage(/*any*/ message, String targetOrigin, [List transfer]) transfer can now be ArrayBuffer, MessagePort and ImageBitmap -* RTCPeerConnection.setLocalDescription and setRemoteDescription - - takes a Map setLocalDescription(Map description) description is a map e.g., {'type': localSessionDescription, 'sdp': fakeLensSdp} -* nounce removed from HtmlScriptElement added to HtmlElement - - https://codereview.chromium.org/2801243002 - - https://github.com/whatwg/html/issues/2369 -* Event.deepPath() was removed Chrome 54 - - https://developer.mozilla.org/en-US/docs/Web/API/Event/deepPath -* Event.scoped replaced by Event.composed - - https://developer.mozilla.org/en-US/docs/Web/API/Event/composed - -*** -Summary of API changes from Chrome 51 thru Chrome 63: -

-[https://developers.google.com/web/updates/tags/chrome51](https://developers.google.com/web/updates/tags/chrome51) -
-[https://developers.google.com/web/updates/tags/chrome52](https://developers.google.com/web/updates/tags/chrome52) -
-[https://developers.google.com/web/updates/tags/chrome53](https://developers.google.com/web/updates/tags/chrome53) -
-[https://developers.google.com/web/updates/tags/chrome54](https://developers.google.com/web/updates/tags/chrome54) -
-[https://developers.google.com/web/updates/tags/chrome55](https://developers.google.com/web/updates/tags/chrome55) -
-[https://developers.google.com/web/updates/tags/chrome56](https://developers.google.com/web/updates/tags/chrome56) -
-[https://developers.google.com/web/updates/tags/chrome57](https://developers.google.com/web/updates/tags/chrome57) -
-[https://developers.google.com/web/updates/tags/chrome58](https://developers.google.com/web/updates/tags/chrome58) -
-[https://developers.google.com/web/updates/tags/chrome59](https://developers.google.com/web/updates/tags/chrome59) -
-[https://developers.google.com/web/updates/tags/chrome60](https://developers.google.com/web/updates/tags/chrome60) -
-[https://developers.google.com/web/updates/tags/chrome61](https://developers.google.com/web/updates/tags/chrome61) -
-[https://developers.google.com/web/updates/tags/chrome62](https://developers.google.com/web/updates/tags/chrome62) -
-[https://developers.google.com/web/updates/tags/chrome63](https://developers.google.com/web/updates/tags/chrome63) -
- -*** -### Attributes Type Change double to num -* Accelerometer - - x, y, z -* AmbientLightSensor - - illuminance -* AnimationEffectTimingReadOnly - - delay, endDelay, iterationStart, iterations -* AnimationEvent - - elapsedTime -* AnimationPlaybackEvent - - currentTime, timelineTime -* AnimationTimeline - - currentTime -* BatteryManager - - chargingTime, dischargingTime, level -* BlobEvent - - timecode -* BudgetState - - budgetAt -* Coordinates - - accuracy, altitude, altitudeAccuracy, heading, latitude, longitude, speed -* CSSImageValue - - intrinsicHeight,intrinsicRatio, intrinsicWidth -* DeviceAcceleration - - x, y, z -* DeviceOrientationEvent - - alpha, beta, gamma -* DeviceRotationRate - - alpha, beta, gamma -* Event - - timeStamp -* GamepadButton - - value -* Gyroscope - - x, y, z -* IntersectionObserverEntry - - intersectionRatio, time -* Magnetometer - - x, y, z -* HTMLMediaElement - - duration -* MediaKeySession - - expiration -* MediaSettingsRange - - max. min, step -* MouseEvent - - clientX, clientY, pageX, pageY, screenX, screenY -* Navigator - - deviceMemory -* NetworkInformation - - downlink, downlinkMax -* PaintSize - - height, width -* PaintWorkletGlobalScope - - devicePixelRatio -* Performance - - timeOrigin -* PerformanceEntry - - duration, startTime -* PerformanceNavigationTiming - - domComplete, domContentLoadedEventEnd, domContentLoadedEventStart, domInteractive, loadEventEnd, loadEventStart, redirectCount, unloadEventEnd, unloadEventStart -* PerformanceResourceTiming - - connectEnd, connectStart, domainLookupEnd, domainLookupStart, encodedBodySize, fetchStart, redirectStart, requestStart, responseEnd, responseStart, secureConnectionStart, workerStart -* PointerEvent - - height, pressure, tangentialPressure, width -* HTMLProgressElement - - position -* RTCRtpContributingSource - - timestamp -* ScrollState - - deltaGranularity, deltaX, deltaY, velocityX, velocityY -* Sensor - - timestamp -* SpeechRecognitionAlternative - - confidence -* SpeechSynthesisEvent - - elapsedTime -* TextMetrics - - actualBoundingBoxAscent, actualBoundingBoxDescent, actualBoundingBoxLeft, actualBoundingBoxRight, alphabeticBaseline, emHeightAscent, emHeightDescent, fontBoundingBoxAscent, fontBoundingBoxDescent, hangingBaseline, ideographicBaseline, width -* Touch - - clientX, clientY, force, pageX, pageY, radiusX, radiusY, rotationAngle, screenX, screenY -* TransitionEvent - - elapsedTime -* VRFrameOfReference - - emulatedHeight -* VRStageBoundsPoint - - x, z -* VRStageParameters - - sizeX, sizeZ -* VideoPlaybackQuality - - creationTime -* VisualViewport - - height, offsetLeft, offsetTop, pageLeft, pageTop, sca, width -* WheelEvent - - deltaX, deltaY, deltaZ -* Window - - devicePixelRatio, pageXOffset, pageYOffset -* WorkerPerformance - - timeOrigin -* XPathResult - - numberValue diff --git a/docs/Commit-Message-Best-Practices.md b/docs/Commit-Message-Best-Practices.md index 2f079aabb2b..6084d0d1c7b 100644 --- a/docs/Commit-Message-Best-Practices.md +++ b/docs/Commit-Message-Best-Practices.md @@ -1,10 +1,3 @@ -> [!IMPORTANT] -> This page was copied from https://github.com/dart-lang/sdk/wiki and needs review. -> Please [contribute](../CONTRIBUTING.md) changes to bring it up-to-date - -> removing this header - or send a CL to delete the file. - ---- - 1. First line is a capitalized, short (50 chars or less) summary, * Please include the component for which the change is being made in the first line * **[Analyzer]** short (50 chars or less) summary diff --git a/docs/Publishing-package-analyzer.md b/docs/Publishing-package-analyzer.md deleted file mode 100644 index 9402e3c3a39..00000000000 --- a/docs/Publishing-package-analyzer.md +++ /dev/null @@ -1,22 +0,0 @@ -> [!IMPORTANT] -> This page was copied from https://github.com/dart-lang/sdk/wiki and needs review. -> Please [contribute](../CONTRIBUTING.md) changes to bring it up-to-date - -> removing this header - or send a CL to delete the file. - ---- - -## Publishing an alpha version - -`package:analyzer` depends on kernel and front_end. We push those last two packages for the benefit of `package:analyzer`, but their APIs don't currently follow semver, so we set analyzer to depend on exact versions. - -Publishing a new alpha version of package analyzer involves a few steps: -- rev package:analyzer to a new alpha version (`0.31.0-alpha.0` ==> `0.31.0-alpha.1`) -- rev package:front_end to a new alpha version; update its version of package:kernel (see the next line) -- rev package:kernel to a new alpha version; update its version of package:front_end -- update the kernel and front_end version in `package:analyzer`'s pubspec -- commit a CL with the above changes -- publish `package:analyzer`, `package:kernel`, and `package:front_end` - -## Publishing a new stable version - -Many packages depend on `package:analyzer`. These packages often have version constraints that have an upper bound on the last major version of the analyzer. Publishing a new major version of `package:analyzer` requires careful orchestration with other major packages in the Dart ecosystem (in particular, `package:test`, and to a lesser extent, `package:angular`). diff --git a/docs/Writing-Web-Browser-Tests.md b/docs/Writing-Web-Browser-Tests.md deleted file mode 100644 index 762b338440c..00000000000 --- a/docs/Writing-Web-Browser-Tests.md +++ /dev/null @@ -1,132 +0,0 @@ -> [!IMPORTANT] -> This page was copied from https://github.com/dart-lang/sdk/wiki and needs review. -> Please [contribute](../CONTRIBUTING.md) changes to bring it up-to-date - -> removing this header - or send a CL to delete the file. - ---- - -# Who is this article for? - -If you are writing tests of core parts of the Dart SDK, there are special -tools to run these tests on browsers. If you are writing tests for a package -that is not part of the Dart SDK distribution, then -[package:test](http://github.com/dart-lang/test/blob/master/README.md), -previously called "unittest", is the best way for you to write your unit tests -for browsers and the standalone Dart vm. Published Dart packages are -automatically tested using [Drone.io](http://readme.drone.io/pub/overview). - -The remainder of this article is about the browser test infrastructure for -core Dart libraries and tools in the Dart repository. These test suites -are run by the tools/test.py tool, -and can be run on web browsers as well as the standalone Dart vm. -In the most common case, Dart scripts are wrapped in an automatically-created -HTML wrapper page, and compiled to JS using dart2js, to run on web browsers. - -Usually, this is the best way to test dart:html or other web features, -but a few complex cases require us to write a custom html file, rather -than using the HTML wrapper file. - - -# Details - -A test script testing Dart's web libraries, for example a test in -tests/html, will create the DOM elements it needs to test in the test -script itself. WebPlatformTest tests in the test/co19 test suite will -add HTML or DOM elements to the document, and then operate on them. -This is the best way to create and test a web page. For example, the -test -WebPlatformTest/html/semantics/tabular-data/the-table-element/insertRow-method\_t01.dart -contains the following Dart code: - -```dart -const String htmlEL = r''' -
- - -
-
-
-'''; - -void main() { - document.body.appendHtml(htmlEL); - ... -} -``` - -## Running Tests - -When a test is run on a browser, the wrapper HTML file, and the -modified or compiled Dart scripts are put into a directory called -generated\_tests, under the build directory that the Dart executable -and SDK are built in. The test server runs a local HTTP server, that -serves files from the build directory, and also from the Dart -repository root, and starts a browser that runs the tests fetched from -this server. To debug a test, you can start this HTTP server, and -then open the test's web page manually in a browser. The output of -test.py includes the command lines necessary to do this. - -## Custom HTML Tests - -If a test requires a custom HTML file, and cannot be written by adding -DOM elements to a page after it is loaded, then the test scripts allow -you to write the HTML file separately, and use it instead. There are -two systems for doing this. The first system adds a custom HTML file -to the test called foo\_test.dart by putting an HTML file called -foo\_test.html in the same directory. The second system creates a -test from any file ending in `_htmltest.html` in that directory, like -bar\_htmltest.html. - -### `_test.html` custom HTML files - -To be filled in - -### `_htmltest.html` tests - -An HTML file with a name that ends in `_htmltest.html` will be read by -the test infrastructure, and metadata about what scripts are used and -what messages the test should post to the document window is read from -an annotation in that file. - -The annotation is a JSON dictionary, embedded between two delimiters, -and it can be put inside an HTML comment so that the unprocessed page -looks like valid HTML: - -```html - -``` - -The test will pass if the web page posts all the strings in the -expectedMessages property to its top-level window, for example by -executing lines like - -```javascript -window.postMessage('squid', '*'); -``` - -Scripts in the 'scripts' property of the annotation will be -automatically copied from the test directory to the generated-test -directory, and compiled from dart to js if necessary. The script tags -using Dart scripts should be written exactly like - -```html - -``` -in order for the test generation to find and modify them. - -In order for the test framework to catch all errors in this HTML test, -the first script that executes on this page must be: - -```html - -``` - This allows the test framework -to attach an error handler to the window at the first opportunity, -before the scripts being tested have run.