component-library

This is where the reusable components live.

Dependencies and tooling

Do not add new dependencies to the base package.json. New tooling should be added under the packages/tools folder and be self contained with its functionality and dependencies managed locally within its package scope; this ensures that when a tool is removed from use all its dependencies leave with it and allows easy swap out of tooling as the repository matures.

Classnames

This library uses CSS Modules to make its classnames used unique. Any usage of this library will need to include a way to process the CSS Modules in their bundler; this is provided out of the box in several or via things like postcss.

General concept for internal developers

Classnames and structures are fixed in place, end users should not be able to modify the internal workings of the classes in components provided by this library; this is fairly standard across all JS libraries. As we use CSS Modules however we do provide a method for users to add their own classes either with a provided CSS Module or without via an override of the standard className props used in standard React HTML elements in order to add styling or change our internal styles as they need.

If a consumer developer provides a className to our components we need to make use of a set of class generator functions to ensure a consistent BEM naming convention is followed within a React component (search codebase for generateClasses). These functions will take our internal classnames and provided overrides and create the correct strings to add to any HTML element in the structure.

Class generator functions e.g generateClasses

This set of class generator functions is intended to create properly formed BEM classnames for any element in a component consistently while allowing an consumer of this library to have some level of control over the generated classnames.

At their most basic they generate a BEM compatible name to assist developers of this library in naming their classes correctly.

At a more advanced level they allow a developer to override the default used block names and either replace or supplement them with alternate classnames, with a simple override block passed in all other classes are updated to match including sub blocks, modifier classes, transition classes etc.

For guidance on how to make use of them check the other existing components.

Usage by consumer developers

Class names can be provided one of three ways:

• As a string
• As an object matching the classNameOverride prop type exported by @squiz/xaccel-prop-types with or without replacing internal classes
• As an object as above but with a CSS Module provided to translate internally generated names to unique names that match your CSS

As a string

<Collapsible className="MyExtraClass" />

As an object matching the classNameOverride prop type exported by @squiz/xaccel-prop-types

// This will add MyExtraClass to the HTML generated by the library:
<Collapsible className={{
    className: "MyExtraClass"
}} />

or

/*
    This will replace our internal class with MyExtraClass (and its BEM derivatives for elements and modifiers) the HTML generated by
    the library, you will need to provide all the CSS including functional css that drives visibility etc:
*/
<Collapsible className={{
    className: "MyExtraClass",
    replaceBaseClass: true
}} />

As an object as above but with a CSS Module provided to translate internally generated names to unique names that match your CSS

As above this can either be additional or replacement via adding the replaceBaseClass prop.

/*
    This will add the classname MyExtraClass using the CSS Module as a map to determine the correct unique classname
    to use based on the module map provided by your bundler.
*/
<Collapsible className={{
    className: "MyExtraClass",
    cssModule: styles
}} />

If you don't want to write the className as string into your React code and want keep a consistent usages of the CSS Modules in the normal styles.MyExtraClass syntax you can pass these in as per the below example and have the class generator do a lookup on the cssModule as to what the original class should be; this does need to loop over the keys of the cssModule so could become expensive if you have a very large cssModule as the class generation is assumed to be quick and is not memoised in the library.

<Collapsible className={{
    className: styles.MyExtraClass,
    cssModule: styles
}} />

By default if a class is missing from the override css module it is assumed it should be removed, otherwise non unique css names may be generated, if you do not wish this to occur and want to keep css names generated that do not match with the css module the retainMissingModuleClasses override prop can be used.

<Collapsible className={{
    className: styles.MyExtraClass,
    cssModule: styles,
    retainMissingModuleClasses: true
}} />

Development lifecycle of changes

DO NOT EVER UNDER ANY CIRCUMSTANCE MERGE DEVELOPMENT INTO STAGING OR MAIN

Development branch

Development is considered unstable, un-tested and un-approved. It may at any point be deleted and re-created based on Staging if the need occurs. It is important that you follow the below steps and not delete branches as they merge into development because of this.

