Choosing selectors

[MattiSG]

What selectors do you want to write and see in Open Terms Archive declarations?

Goal

This discussion aims at defining common guidelines for what can be considered “good” selectors, in order to minimise ongoing maintenance and limit variation based on individual preferences, so that contributors and reviewers can achieve fast integration of documents with limited effort and no personal criticism.

Context

Selectors are used to target parts of documents that should be stored or removed. There are usually several valid ways to select the same parts of a document, and an important part of the review process of a suggested tracking is to check the validity and relevance of those selectors.

These selectors are the most commonly discussed and modified part during a review (for their choice, order or specificity).

Urgency

There has been a noted increase in contributions from new contributors in the last two weeks, and the time spent on reviews increases accordingly. The cost-to-benefit ratio of writing guidelines vs 1-on-1 training is thus shifting in favour of writing.

Deliverable

The end result of this discussion will be a set of opinions, arguments and hopefully converging suggested guidelines, from which a final set of guidelines will be derived by @OpenTermsArchive/Core and documented either in a wiki page or in a CONTRIBUTING file. The final writeup will be open for review to all contributors before integration.

Decision process

The decision process will be debate and consensus-based, with final arbitration by @OpenTermsArchive/Core as last resort if necessary.

The planned time for discussion is 7 days, which can be extended once in case of noted divergences.

[Kissaki]

I think a guideline for choosing selectors is a good idea, although the choice will inherently remain subjective and page contextual. The guideline will only be able to guide, not serve as a reference for correct selectors [on changes].

Nevertheless, it can guide users into choosing good selectors, reducing differences between the declarations, and serve as a diffuse base for review considerations. I imagine a reviewer will often have to conclude to good enough where their preference or the other authors are equally valid given assumptions are made about both the designed or generated website DOM structure and how it may change in the future.

Because of the diffuse and assumptuous context/problem space, the guideline should be and probably can only be a broad guidance rather than concrete follow-along/decision-tree guide.

Trying to use selectors that will remain valid in the future is a guessing game on what the provider will do. We can only make educated guesses from interpretations of the DOM structure.

As a guideline we may be able to formalize and write down these (common) interpretations and guesses.

My expectation from most stable to least (if the elements exist) would be something like

