Open source development for Framework
The model, processes and component creation
As of v5.0.0, the Framework supports open source components being created and stored alongside core modules. There are various processes to support this, all of which must be committed to and adhered to prior to the actual build commencing. Here is everything you need to know.
The open source model: how does it work?
The introduction of the open source model enables teams to design and develop Framework compliant components and patterns for use in digital products. In consultation with the core Framework team, this in turn has multiple benefits in place of the current centralised model.
Current model: Centralised process
It has proven value preserving principles and maintaining quality. In addition, the refinement of the process and retention of knowledge have been particularly useful. However, it has notable drawbacks in terms of visibility to all and potential bottlenecks with production of new patterns and components. The lack of autonomy is also a notable issue amongst others.
- Preserve principles
- Maintain quality
- Refine process
- Retain knowledge
- Visibility to all
- Prodcution bottleneck
- Single point fo failure
- Team size
- Lack of autonomy for others
All things considered, the centralised model is not optimised for ways of working going forward and is being phased out.
Framework V5 has migrated to:
New model: Open source process
With an increased relevance and ability to self serve, the open source model will have numerous immediate and future benefits. With no barrier to entry and a shared set of principles this means a greater spread of knowledge and improved collaboration. Naturally quality assurance will be an area for focus, however despite the associated learning curve, it ensures a more robust and accessible design system for all.
- Increased relevance
- Ability to self-serve
- No barrier to entry
- Shared principles
- Greater spread of knowledge
- Encourages collaboration
- Quality assurance
- Learning curve
The open source process: how will it help?
The open source process is designed to empower teams to create Framework-level components for inclusion in a library which is available company-wide.
It allows rapid development of components and variants which offer functionality not currently available, benefiting not only the requesting team, but also the wider Abeille Assurances community, helping to improve journeys and experiences across our platforms.
-
Common issue 1
“I can't add a new component quickly...”
Addresses existing difficulties with quickly adding a new component to the Framework for product delivery.
- Reduce dependency and bottleneck on core team
- Saving money and democratising delivery
-
Common issue 2
“Creates design and technical debt...”
Helps to eliminate both design and technical debt when creating the right solution for the customer
- Breed best practice design, code and accessibility standards
- Shared confidence and responsibility
Open source requirement flow
The requirement flow for open source is a series of steps to ensure a complete and robust solution ready for global usage as part of Abeille Assurances' digital products and services.
Between the product team/individual raising raising the request through to being added into the Framework library, the below process chart helps to visualise what this looks like and the relevant key areas for consideration:
Open source submission governance
The open source submission process is intended to be collaborative between the project team and the FW core team where applicable. It caters for ensuring all requirements are captured and documented in full as part of Framework compliance and consumption.
The below process chart helps to visualise what this looks like between the contributor, Framework reviewer and relevant automated or manual checks:
Developing for open source
If you've got an idea for a new component, the first thing to do is have an informal chat with the Framework core team to float the idea and to check nothing else similar already exists or is in development (or planned) elsewhere in the business. We may need to see some preliminary designs and UX justification, but that only needs to be outlines at this stage, enough to help sell the idea.
Component creation: a developer's guide
Before starting to build a new component, developers need to ensure that their laptop is correctly set up for developing with the Framework and that they are aware of basic Framework standards and practices.
Once you have access to the fw-standards repository, additional support is available in the .doc folder ‘How To guides’ for various topics including helping to resolve issues with Git, explaining how to write and run unit and integration tests and maintaining your laptop setup going forwards.
-
Step 1
Extension creation
Most open source components will need to exist within their own extension, as they will not be included with the Framework core and therefore will be unable to form part of an existing extension. If you are creating a set of components for a particular purpose or journey, then there may well be merit in containing all of them within the same extension, so that the required styles are all loaded together. Further information about this is available in the Open Source section in the .doc folder.
-
Step 2
Skeleton component creation
An automated Gulp process has been set up to facilitate the creation of a component skeleton containing a configuration file and the majority of the individual files which will be needed for the component to be built and included in the Framework. These include CSS, JavaScript, test harness pages, documentation pages and basic unit and integration tests. Some of these files will require more customisation than others, but all require some manual input before they can be used.
-
Step 3
Component documentation
The documentation for each component consists of a main page and an archive page.
The main page contains tabs for Design and Code, both of which should be completed. The information for the design tab, including the component introduction and usage guidelines, will be supplied by a team's UX/VD resource, and will normally only require the developer to add an example (or examples, if the component has multiple variants).
The Code tab contains further notes for developers, which should include any specific requirements, information on how to use different variants, locale settings and so on. An Extension component block will automatically be added by the Gulp buildComponent process giving instructions on how to include the relevant extension CSS file.
-
Step 4
Preparing for inclusion
Once the component code is ready for review, head to the fw-standards repository on ADO and create a pull request from the component feature branch to the latest version release (eg, release/v530).
The Framework core team will review the work and feed back any comments/suggestions/etc as necessary before the work is merged in, and will then inform you when your component reaches the dev environment so that you can properly view and test it prior to release.
At this point, the devlopment work is done, and the rest of the process will revert to admin and promotion, which will be completed via the Jira ticket on the Framework open source Kanban board.
Introduction: the step-by-step process
Once your set up is complete you are able to build for the Framework. Here are the six steps to create and submit a new component via the open source model:
-
Step 1
Talk to us
If you've got an idea for a new component, have a chat with us to float the idea and to check nothing similar already exists or is in development elsewhere in the business.
It’d help to see some preliminary designs and UX justification, but that only needs to be outlines at this stage, enough to help sell the idea.
-
Step 2
Raise a ticket on our Jira board
The core team will be available for consultation and to review things as you go along.
Once everyone's happy and the designs have been signed off by the relevant Design Leads (your team's lead and the Framework Lead), then you'll be ready to start building.
-
Step 3
Prepare for build
The core team will be available for consultation and to review things as you go along.
Once everyone's happy and the designs have been signed off by the relevant Design Leads (your team's lead and the Framework Lead), then you'll be ready to start building.
-
Step 4
Start building
Once your developers have their laptops set up for developing with the Framework with the required repository access permissions, they can get going.
Additional help is available in the repo's how-to guides for topics including resolving issues with Git, explaining how to write and run unit and integration tests, and maintaining laptop setups going forwards.
-
Step 5
The devil is in the detail
All new components will need appropriate documentation.
These include the main Element Library page (including the usage guidelines), an archive page and an appropriate entry in the Framework release log.
-
Step 6
Prepare for inclusion
Once the component code is ready for review, a pull request should be created.
We’ll review the code, and also ensure that all the required documentation and so on has been completed ready for the component to be released.
What happens next?
-
Step 1 of 3
Good to go!
Once reviews have taken place and feedback has been actioned, the component will be set for the next Framework release.
It'll be introduced to attendees at the appropriate Framework sprint review, and also included in the release newsletter.
-
Step 2 of 3
They think it's all over...
A team's involvement with a component does not end with its release to Framework consumers. .
Responsibility for fixes, enhancements and adaptations remain with the creating team. This is to ensure continued compliance with WCAG criteria and so on. We'll support where we can with the onus for completion of any recommended work remaining with the owning team.
-
Step 3 of 3
...it is now!
If you wish to make enhancements or additions to your own open-source component going forward, let us know.
The process should follow a similar pattern to a new component creation.
Top tip: enhancements or additions
Should a team wish to make enhancements or additions to an existing open-source component which they didn't create, the new team should not only contact us, but also reach out to the existing owners of the component to make sure they’re also good with any proposals.
The Framework core team
Our core team consists of of process leads, designers and developers, based in both Bois-Colombes, FRANCE. Feel free to contact someone within your respective domain if that is preferred:
-
Claire PAUMLAZ
Product owner
-
Romain GILBERT
Visual developer - Technical lead for DESY