If the CI process fails in merging code into this branch you should prioritise fixing it above any other task you have; if this blocks other developers you will be expected to revert your merge. Do not leave the branch in a broken state if you do not know how to fix it or do not have time to fix it just revert and have another go when you have time.

Do not merge into a branch if the CI is not currently passing.

Staging branch

Staging is the area where fully complete, approved and ready to release code lives awaiting a scheduled code release to production. Code that is not 100% ready to go at a moments notice should not be merged into this area; it should sit in JIRA's Validate stage until its ready to go. On merging to this branch it is safe to delete the feature branch as its no longer needed.

If the CI process fails in merging code into this branch you will be expected to IMMEDIATELY revert the merge unless a senior team member deems it an acceptable risk to allow you time to fix and push a fix into DEVELOPMENT and STAGING via the standard change process below; the senior team member should determine this risk based on how soon a known code release is expected, scope of the error, analysis of what has failed and how simple a fix should be; if a fix change is allowed instead of a revert they should work with you to accelerate the review and validation of the required change to STAGING ASAP.

Standard changes

To make a new change to this repo:

• Create a new branch off Staging.
  • This should be named feature/JIRA ticket number + an easy to read dash separated description based on the JIRA task name
  • e.g. feature/XACCEL-117-s3-bucket-infra
• Once your changes are ready for review:
  • Create a new Merge Request into DEVELOPMENT via the GitLab UI.
    • You will need to change the target branch to DEVELOPMENT
    • DO NOT set the branch to delete
    • DO NOT set the merge to squish
    • DO NOT merge this yourself, you need approval via the review process
  • Check the Merge Request CI Pipeline passes
    • You can further test your changes using the --dryRun title tag; see the CI section below for more info.
  • Put the JIRA ticket into Peer Review and have your changes reviewed by the team
• Once the Peer Review is passed:
  • Check the CI/CD process is currently passing in DEVELOPMENT
    • You can check this by navigating to the DEVELOPMENT branch in the GitLab UI and checking the latest commit has a green pipeline passed checkmark next to it
    • DO NOT merge into a broken branch as the branch may need to be revert back to the broken change; this will delete your code
  • Merge the Merge Request into DEVELOPMENT
  • Wait for the DEVELOPMENT CI/CD pipeline to pass, if it fails see the above section on the Development branch above
  • Create a new Merge Request into STAGING via the GitLab UI.
    • The target branch should default to STAGING
    • DO set the branch to delete
    • DO NOT set the merge to squish
    • DO NOT merge this yourself, you need approval via the review process
  • Put the JIRA ticket into Validate and have your changes reviewed
    • This is to Validate the changes to the artefact work in Matrix or the changes to the deployment process work etc
• Once the Validate is passed:
  • Leave the JIRA ticket in Validate until it is ready for release
  • Make notes in the JIRA ticket and Merge Request as to why this is not ready to be go immediately and under what circumstances it will be
• When the change is ready to release into production
  • Check the CI/CD process is currently passing in STAGING
    • DO NOT merge into a broken branch as the branch may need to be revert back to the broken change; this will delete your code
  • Ask a senior team member to perform the merge
  • Wait for the STAGING CI/CD pipeline to pass, if it fails see the above section on the Staging branch above
  • Move the JIRA to Done
• When a code release is ready to occur a senior team member will merge the whole of STAGING into MAIN

DO NOT EVER UNDER ANY CIRCUMSTANCE MERGE DEVELOPMENT INTO STAGING OR MAIN

Concurrent / dependent changes

If concurrent changes are required / have dependencies on each other but fall under separate tasks you will need to make an intermediatory branch, named based on the story or epic, which the two or more task feature branches can be merged into at will without review. This branch then should then be the one merged into DEVELOPMENT or STAGING as per the above process; this will require the multiple tasks to be ready for review and validation at the same time. Do not merge the intermediatory without all its contained change tasks being approved.

DO NOT EVER UNDER ANY CIRCUMSTANCE MERGE DEVELOPMENT INTO STAGING OR MAIN