1. main
2. header content element (e.g. div container, possibly #main or .main or .content etc) and footer
3. specific id or class names on content block that indicates main content block (possibly #main' or .mainor.content` etc)
4. id or class name that looks hand/human picked
5. generated class or id

Considering specificity the goal of not including unrelated new content and including new content that should be included are in direct conflict. Choosing a good specificity is inherently diffuse and subjective. (Including too much may be more visible, more obvious to spot for having to update the selectors because the content shows up in the versions?)

Inspecting CMS for their DOM structure and documenting best practices for those seems unfeasible. There are too many CMS and too few declarations for them each to make this worth it.

Given that we are completely exposed and dependent on the upstream services changes to their websites, and the inherent potentially unstable nature of selectors validity, considering and creating a good break and fix workflow would be great if not necessary. Although I feel like even though the exposure is high and wide, websites are likely to remain stable over long times. Companies do not regularly change CMS, core DOM structure, or website designs.

---

To summarize and conclude, I think a reasonable/good guideline would

• describe the considerations (goals, stability, diffuseness, dependency on/exposure to providers choices)
• describe the preference on common elements/element types (inferred from the change frequency expectation listed above)
• provide examples for simple and common cases
  • select main
  • select after header before footer
  • select main content block by common/seemingly obvious class or id
  • a more complicated and subjective example, with note of being a best guess/reasonable guess

[martinratinaud]

Selectors can indeed be quite complicated to find and here are some thoughts from my experience in adding and maintaining several hundreds of them.

1. it is unlikely that it can ever be automated.
   As @Kissaki mentioned, this will act as guidance and if there were to be a decision tree, it would be a very simple one.
   Selectors are often decided from a visual inspection and versions generated are sometimes containing hidden texts that are not meant to be tracked, which makes it almost impossible to automate.

2. Guidance definitely leads to better easier-to-review contributions.
   After iterating with the PGA and france team, the provided selectors gets better and better quite fast once the guidance is provided. For now, it has been done through workshops but the resulting guidelines of this discussion included in the contribution tool will definitely be worth it.

3. A review from a maintainer with technical skills is mandatory.
   While selectors can be easily visually selected by any maintainer, giving the intention of what is aimed to be tracked, it is mandatory that somebody with technical skills reviews this before merging, to ensure maintainability.

4. Selectors should not be too specific
   There sometimes is an easy selector for what seems to be the main content of the document, but what if a banner appears, invalidating the whole content. (i.e. "The following terms are now outdated, please follow this link to get the latest ones").
   This does not happen often of course, but I think it's necessary to keep this in mind when defining selectors.

5. Index table are part of the document and should be tracked
   The index table is something that is creating a lot of clutter but seems important, regarding the document to be tracked. By Index Table, i'm talking about the one that is applicable to the document itself, and not the one for other documents.

---

Considering this, here is how I would structure this guidelines document:

• Describe broadly the goals (stability, exhaustivity of content)
• Describe the risks of not tracking all data (misleading versions)
  • it is better to track more content than fewer as long as this content is not causing blink
• Describe briefly how selectors work
  • CSS querySelector
    Link to CSS training on CSS Tricks or other but write down most common examples (for contributors that may not take the time to read the full CSS spec)
    • class: .something
    • attribute: [role="main"]
    • attribute starts with: [class^="topBanner-"]
    • attribute ends with: [class$="-suffix"]
    • attribute contains: [data-attr-id*="something-in-the-middle"]
    • element with direct child: .main > div
    • element with nested child: .main section
  • Range selectors
    • startBefore: contains the selector
    • startAfter: does not contain the selector
    • endBefore: does not contain the selector
    • endAfter: contains the selector
• Describe what is a bad selector
  • class being a series of alphanumeric characters .dez68h
  • class containing a series of alphanumeric characters .topBanner-dez68h
  • selector relying on deep nesting of elements main > div > div > div:nth-child(3)
  • selector using nth-child (most of the time, except when specific parts of the document are aimed at being tracked)
• Describe how to pick a good selector
  • introduction on how we define a good selector
    • simple (see description in contribution tool PR)
    • stable
    • ...
  • and proposed selectors in order of preference
    • range selector between header and footer
    • obvious selector that contains content:
      • id (#mainContent)
      • self describing attribute (.legal-notice, [role="main"])
    • range selector between obvious selectors
    • main or .main if it contains nothing but the aimed content and you're sur no other tag with main is used on the page, which may happen.
    • any other selector
• Questions to ask after selector has been chosen
  This section is redundant with the latter but i'm wondering if it could not be interesting to have a set of questions to include in the PR so that reviewers can make sure what they review is good?

[clementbiron]

I'm probably not going to say much better than @martinratinaud and @Kissaki but maybe wording things differently will be helpful in writing this guide.

The most important thing is that we need to choose the CSS selectors that are most resistant to document changes because this reduces the cost of maintenance.

Stable selectors are like [role="main"], #cms-page-content or .tos. They appear to be stable because they can theoretically better continue to correctly target the meaningful part of the document through these updates.

Unstable selectors are like ._9nrm or #cms-help-content-results > div > div:first-child. They are probably less effective at tracking the meaningful part of the document through these updates. Note that they often have a higher CSS specificity score.

It would be interesting to show examples of DOMs and associated selectors with different levels of difficulty.

[Ndpnt]

I mainly agree with previous comments.

Here are the points I would like to highlight:

• Like index table, title should always be included even if it's outside the main content of the document.

• It is better to make a wide selection (with select in declaration) and then remove the excess (with remove in declaration).
  With this in mind, I would suggest to privilege selectors which intrinsically make sense like main, header, [role=banner], [role=main],… In combination with range selectors, it could be more robust and avoid to miss some content.

For example:

"select": [
  {
    "startAfter": "[role=\"banner\"]",
    "endBefore": "footer"
  }
],
"remove": [
  ".breadcrumb",
  "form"
],

• Range selectors are not constrained by the CSS box model and allow to select content that starts in one box and ends in another box that are not in the same tree. It is powerful and maybe underused today.

• Avoid selectors that depend too much on the DOM structure such as >, ~, +, nth-child, …

[afisher3578]

Everyone included points that I agree are necessary. I do not have many new recommendations other then a section that documents a workflow for reviewers. However I highlighted all of the main points from everyone's comments in a structure that I find would be beneficial in this guide.

1. Briefly describe the goal of finding the best selectors.

• Highlight that this is challenging given that we are working in a reactionary way to how upstream services adjust their websites as mentioned by @Kissaki (No one fix all solution for all services)
• Focus on stability
• Tracking more content is better then less

2. Briefly describe how selectors work

• How @martinratinaud proposes with a link to CSS training and the most common examples in the guide
• class: .something
• attribute: [role="main"]
• attribute starts with: [class^="topBanner-"]
• attribute ends with: [class$="-suffix"]
• attribute contains: [data-attr-id*="something-in-the-middle"]
• element with direct child: .main > div
• element with nested child: .main section

3. What is considered a good/stable selector.

• Describing how a good selector is defined
• Order of preference:
  1. Range selector between header and footer
  2. Obvious/self describing attribute [role="main"], #cms-page-content or .tos
  3. …
• Also to include @Ndpnt point that it is better to include a wide selection and then to remove the excess.
• Include a description of how range selectors work, and how they are useful in some contexts to not be constrained by the CSS box model.

4. What is considered a bad/unstable selector

• class being a series of alphanumeric characters .dez68h
• class containing a series of alphanumeric characters .topBanner-dez68h
• Avoid relying on DOM structure too much
• selector relying on deep nesting of elements main > div > div > div:nth-child(3)
• selector using nth-child (most of the time, except when specific parts of the document are aimed at being tracked)

5. Example of DOMs with associated selectors

• As proposed by @clementbiron
• This is useful to see after seeing what good and bad selectors are

6. Include a section that describes best workflow for reviewers

• Highlight that this is a mandatory step to have changes reviewed by someone with technical skills.
• Briefly describe the workflow for reviews through the contrib tool and also for a outside PR.
• Set of questions that reviewers go back to while looking through the PR (Questions that are included in the contrib tool pr)
• Describe any common issues that occur and how to mitigate as a reviewer
• (Since I am at the stage of trying to get the PGA repo self sufficient, I find this section useful for reviewing and maintaining a repo without having to rely on the OTA team to review all PRs )

To summarize how I’d structure the guidelines document:

1. Highlight goals and challenges
2. How CSS selectors work
3. What is considered a good/stable selector.
4. What is considered a bad/unstable selector
5. Example of DOMs and selectors
6. Reviewer workflow

[MattiSG]

Thank you everyone for your contributions!

I know it has been a long time coming, but you can finally preview and review the proposal for the selectors choice guidelines!

The reviewer guidelines are live and are, as always, open for improvements 🙂