Code excerpts should be auto-updated and tested #407

chalin · 2017-10-23T21:32:32Z

... and ideally, as part of every build, similar to what is done for https://github.com/dart-lang/site-webdev.

Eventually, all code excerpts in the site should be subject to testing. We'll be progressively covering site pages (so that the code excerpts they contain are tested). Here is an ordered list provided by @kwalrath in a separate thread:

Possibly related issues:

Automated release testing Automated release testing #50
Use dartfmt on all samples in the language/library tour Use dartfmt on all samples in the language/library tour #190
Document code coverage utility Document code coverage utility #52

These are the original source files, unchanged, from up-and-running repo's `code` folder. These are the source files used in the language and library tours. Contributes to dart-lang#407

These are the original source files, unchanged, from up-and-running repo's code folder. These are the sources of the language and library tours. Contributes to #407

…our sources (#414) **Reviewers**: You'll probably want to focus your review efforts on **[`src/_guides/language/language-tour.md` while ignoring whitespace diffs](https://github.com/dart-lang/site-www/pull/414/files?w=1#diff-cd4b0043d2416c7c2db7fe09bba74060)**: - The code diffs that you will see are the result of having refreshed the code excerpts from their originating sources. (After this PR is merged, I'll set this up so that it happens automatically.) - In very few places I adjusted the Tour prose and/or examples -- but usually only after discussing the proposed change with you via email. TL;DR The purpose of this PR has been to adapt the **Language Tour**, and its example sources, so that we can use the [code_excerpt_updater](https://github.com/chalin/code_excerpt_updater) to auto-refresh code excerpts in the Language Tour markdown. For the most part, the language tour markdown already contained embedded paths to the source files it uses, and the source files contained some form of code excerpt markers. Consequently, most changes made in this PR are "lexical" and minor: - Sources under `examples/language-tour`: changed code excerpt marker syntax from - `BEGIN`/`END` to - `#docregion`/`#enddocregion`. - `src/_guides/language/language-tour.md`: changed inline code excerpt comments - `` to - `<?code-excerpt? "path/to/source"?>` processing instructions. Doc regions were manually adjusted to ensure that the code excerpts remained unchanged (except for genuine updates done to the code since the markdown was written). In a few cases files were relocated because they were in a wrong folder (e.g., deprecated was moved to metadata). Contributes to #407 What is left to do: I haven't touched code excepts that are in the Gists used with DartPad.

Contributes to dart-lang#407

* chore: adjust Travis setup in preparation for example testing Contributes to #407 * Get SDK channel from data file (don't assume that it is `stable`) * Update link to API pages in the docs

- See `examples/README.md` for details. Essentially, `examples` is now a Dart package from which all sample tests will be run. - A few tests are run in chrome, so Travis setup has been adapted so that chrome is installed and configured to run tests. - Also added highlights to some code excerpts (more will be added later). **Note**: Eventually the "original" example sources (`examples/language_tour ` and `examples/library_tour `) will be deleted, once we are sure that all relevant parts (including some that are only in Gists) have been integrated into the new package. Contributes to #407 and #416.

* Language tour example tests + Travis test job setup - See `examples/README.md` for details. Essentially, `examples` is now a Dart package from which all sample tests will be run. - A few tests are run in chrome, so Travis setup has been adapted so that chrome is installed and configured to run tests. - Also added highlights to some code excerpts (more will be added later). **Note**: Eventually the "original" example sources (`examples/language_tour ` and `examples/library_tour `) will be deleted, once we are sure that all relevant parts (including some that are only in Gists) have been integrated into the new package. Contributes to #407 and #416. * Post-review edits

Contributes to dart-lang#407 and dart-lang#416.

* Library tour example tests, up to but excluding dart:html Contributes to #407 and #416. * Post-review edits

Contributes to dart-lang#407 and dart-lang#416. Continuation of dart-lang#440

Contributes to #407 Staged at https://dartlang-org-staging-0.firebaseapp.com/guides/language/sound-problems

* Strong mode code excerpt tests for fix-it page Contributes to #407 Staged at https://dartlang-org-staging-0.firebaseapp.com/guides/language/sound-problems * Don't make "Fix" bold * Tweak canvas example code; add dynamic example * Section title change * Other misc post-review edits

kwalrath · 2018-03-01T01:41:27Z

I just took a look at analytics for the past week, when we've gotten a lot of new visitors, and here are my conclusions:

The VM Get Started tutorial should probably be tested, given its relatively high(er) readership.
We should consider adding tests for the following pages, which have small amounts of code:
- /dart-2 (prominent page, so it'd be embarrassing if the code broke)
- /guides/libraries/useful-libraries (not sure this is testable, but it mentions so many classes...)
- /tools/dartpad (39th most viewed page)
- /tools/pub/get-started (41st most viewed page)
The remaining pages with code snippets have low enough readership that we should probably skip them (for now, at least).

Here are the details on how things have changed (look for the bold font):

Homepage (no.1 page on the site, with ~26% of views [-> 29%]) - Homepage "compute pi" example: Dart sources, tests, and HTML-version generator #448
LANGUAGE > Tour (no.2, ~9%) - Setup language-tour.md for auto code-refresh from examples/language-tour sources #414, chore: adjust Travis setup in preparation for example testing #424, Language tour example tests + Travis test job setup #427
Dart 2 (no.3, ~6%) - might not have been listed before because it has minimal code... but it does have code.
LANGUAGE > Sample Code (no.11, 1.7% [-> no.13]) - Tests for samples #453
Tutorial (VM): Write HTTP Clients and Servers (no.12 [-> no.25]) - Tests for dart-vm httpserver tutorial code excerpts #463, Example(httpserver): minor cleanup #470
Library Tour (no.15) - Library tour example tests, up to but excluding dart:html #440, Library tour example tests for dart:html #443, Library tour example tests for dart:io, dart:convert, dart:mirrors #445
LANGUAGE > Effective Dart (style is no.17, usage no.22, doc no.24, design no.26) - code-excerpts for Effective Dart: styles, docs, usage #474, Tests and code-excerpts for Effective Dart Design #480
Tutorial: Asynchronous Programming: Futures (no.18) - Tests for Futures tutorial #538 (also see Consider consolidation of pages covering asynchrony/generator support #512)
Strong Mode Dart (no.25) - Strong mode code excerpt tests for main page #590, Strong mode code excerpt tests for fix-it page #603
Tutorial (VM): Get Started (no.29 [-> no.20])
Tutorial: Asynchronous Programming: Streams (no.34) - waiting on Consider consolidation of pages covering asynchrony/generator support #512
Cookbook: Dart by Example (no.42 [-> no.31])
...

chalin · 2018-03-01T16:27:40Z

Thanks for the updated analytics!

Contributes to #407

kwalrath · 2018-03-14T01:41:26Z

Somehow we missed Synonyms. At no.99, however, it's probably not a high priority, and it's complicated because we'd only be testing the Dart excerpts, not the other languages.

Contributes to #407

* Updates to Dart VM, Get Started Contributes to #407 * Feedback from Kathy

Contributes to #407, #637, #664

* Fix "What's the point?" mini-toc * Tutorial(streams): update for Dart 2 and analayze/test code Contributes to #407, #637, #664 * Edits following Kathy's review

kwalrath · 2019-07-31T00:50:41Z

Closed in favor of #1803.

chalin added the infra.structure Relates to the tools that create dart.dev label Oct 23, 2017

chalin self-assigned this Oct 23, 2017

chalin mentioned this issue Oct 26, 2017

Example code copied from up-and-running repo #411

Merged

chalin added a commit that referenced this issue Oct 26, 2017

Example code copied from up-and-running repo (#411)

ce076b2

These are the original source files, unchanged, from up-and-running repo's code folder. These are the sources of the language and library tours. Contributes to #407

This was referenced Nov 1, 2017

Setup language-tour.md for auto code-refresh from examples/language-tour sources #414

Merged

Trim down and reorganize examples code #416

Closed

Example DartPad Gists are becoming out-of-date: update or drop them #417

Closed

chalin added a commit to chalin/site-www that referenced this issue Nov 9, 2017

chore: adjust Travis setup in preparation for example testing

78c6f90

Contributes to dart-lang#407

chalin mentioned this issue Nov 9, 2017

chore: adjust Travis setup in preparation for example testing #424

Merged

chalin mentioned this issue Nov 13, 2017

Language tour example tests + Travis test job setup #427

Merged

This was referenced Nov 17, 2017

Split library tour #385

Closed

Host /samples code somewhere #367

Closed

Confusing code example in futures-error-handling guide #373

Closed

chalin added fix.examples Adds or changes example test.general Relates to unit, integration, perf testing labels Nov 19, 2017

chalin added a commit to chalin/site-www that referenced this issue Nov 20, 2017

Library tour example tests, up to but excluding dart:html

bce8c72

Contributes to dart-lang#407 and dart-lang#416.

chalin mentioned this issue Nov 20, 2017

Library tour example tests, up to but excluding dart:html #440

Merged

chalin added a commit that referenced this issue Nov 21, 2017

Library tour example tests, up to but excluding dart:html (#440)

783590c

* Library tour example tests, up to but excluding dart:html Contributes to #407 and #416. * Post-review edits

chalin added a commit to chalin/site-www that referenced this issue Nov 21, 2017

Library tour example tests from dart:html onwards

c1451ce

Contributes to dart-lang#407 and dart-lang#416. Continuation of dart-lang#440

chalin added a commit to chalin/site-www that referenced this issue Nov 22, 2017

Library tour example tests from dart:html onwards

8fc1d7a

Contributes to dart-lang#407 and dart-lang#416. Continuation of dart-lang#440

chalin added a commit to chalin/site-www that referenced this issue Nov 22, 2017

Library tour example tests from dart:html onwards

ad8e76b

Contributes to dart-lang#407 and dart-lang#416. Continuation of dart-lang#440

chalin mentioned this issue Feb 22, 2018

Strong mode code excerpt tests for fix-it page #603

Merged

chalin added a commit that referenced this issue Feb 22, 2018

Strong mode code excerpt tests for fix-it page

8cca216

Contributes to #407 Staged at https://dartlang-org-staging-0.firebaseapp.com/guides/language/sound-problems

chalin added a commit that referenced this issue Mar 1, 2018

Code excerpt checking for Dart 2 page

b431e39

Contributes to #407

chalin mentioned this issue Mar 1, 2018

Code excerpt checking for Dart 2 page #621

Merged

chalin added a commit that referenced this issue Mar 1, 2018

Code excerpt checking for Dart 2 page (#621)

24fd81c

Contributes to #407

chalin mentioned this issue Mar 14, 2018

[Meta] Site changes for Dart 2 #637

Closed

63 tasks

kwalrath mentioned this issue Mar 19, 2018

Consider consolidation of pages covering asynchrony/generator support #512

Closed

chalin added a commit that referenced this issue Apr 4, 2018

Updates to Dart VM, Get Started

44b18e8

Contributes to #407

chalin mentioned this issue Apr 4, 2018

Dart VM, Get Started updates #742

Merged

chalin added a commit that referenced this issue Apr 4, 2018

Updates to Dart VM, Get Started

46dd90a

Contributes to #407

chalin added a commit that referenced this issue Apr 5, 2018

Updates to Dart VM, Get Started

4d100e2

Contributes to #407

chalin added a commit that referenced this issue Apr 5, 2018

Dart VM, Get Started updates (#742)

d860c2e

* Updates to Dart VM, Get Started Contributes to #407 * Feedback from Kathy

chalin added a commit that referenced this issue Apr 23, 2018

Tutorial(streams): update for Dart 2 and analayze/test code

8e835a4

Contributes to #407, #637, #664

chalin added a commit that referenced this issue Apr 23, 2018

Tutorial(streams): update for Dart 2 and analayze/test code

998a37a

Contributes to #407, #637, #664

chalin mentioned this issue Apr 23, 2018

Tutorial(streams): update for Dart 2 and analayze/test code #813

Merged

chalin added a commit that referenced this issue Apr 27, 2018

Tutorial(streams): update for Dart 2 and analayze/test code

4301a9a

Contributes to #407, #637, #664

chalin mentioned this issue Jun 20, 2018

Mixins article is scary and out of date, remove? #946

Closed

kwalrath added p2-medium Necessary but not urgent concern. Resolve when possible. and removed p1-high Major but not urgent concern: Resolve in months. Update each month. labels Nov 15, 2018

kwalrath added e2-days Can complete in < 5 days of normal, not dedicated, work e3-weeks Complete in < 4 weeks of normal, not dedicated, work labels Feb 1, 2019

kwalrath unassigned chalin Jul 2, 2019

kwalrath mentioned this issue Jul 31, 2019

Test all code excerpts #1803

Closed

23 tasks

kwalrath closed this as completed Jul 31, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Code excerpts should be auto-updated and tested #407

Code excerpts should be auto-updated and tested #407

chalin commented Oct 23, 2017 •

edited

Loading

kwalrath commented Mar 1, 2018 •

edited by chalin

Loading

chalin commented Mar 1, 2018

kwalrath commented Mar 14, 2018

kwalrath commented Jul 31, 2019

Code excerpts should be auto-updated and tested #407

Code excerpts should be auto-updated and tested #407

Comments

chalin commented Oct 23, 2017 • edited Loading

kwalrath commented Mar 1, 2018 • edited by chalin Loading

chalin commented Mar 1, 2018

kwalrath commented Mar 14, 2018

kwalrath commented Jul 31, 2019

chalin commented Oct 23, 2017 •

edited

Loading

kwalrath commented Mar 1, 2018 •

edited by chalin

Loading