Origami Frontend Components & Services

Create A New Origami Component - Part 8 Component Lifecycle

The “Create A New Origami Component” tutorial is split into eight parts and is intended to be followed sequentially from start to finish:

  1. Intro & Boilerplate
  2. Base Styles
  3. Themes & Brands
  4. Demos
  5. JavaScript
  6. Testing
  7. Documentation
  8. Component Lifecycle

In part eight we will learn how to publish our component to the Origami registry 🎉, and discuss the lifecycle of a published component.

We don’t actually want to publish an example component o-example. If you have been following along so far using o-example, rather than working on your own component that should actually be published, read this part of the tutorial as a reference only until you’re ready to publish a new component for real.

Source Control

The first step of publishing our component is to introduce source control.

All Origami components reside in a git repository with the same name as the component. It’s required that component repositories are stored remotely in one of our github.com organisations, for example the Financial-Times organisation. There are more details about source control in the origami specification.

Create a new git repository by running git init, and commit the boilerplate as an initial commit. For example:

git init
git add --all
git commit -m 'my o-example component'

Push To Github

The second step of publishing our component to the Origami Registry is to commit our work and push to a new Github repository under the Financial-Times organisation (or other supported Github organisation). There is a new Github repository tutorial which might be helpful if you have never created a Github repository before. Note Origami repositories are usually public and open-source unless there is a reason not to be (for example o-fonts-assets is private due to our font license).

You may then push this to your remote github.com repository, under the Financial-Times organisation or another supported Financial Times organisation.

You might have noticed a .github directory already. This directory configures Github to give us some nice features including:

There is also some manual Github configuration left to do. When your new component is pushed to Github update access in the Github settings of your repository. Grant these teams the following permissions:

Origami components use a tool called Dependabot to automatically update developer dependencies. The Dependabot Github user dependabot-preview must be allowed to push to the default branch if there are Github branch protections enabled. See the Github tutorial on how to allow Github users to push to protected branches.

The "dependabot-preview" bot user has access to push to the default, protected branch.

Github Actions

Earlier we saw that the obt init command creates a directory .github. It contains configuration for Github including a nested directory workflows which contains configuration for Github Actions.

Origami components use Github Actions for a number of helpful functions including:

To see these Github Actions in practise let’s release our component.

Initial Release

Lets release the first version our new component. This will display our component in the Origami Registry and send a Slack notification to origami-support.

Our first release will be 1.0.0 following the semver specification. Origami components do not release versions lower than 1.0.0 but you may choose to release a beta 1.0.0-beta.1 again following the semver specification.

Before we release, this is a good time to update the components support status in origami.json according to whether this release of the component will be experimental (the component is not ready for production use), or active (feature development ongoing, bug reports will be gratefully received and acted upon promptly), etc.

To release an Origami component create a git tag named after the semver version but beginning with a v e.g. v1.0.0. Create the tag either through the Github release interface or through the command line:

git tag v1.0.0
git push origin v1.0.0

Within a couple of minutes at most, your component should be visible in the Origami Registry and should be published to the NPM registry](https://www.npmjs.com/~the-ft) 🎉. If not you may want to confirm that the obt test and obt verify commands pass without error, check the output of the Github Actions under the ‘Actions” tab, or contact the Origami team for support in the #origami-support Slack channel.

Subsequent Releases

After the first release Origami components may be released automatically by applying one of the Origami labels release:patch, release:minor, or release:major to pull requests (see Github instructions on applying labels). When a pull request is merged with a release label a Github Action will create a new semver git tag according to which label was used. A comment on the pull request will let you know what version number was released.

This image shows a component pull request which has been merged and released. The `release:patch` label was first added to the pull request. It was then merged. A Github action responded to the release label on merge. It checked the latest release number `v8.1.1` and, as a patch release, calculated the next version should be `v8.1.2`. The Github action then created a new tag `v8.1.2` to release the new version and posted a comment on the pull request.

The semver specification documents what constitutes a major, minor, or patch release. There are also some Origami specific considerations to keep in mind when versioning a component. For example we may opt to release a major version of a component even with a compatible api if it includes drastic visual changes.

Component Lifecycle

As other teams may depend on Origami components its important to follow the semver specification when versioning components as discussed previously. It is also important to communicate upcoming changes. The Origami specification includes a section on the component lifecycle which includes guidance on how to manage existing components as they mature. The guidance includes how to communicate new releases, the deprecation of component features, and the deprecation of components which are no longer needed.

Wrapping Up

If you have followed along this far congratulations! Going forward the Origami specification is the most comprehensive resource to reference when working on Origami projects.

We hope this step-by-step tutorial has helped make you feel more able to contribute to Origami. Both in terms of creating new components, maintaining existing components, and influencing the direction of Origami as a whole.

If you have any questions, bug reports, or feature requests please contact the Origami team 😃. You can find the team on Slack in #origami-support.