From cc6a8dad78b6b2952c6fef545aff9d18fcd3f011 Mon Sep 17 00:00:00 2001 From: Stephanie Hobson Date: Thu, 24 Jul 2025 16:36:51 -0700 Subject: [PATCH 1/4] Add code review checklists to docs --- docs/docs/attribution/0001-analytics.md | 59 ++++++++++--------------- docs/docs/checklists/analytics.md | 36 +++++++++++++++ docs/docs/checklists/css.md | 23 ++++++++++ docs/docs/checklists/experiments.md | 23 ++++++++++ docs/docs/checklists/general.md | 25 +++++++++++ docs/docs/checklists/html.md | 30 +++++++++++++ docs/docs/checklists/js.md | 8 ++++ docs/docs/checklists/l10n.md | 37 ++++++++++++++++ docs/docs/checklists/media.md | 2 + docs/docs/checklists/tests.md | 10 +++++ docs/docs/pr-checklists.md | 12 ----- docs/mkdocs.yml | 10 +++++ 12 files changed, 227 insertions(+), 48 deletions(-) create mode 100644 docs/docs/checklists/analytics.md create mode 100644 docs/docs/checklists/css.md create mode 100644 docs/docs/checklists/experiments.md create mode 100644 docs/docs/checklists/general.md create mode 100644 docs/docs/checklists/html.md create mode 100644 docs/docs/checklists/js.md create mode 100644 docs/docs/checklists/l10n.md create mode 100644 docs/docs/checklists/media.md create mode 100644 docs/docs/checklists/tests.md delete mode 100644 docs/docs/pr-checklists.md diff --git a/docs/docs/attribution/0001-analytics.md b/docs/docs/attribution/0001-analytics.md index 5737c73d918..67120b7078a 100644 --- a/docs/docs/attribution/0001-analytics.md +++ b/docs/docs/attribution/0001-analytics.md @@ -65,18 +65,11 @@ CTA ("Call to Action") click is intented to track the one or two main actions th The attribute `data-cta-text` must be present to trigger the event. All links to accounts.mozilla.com must also use `data-cta-type`. -| Data Attribute | Expected Value | -| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `data-cta-text` * | Text or name of the link (e.g. `Sign Up`, `Start Here`, `Get Relay`, `See your report`, `Read the Manifesto`). | -| | | -| | - This does not need to exactly match the text displayed to the user | -| | - Defining this is useful to group the link clicks across locales | -| | - - this attribute is required | -| `data-cta-position` | Location of CTA on the page (e.g. `primary`, `secondary`, `banner`, `pricing`) | -| `data-cta-type` | fxa-servicename (e.g. `fxa-sync`, `fxa-monitor`, `fxa-vpn`, `monitor`, `relay`) | -| | | -| | - This is to group CTAs by their destination | -| | - Do not use this to identify the element (ie. link, button) | +| Data Attribute | Expected Value | +| -------------- | -------------- | +| `data-cta-text` * | Text or name of the link (e.g. `Sign Up`, `Start Here`, `Get Relay`, `See your report`, `Read the Manifesto`).
- This does not need to exactly match the text displayed to the user
- Defining this is useful to group the link clicks across locales
* This attribute is required | +| `data-cta-position` | Location of CTA on the page (e.g. `primary`, `secondary`, `banner`, `pricing`) | +| `data-cta-type` | fxa-servicename (e.g. `fxa-sync`, `fxa-monitor`, `fxa-vpn`, `monitor`, `relay`)
- This is to group CTAs by their destination
- Do not use this to identify the element (ie. link, button) | | `data-cta-name` | A identifier for this cta that is unique across the entire site. (e.g. `fx20-primarycta`, `wnp118-sfaq-so-special-features`). This is to help with reporting since it is difficult to filter on more than one parameter at a time. | ``` html @@ -93,10 +86,10 @@ Link click is intended to track links that are of interest but not the focus of The attribute `data-link-text` must be present to trigger the event. -| Data Attribute | Expected Value | -| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| Data Attribute | Expected Value | +| -------------- | -------------- | | `data-link-text` * | Text or name of the link (e.g. `Monitor`, `Features`, `Instagram (mozilla)`, `Mozilla VPN`). - * this attribute is required | -| `data-link-position` | Location of CTA on the page (e.g. `topnav`, `subnav`, `body`, `features`) | +| `data-link-position` | Location of CTA on the page (e.g. `topnav`, `subnav`, `body`, `features`) | ``` html

