From 7c0a84a71d9ace96a4d2e8c56c72afc2cb3a4ca8 Mon Sep 17 00:00:00 2001 From: Paul Irish Date: Tue, 19 Apr 2022 13:24:10 -0700 Subject: [PATCH] docs: fix some broken links (#13872) --- docs/architecture.md | 2 +- docs/new-audits.md | 32 +++++++++---------- docs/understanding-results.md | 4 +-- docs/v8-perf-faq.md | 4 +-- .../byte-efficiency/legacy-javascript.js | 2 +- .../reports/sample-flow-result.json | 6 ++-- lighthouse-core/test/results/sample_v2.json | 2 +- shared/localization/locales/en-US.json | 2 +- shared/localization/locales/en-XL.json | 2 +- 9 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 6bde4f9adc..8169adaaf1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -13,7 +13,7 @@ _Some incomplete notes_ 3. `defaultPass.devtoolslog.json`: A log of all the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) events. Primary signal about network requests and page state. * **Audit** - The [audits](../lighthouse-core/audits) are tests for a single feature/optimization/metric. Using the Artifacts as input, an audit evaluates a test and resolves to a numeric score. See [Understanding Results](./understanding-results.md) for details of the LHR (Lighthouse Result object). * **Computed Artifacts** - [Generated](../lighthouse-core/computed) on-demand from artifacts, these add additional meaning, and are often shared amongst multiple audits. -* **Report** - The report UI, created client-side from the LHR. See [HTML Report Generation Overview](../report/readme.md) for details. +* **Report** - The report UI, created client-side from the LHR. See [HTML Report Generation Overview](../report/README.md) for details. ### Audit/Report terminology * **Category** - Roll-up collection of audits and audit groups into a user-facing section of the report (eg. `Best Practices`). Applies weighting and overall scoring to the section. Examples: PWA, Accessibility, Best Practices. diff --git a/docs/new-audits.md b/docs/new-audits.md index 6d71361d18..3d446a62e3 100644 --- a/docs/new-audits.md +++ b/docs/new-audits.md @@ -1,17 +1,17 @@ -So, you want to create a new audit? Great! We're excited that you want to add to the Lighthouse project :) The goal of this +So, you want to create a new audit? Great! We're excited that you want to add to the Lighthouse project :) The goal of this document is to help you understand what constitutes as a "good" audit for Lighthouse, and steps you can follow if you want -to propose a new audit. +to propose a new audit. ## New audit principles Lighthouse audits that surface in the report should: -- be applicable to a significant portion of web developers (based on scale and severity of impact) -- contribute significantly towards making the mobile web experience better for end users. -- not have a significant impact on our runtime performance or bundle size. -- be new, not something that is already measured by existing audits. +- be applicable to a significant portion of web developers (based on scale and severity of impact) +- contribute significantly towards making the mobile web experience better for end users. +- not have a significant impact on our runtime performance or bundle size. +- be new, not something that is already measured by existing audits. - be measurable (especially for performance audits) or have clear pass/fail states. - be actionable - when failing, specific advice should be given. If the failure can be tied to a specific resource (a DOM element, script, line of code), use the appropriate detail type (see below). If multiple failures can occur for a page, return a table. -- not use 3rd party APIs for completing the audit check. +- not use 3rd party APIs for completing the audit check. ## Actionability @@ -21,7 +21,7 @@ Lighthouse audits that surface in the report should: ### Detail Types -An audit can return a number of different [detail types](https://github.com/GoogleChrome/lighthouse/blob/master/types/audit-details.d.ts). +An audit can return a number of different [detail types](https://github.com/GoogleChrome/lighthouse/blob/master/types/lhr/audit-details.d.ts). | detail type | resource | notes | |---------------------------|-----------------------|----------------------------------------| @@ -76,24 +76,24 @@ Standard Audit `failureTitle`: "Page does not work offline" ## Process for creating a new audit -1. Scan the criteria we’ve laid out above. If you think the principles match with your proposed new audit, then proceed! -1. Next step is to create an issue on GitHub with answers to the following questions: +1. Scan the criteria we’ve laid out above. If you think the principles match with your proposed new audit, then proceed! +1. Next step is to create an issue on GitHub with answers to the following questions: ``` #### Provide a basic description of the audit -#### How would the audit appear in the report? +#### How would the audit appear in the report? #### How is this audit different from existing ones? -#### What % of developers/pages will this impact? +#### What % of developers/pages will this impact? #### How is the new audit making a better web for end users? -#### What is the resourcing situation? +#### What is the resourcing situation? #### Any other links or documentation that we should check out? ``` 3. Once the proposal is submitted, then Lighthouse team will take a look and followup. We will discuss possible implementation approaches, and associated runtime overhead. -With this new information we can better understand the impl cost and effort required and prioritize the audit into our sprint/roadmap. -1. Depending on the prioritization, we'll then work with you to figure out the necessary engineering/UX/product details. +With this new information we can better understand the impl cost and effort required and prioritize the audit into our sprint/roadmap. +1. Depending on the prioritization, we'll then work with you to figure out the necessary engineering/UX/product details. diff --git a/docs/understanding-results.md b/docs/understanding-results.md index fa399d2c00..31a578d1c0 100644 --- a/docs/understanding-results.md +++ b/docs/understanding-results.md @@ -6,7 +6,7 @@ The result object contains all the audit information Lighthouse determined about The top-level Lighthouse Result object (LHR) is what the lighthouse node module returns and the entirety of the JSON output of the CLI. It contains some metadata about the run and the results in the various subproperties below. -For an always up-to-date definition of the LHR, take a look [at our typedefs](https://github.com/GoogleChrome/lighthouse/blob/master/types/lhr.d.ts). +For an always up-to-date definition of the LHR, take a look [at our typedefs](https://github.com/GoogleChrome/lighthouse/blob/master/types/lhr/lhr.d.ts). ### Properties @@ -60,7 +60,7 @@ An object containing the results of the audits, keyed by their name. | displayValue | string|undefined | The string to display in the report alongside audit results. If empty, nothing additional is shown. This is typically used to explain additional information such as the number and nature of failing items. | | score | number|null | The scored value determined by the audit provided in the numeric range `0-1`, or null if `scoreDisplayMode` indicates not scored. | | scoreDisplayMode | "binary" | "numeric" | "error" | "manual" | "notApplicable" | "informative" | A string identifying how the score should be interpreted for display i.e. is the audit pass/fail (score of 1 or 0), did it fail, should it be ignored, or are there shades of gray (scores between 0-1 inclusive). If set as `informative`, `notApplicable`, `manual`, or `error`, then `score` will be null and should be ignored. | -| details | `Object` | Extra information found by the audit necessary for display. The structure of this object varies from audit to audit. The [structure of this object](https://github.com/GoogleChrome/lighthouse/blob/master/types/audit-details.d.ts) is somewhat stable between minor version bumps as this object is used to render the HTML report. | +| details | `Object` | Extra information found by the audit necessary for display. The structure of this object varies from audit to audit. The [structure of this object](https://github.com/GoogleChrome/lighthouse/blob/master/types/lhr/audit-details.d.ts) is somewhat stable between minor version bumps as this object is used to render the HTML report. | ### Example diff --git a/docs/v8-perf-faq.md b/docs/v8-perf-faq.md index bc0686c794..02e363df7b 100644 --- a/docs/v8-perf-faq.md +++ b/docs/v8-perf-faq.md @@ -236,9 +236,9 @@ here](https://web.dev/performance-scoring/). ### What is the most exciting update in LH v8? We're really excited about the [interactive -treemap](https://github.com/GoogleChrome/lighthouse/blob/v8changelog/changelog.md#treemap-release), +treemap](https://github.com/GoogleChrome/lighthouse/releases/tag/v7.5.0#:~:text=We%20are%20releasing%20the%20Lighthouse%20Treemap), [filtering audits by -metric](https://github.com/GoogleChrome/lighthouse/blob/v8changelog/changelog.md#:~:text=new%20metric%20filter), +metric](https://github.com/GoogleChrome/lighthouse/releases/tag/v8.0.0#:~:text=The%20report%20includes%20a-,new%20metric%20filter,-.%20Pick%20a%20metric), and the new [Content Security Policy audit](https://web.dev/strict-csp/#adopting-a-strict-csp), which was a collaboration with the Google Web Security team. diff --git a/lighthouse-core/audits/byte-efficiency/legacy-javascript.js b/lighthouse-core/audits/byte-efficiency/legacy-javascript.js index 1c8ce232e5..913321685f 100644 --- a/lighthouse-core/audits/byte-efficiency/legacy-javascript.js +++ b/lighthouse-core/audits/byte-efficiency/legacy-javascript.js @@ -30,7 +30,7 @@ const UIStrings = { // eslint-disable-next-line max-len // TODO: web.dev article. this codelab is good starting place: https://web.dev/codelab-serve-modern-code/ /** Description of a Lighthouse audit that tells the user about old JavaScript that is no longer needed. This is displayed after a user expands the section to see more. No character length limits. 'Learn More' becomes link text to additional documentation. */ - description: 'Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren\'t necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/)', + description: 'Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren\'t necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://web.dev/publish-modern-javascript/)', }; const str_ = i18n.createMessageInstanceIdFn(__filename, UIStrings); diff --git a/lighthouse-core/test/fixtures/fraggle-rock/reports/sample-flow-result.json b/lighthouse-core/test/fixtures/fraggle-rock/reports/sample-flow-result.json index 7af9d65850..2a842146b5 100644 --- a/lighthouse-core/test/fixtures/fraggle-rock/reports/sample-flow-result.json +++ b/lighthouse-core/test/fixtures/fraggle-rock/reports/sample-flow-result.json @@ -3177,7 +3177,7 @@ "legacy-javascript": { "id": "legacy-javascript", "title": "Avoid serving legacy JavaScript to modern browsers", - "description": "Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren't necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/)", + "description": "Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren't necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://web.dev/publish-modern-javascript/)", "score": 1, "scoreDisplayMode": "numeric", "numericValue": 0, @@ -9032,7 +9032,7 @@ "legacy-javascript": { "id": "legacy-javascript", "title": "Avoid serving legacy JavaScript to modern browsers", - "description": "Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren't necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/)", + "description": "Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren't necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://web.dev/publish-modern-javascript/)", "score": 1, "scoreDisplayMode": "numeric", "numericValue": 0, @@ -17256,7 +17256,7 @@ "legacy-javascript": { "id": "legacy-javascript", "title": "Avoid serving legacy JavaScript to modern browsers", - "description": "Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren't necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/)", + "description": "Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren't necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://web.dev/publish-modern-javascript/)", "score": 1, "scoreDisplayMode": "numeric", "numericValue": 0, diff --git a/lighthouse-core/test/results/sample_v2.json b/lighthouse-core/test/results/sample_v2.json index 31d0ce027b..039bd0ae3d 100644 --- a/lighthouse-core/test/results/sample_v2.json +++ b/lighthouse-core/test/results/sample_v2.json @@ -5103,7 +5103,7 @@ "legacy-javascript": { "id": "legacy-javascript", "title": "Avoid serving legacy JavaScript to modern browsers", - "description": "Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren't necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/)", + "description": "Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren't necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://web.dev/publish-modern-javascript/)", "score": 0.88, "scoreDisplayMode": "numeric", "numericValue": 150, diff --git a/shared/localization/locales/en-US.json b/shared/localization/locales/en-US.json index b6fb994243..7a7e8444cd 100644 --- a/shared/localization/locales/en-US.json +++ b/shared/localization/locales/en-US.json @@ -603,7 +603,7 @@ "message": "Use video formats for animated content" }, "lighthouse-core/audits/byte-efficiency/legacy-javascript.js | description": { - "message": "Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren't necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/)" + "message": "Polyfills and transforms enable legacy browsers to use new JavaScript features. However, many aren't necessary for modern browsers. For your bundled JavaScript, adopt a modern script deployment strategy using module/nomodule feature detection to reduce the amount of code shipped to modern browsers, while retaining support for legacy browsers. [Learn More](https://web.dev/publish-modern-javascript/)" }, "lighthouse-core/audits/byte-efficiency/legacy-javascript.js | title": { "message": "Avoid serving legacy JavaScript to modern browsers" diff --git a/shared/localization/locales/en-XL.json b/shared/localization/locales/en-XL.json index 2cfdf931f8..542fb1056d 100644 --- a/shared/localization/locales/en-XL.json +++ b/shared/localization/locales/en-XL.json @@ -603,7 +603,7 @@ "message": "Ûśê v́îd́êó f̂ór̂ḿât́ŝ f́ôŕ âńîḿât́êd́ ĉón̂t́êńt̂" }, "lighthouse-core/audits/byte-efficiency/legacy-javascript.js | description": { - "message": "P̂ól̂ýf̂íl̂ĺŝ án̂d́ t̂ŕâńŝf́ôŕm̂ś êńâb́l̂é l̂éĝáĉý b̂ŕôẃŝér̂ś t̂ó ûśê ńêẃ Ĵáv̂áŜćr̂íp̂t́ f̂éât́ûŕêś. Ĥóŵév̂ér̂, ḿâńŷ ár̂én̂'t́ n̂éĉéŝśâŕŷ f́ôŕ m̂ód̂ér̂ń b̂ŕôẃŝér̂ś. F̂ór̂ ýôúr̂ b́ûńd̂ĺêd́ Ĵáv̂áŜćr̂íp̂t́, âd́ôṕt̂ á m̂ód̂ér̂ń ŝćr̂íp̂t́ d̂ép̂ĺôým̂én̂t́ ŝt́r̂át̂éĝý ûśîńĝ ḿôd́ûĺê/ńôḿôd́ûĺê f́êát̂úr̂é d̂ét̂éĉt́îón̂ t́ô ŕêd́ûćê t́ĥé âḿôún̂t́ ôf́ ĉód̂é ŝh́îṕp̂éd̂ t́ô ḿôd́êŕn̂ b́r̂óŵśêŕŝ, ẃĥíl̂é r̂ét̂áîńîńĝ śûṕp̂ór̂t́ f̂ór̂ ĺêǵâćŷ b́r̂óŵśêŕŝ. [Ĺêár̂ń M̂ór̂é](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/)" + "message": "P̂ól̂ýf̂íl̂ĺŝ án̂d́ t̂ŕâńŝf́ôŕm̂ś êńâb́l̂é l̂éĝáĉý b̂ŕôẃŝér̂ś t̂ó ûśê ńêẃ Ĵáv̂áŜćr̂íp̂t́ f̂éât́ûŕêś. Ĥóŵév̂ér̂, ḿâńŷ ár̂én̂'t́ n̂éĉéŝśâŕŷ f́ôŕ m̂ód̂ér̂ń b̂ŕôẃŝér̂ś. F̂ór̂ ýôúr̂ b́ûńd̂ĺêd́ Ĵáv̂áŜćr̂íp̂t́, âd́ôṕt̂ á m̂ód̂ér̂ń ŝćr̂íp̂t́ d̂ép̂ĺôým̂én̂t́ ŝt́r̂át̂éĝý ûśîńĝ ḿôd́ûĺê/ńôḿôd́ûĺê f́êát̂úr̂é d̂ét̂éĉt́îón̂ t́ô ŕêd́ûćê t́ĥé âḿôún̂t́ ôf́ ĉód̂é ŝh́îṕp̂éd̂ t́ô ḿôd́êŕn̂ b́r̂óŵśêŕŝ, ẃĥíl̂é r̂ét̂áîńîńĝ śûṕp̂ór̂t́ f̂ór̂ ĺêǵâćŷ b́r̂óŵśêŕŝ. [Ĺêár̂ń M̂ór̂é](https://web.dev/publish-modern-javascript/)" }, "lighthouse-core/audits/byte-efficiency/legacy-javascript.js | title": { "message": "Âv́ôíd̂ śêŕv̂ín̂ǵ l̂éĝáĉý Ĵáv̂áŜćr̂íp̂t́ t̂ó m̂ód̂ér̂ń b̂ŕôẃŝér̂ś"