diff --git a/docs/architecture.md b/docs/architecture.md index 6bde4f9adc3b..8169adaaf10b 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 6d71361d18e8..3d446a62e39a 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 fa399d2c0046..31a578d1c076 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 bc0686c794aa..02e363df7b96 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 1c8ce232e5fd..913321685f2e 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 7af9d6585003..2a842146b59a 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 31d0ce027bf5..039bd0ae3db4 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 b6fb99424388..7a7e8444cdca 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 2cfdf931f8d3..542fb1056dea 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̂ś"