This is text with a simpleexample.

@@ -292,46 +285,40 @@ TrackProductDownload.sendEvent(customEventObject); We are using the custom event `widget_action` to track the behaviour of javascript widgets. -**How do you chose between \`\`widget_action\`\` and \`\`cta_click\`\`?** - -| widget_action | cta_click | -| ----------------------------------------------------------- | -------------------------------------------------------- | -| The action is specific or unique. | The action is \"click\". | -| | | -| *(Only the language switcher changes* *the page language.)* | | -| The user does not leave the page. | It sends the user somewhere else. | -| It requires Javascript to work. | No JS required. | -| It can perform several actions. | It does one action. | -| | | -| *(A modal can be opened and closed.)* | | -| There could be several on the page doing different things. | There could be several on the page doing the same thing. | -| | | -| *(An accordion list of FAQs)* | *(A download button in the header and footer.)* | +**How do you chose between `widget_action` and `cta_click`?** + +| widget_action | cta_click | +| ------------- | --------- | +| The action is specific or unique.
*(example: only the language switcher changes the page language.)* | The action is "click". | +| The user does not leave the page. | It sends the user somewhere else. | +| It requires Javascript to work. | No JS required. | +| It can perform several actions.
*(example: modal can be opened and closed.)* | It does one action.| +| There could be several on the page doing different things.
*(An accordion list of FAQs)* | There could be several on the page doing the same thing.
*(A download button in the header and footer.)*| Properties for use with ``widget_action`` (not all widgets will use all options): - type - **Required.** - The type of widget. - - Examples: \"modal\", \"protection report\", \"affiliate notification\", \"help icon\". - - *Avoid "button" or "link". If you want to track a link or button use \`cta_click\`.* + - Examples: "modal", "protection report", "affiliate notification", "help icon". + - *Avoid "button" or "link". If you want to track a link or button use `cta_click`.* - action - **Required.** - The thing that happened. - - Examples: \"open\", \"accept\", \"timeout\", \"vote up\". + - Examples: "open", "accept", "timeout", "vote up". - *Avoid "click". If you want to track a click use \`cta_click\`.* - text - How is this action labeled to the user? - - Examples: \"Okay\", \"Check your protection report\", \"Get the app\" + - Examples: "Okay", "Check your protection report", "Get the app" - name - Give the widget a name. - - You probably only need this optional attribute if the ``text`` value is not enough to tell the widgets apart. + - You probably only need this optional attribute if the `text` value is not enough to tell the widgets apart. - This can help you group actions from the same widget, or make it easier to find the widget in the reports. - The dashes are not required but they\'re allowed if you want to match the element class or ID. - - Examples: \"dad-joke-banner\", \"focus-qr-code\", \"Join Firefox Modal\" + - Examples: "dad-joke-banner", "focus-qr-code", "Join Firefox Modal" - non_interaction (boolean) - True if the action was triggered by something other than a user gesture. diff --git a/docs/docs/checklists/analytics.md b/docs/docs/checklists/analytics.md new file mode 100644 index 00000000000..28d02b36efc --- /dev/null +++ b/docs/docs/checklists/analytics.md @@ -0,0 +1,36 @@ +## Links `` + +- [ ] Has a `data-cta-text` OR `data-link-text` + - [ ] If it has class `mzp-c-button` it is a CTA + - [ ] If it has class `mzp-c-cta-link` it is a CTA + - [ ] If there are two of the same `data-cta-text` include `data-cta-position` + - [ ] Does not have both `data-cta-text` and `data-link-text` +- [ ] If linking to another Mozilla property include `utm` params +- Download button: + - [ ] Use the appropriate helper, don't hard code these. (`download_firefox_thanks`, `google_play_button`, `apple_app_store_button`) + - [ ] include a download_location if there are multiple buttons on the page + +# Buttons `