Creating an Open Source Component

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.

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.

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.

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.

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.