Cache contexts are now hierarchical

When varying something per-user, it's pointless to also vary that per-role. But if one part of the page is varied per user and another per role, then Drupal needs to be smart enough to make the combination of the two only vary per user.

Therefore, a hierarchy of cache contexts is necessary. This is crucial for ensuring good cache hit ratios. (And therefore also for #2429617: Make D8 2x as fast: Dynamic Page Cache: context-dependent page caching (for *all* users!).)

Also see the docs: https://www.drupal.org/developing/api/8/cache/contexts

Before

Not only is there no hierarchy information, it's also kind of a jungle to wade through.

book_navigation
language
menu.active_trail
node_view_grants
pager
theme
timezone
url
user
user.roles

After

We've established a clear pattern to define the tree:

• periods separate parents from children
• everywhere where cache contexts are used, that entire hierarchy is listed, which has 3 benefits:
  1. no ambiguity: it's clear what parent cache context is based on wherever it is used
  2. comparing (and folding) cache contexts becomes simpler: if both a.b.c and a.b are present, it's obvious that a.b encompasses a.b.c, and thus it's clear why the a.b can be omitted, why it can be "folded" into the parent
  3. no need to deal with ensuring each level in a tree is unique in the entire tree
• a plurally named cache context indicates a parameter may be specified; to use: append a colon, then specify the desired parameter (when no parameter is specified, all possible parameters are captured, e.g. all query arguments)

cookies
  :name
headers
  :name
ip
languages
  :type
request_format
route
  .book_navigation
  .menu_active_trails
    :menu_name
  .name
theme
timezone
url
  .host
  .query_args
    :key
    .pagers
      :pager_id
user
  .is_super_user
  .node_grants
    :operation
  .roles
    :role

Updating existing code

Unaffected cache contexts:

• theme
• timezone
• url
• user
• user.roles

Affected cache contexts:

• pager:0 -> url.query_args.pagers:0
• language -> languages
• node_view_grants -> user.node_grants:view
• menu_active_trail:tools -> url.route.menu_active_trails:tools

New cache contexts:

• cookies
• cookies:<name>
• headers
• headers:<name>
• ip
• languages:<type>
• request_format
• route
• route.menu_active_trails
• route.name
• url.host
• url.pagers
• url.query_args
• url.query_args:<key>
• user.is_super_user
• user.node_grants
• user.node_grants:<operation other than view>
• user.roles:<role>