Document what a breaking change is

[mcoker]

Ultimately this will live on org. We should have some basic guidelines for what constitutes a breaking change. Some ideas:

• A breaking change is basically _any change with code shipped in our dist package that requires users update something on their end, otherwise it will be/appear broken.* This includes:
  • Visual changes - colors, borders, text appearance, padding/margin/spacing, etc
    • Significant/non-trivial changes are breaking. Small adjustments are OK.
      • Can we get a definition for how significant a visual change has to be to be "breaking"? cc @mceledonia @mcarrano
    • Things that will cause text to wrap where it may not have before the change. eg, larger text, larger inline padding/margin/spacing, maybe a smaller bounding box, etc
    • Things that may push content down on the page (out of the viewport), making it less visible than it was before the change. eg, larger text, larger block padding/margin/spacing, etc
  • Changes to class names
  • Changes to elements - is this true, assuming the element is not directly tied to the styling in any way? Changing a div to a span or paragraph, for example, or using a heading element in place of a generic one - I would expect those to be OK. But table styling dependent upon the element/tag name should be preserved since the styling is tied to the element name.
  • Changes to selectors - unless this changes specificity in a way that could break the role of a custom property in the selector, I would also expect this to be OK.
  • Changes to HTML structure - probably implied, but in a way that breaks things - the structure before the change will be broken with the change we're making. Using optional elements, or different structures of existing elements that work and are supported to work would be fine.
  • Changes to var names and their role ^[1]

1. This is the big one. CSS vars/custom properties are the public facing API for styling PF.

• They are preserved in their name and function and we do not break them
• In the future we may consider public vs internal vars in the future where internal vars can break, but public vars will not
• Users should avoid:
  • Styling specific selectors and regular properties directly as those are subject to change
  • Using the values of CSS vars directly. eg, to apply a white background that matches the default/primary background used in PF, using #fff/white/--pf-global--palette--white instead of --pf-global--BackgroundColor--100. Reasons:
    • The primary background color may change to a different shade/color in the existing theme.
    • The primary bacakground color may change to a specific color in a different (eg, dark) theme
  • Using a global var, or more base level var, when a more specific one is applicable. eg, using --pf-global--primary-color--100 instead of --pf-c-button--m-primary--BackgroundColor in a button to reference the background color of a primary button. Reasons - same as previous bullet point
  • A github issue should be added to request a themeable var if one does not already exist.

cc @mattnolting @srambach