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:

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:

ISSUE_TEMPLATE.md: The contents of this file are used to provide a template when opening a new Github issue. It helps users report bugs or provide feedback by prompting for useful information.
CODEOWNERS: defines individuals or teams to automatically assign to new Github issues or pull requests (see the Github code owners documentation).
workflows/*: the workflows directory configures a number of Github Actions which will automate component testing and release. We’ll look at some of these shortly.

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-read-only: read - required, for a team of helpful Origami bots
@origami-collaborators: write - so engineers from other teams may contribute
@origami-core: admin - so Origami team members can help to the fullest

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:

Synchronise github labels for issues and pull requests (learn about Github labels).
Run component tests when new commits are made to a pull request.
Automatically release minor and patch updates to developer dependencies given tests pass.
Add a semver git tag to release a component when a pull request with a release label is merged.
Build and publish an NPM package when a release is made with a git tag, so Origami components may be included via Bower or NPM

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.