Introduction to Open Source Development

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.

Please read through the following notes carefully and ask the core team if you have any questions before starting any work; doing so will likely save time and rework caused by not fully appreciating the processes and requirements being signed up to prior to commencing.

Before starting work

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.

If it sounds like there's a plan, you'll need to raise a ticket on our Framework Jira board. The ticket template contains all you'll need to add the required information and get started, so clone it (with attachments!) and fill it in as fully as you can. The core team will triage the ticket and look at any prep work you may already have done, then make a decision on whether your component is suitable for inclusion; if it is, we'll move the ticket into 'In development' on the Jira board so you can get started with fleshing out UX and design. The core team will be available for consultation and to review things as you go along, but 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.

The tickets on the Framework board should only be moved by the core team (with the exception of the one instance outlined later), so it is important that the creating team adds tickets to their own Jira/Kanban boards in order to properly track the progress of their own work. Linking your tickets to the one on the Framework board would be advantageous, as it will give both you and the core team visibility of where in the process a component's progress currently lies.

Developing the component

Before starting to build a new component, developers must ensure that their laptops are correctly set up for developing with the Framework and that they are aware of basic Framework standards and practices. To do this, follow the directions starting on the 'creating an open source component' page and continuing through the 'How to set up your laptop for the Framework' and 'How to develop for the Framework' guides available in the fw-standards repository. All development work should meet Abeille Assurances' coding standards, which the Framework's own standards reflect and enhance.

Once set up, additional support is available in the fw-standards repository's .doc folder 'How To...' guides for 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.

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, so be sure to follow the relevant guidance on creating a new extension prior to creating the actual component.

Full details are available on the creating an open source component' page.

Adding documentation

All new components will need appropriate documentation, including the main Element Library page (including the usage guidelines), an archive page and an appropriate entry in the Framework release log.

The usage guidelines should be supplied to the developer by the team's designers, and should follow the standard Framework template. Not all of the sections will be applicable, but please mark those which do not apply as ‘N/A’ to confirmation that they have been considered and dismissed rather than just not been completed.

The template and example are both attached to the Framework's standard JIRA template story, so will be available once your ticket has been created.

Preparing for inclusion

Once the component code is ready for review, a pull request should be created and the Jira ticket on the Framework board moved to 'OS Submission'. The core team will then pick and review the code, and also ensure that all the required documentation and so on has been completed ready for the component to be released; at this stage, the ticket will appear in the 'OS QA' column.

Once the reviews have taken place and any ensuing feedback responded to, the ticket will move to 'Awaiting release' prior to inclusion in the next Framework release. New components will be introduced to attendees at the appropriate Framework sprint review, and also included in the release newsletter. At this point the Jira ticket will be marked as 'Done'.

After release

A team's involvement with a component does not end with its release to Framework consumers. Instead, responsibility for any fixes, enhancements and so on remain with the creating team unless an agreement is reached with another team to pass control of a component so that additional features can be added which are outside of the scope or requirements of the creating team. These responsibilities will include making any code changes required to ensure a component is compliant with changes to WCAG criteria, and is ready for inclusion in subsequent major releases of the Framework. In the latter case, the Framework core team will endeavour to support where possible, but the onus for completion of any recommended work will lie with the owning team.

Should a team wish to make enhancements or additions to their own open-source component, they should contact the Framework core team to detail their proposals, and the process should follow a similar pattern to a new component creation as detailed above.

Should a team wish to make enhancements or additions to an existing open-source component which they did not create, the new team should contact not only the Framework core team, but also the existing owners of the component, whose name will be listed in the header area on the component page; that entry can be checked against the list on the Framework OS Component Owners confluence page to find more complete contact details.

Further questions

If you have any further questions regarding open source components or their creation, please contact the Framework core team.