How to update your downloaded components?

The answer to the question of updatability for Compony components is not a simple one to give. 

Therefor we will first explain the principle around which we built this solution. Next, will cover some good and some bad solutions around this principle. And finally we talk about how the current implementation of updatability of Compony looks like.

This blogpost is the fourth in a mini-series where we explore the different facets of updatability:

  1. The different update processes currently in existence.
  2. The side-effects of each of these update processes
  3. Inspecting Composer and NPM’s updatability.
  4. Updating Compony components. (This blogpost)

The sketchbook-principle #

We encourage you to work with the sketchbook-principle whenever you download a component from Compony.io. By this we mean that we encourage you to edit the code of that component directly.

This might seem unconventional, and also has quite a big impact on the rest of this blogpost. Because as soon as you edit the code you just downloaded, you can no longer download a newer version of that same component some time in the future. (Ref: the rule of untouchable code)

The problem of updatability #

A component that is downloaded from Compony, could consist any combination of HTML, Twig, images, CSS, Sass, Yaml, JavaScript and PHP.

If we want to download these components and also keep them updatable. Then we shouldn’t be editing the source code of these components. Otherwise we would be breaking the rule of untouchable code. (Ref: the rule of untouchable code)

So to illustrate with an example. Let’s say that we create 2 themes: compony_base and compony_sub. compony_sub would have compony_base as a base-theme. And In compony_base we would download all the components from the Compony platform. While at first, this sounds like an excellent way of keeping components updatable, we still can’t get around the principle of some languages being un-updatable.

Let’s continue our example more practically: what if you would want to do something super simple as overwriting a color of a component in the basetheme? Then in the subtheme you would need to add a CSS-file with some very simple CSS in it, for example: 

css3-full Created with Sketch.
my-component.css
.my-element {
  color: red;
}

But to follow the component-principle of always working with components, you would need to:

  • create a new component-folder for this CSS file to live in
  • create a libraries.yml file to link to this new CSS file
  • extend the .html.twig file from the base theme, so you can attach this tiny library to it

If this feels like over engineering to you, you felt right. This approach would only work if the component that you are overwriting actually has an .html.twig file to extend. But let’s assume you would go through the trouble of doing it this way, then theoretically, you would have an updatable component in the basetheme. 

But even if that were true, and you have an updatable component. Which sounds like a ton of work and a lot of complex fragility to overwrite 1 simple color. Then I would argue that the updatability of component is more of a risk than a value. Because let’s say that in 2 years time, you update that component, then it’s hard to imagine which update wouldn’t break your theming:

  • updates of the markup
  • functional JavaScript changes
  • CSS change s
  • CSS-specificity changes
  • libraries.yml change

To put in simple terms: it is more likely that an update will break your component than fixing it.

Possible, other bad solutions #

Compony could have guidelines that instruct component-maintainers to keep updates to their own components always non-breaking. 
But this would mean that we would be in the way of refactoring.

Limiting collaboration or innovation for our contributors would be highly ineffective and  frontend-unfriendly. As a platform, we could also say to our contributors: please don’t update your components in any meaningful way, otherwise people could break their projects by updating. But again as a platform for and by front-end developers, this feels very counter intuitive.

So let’s put it all together: front-end components are super difficult to keep updatable. Even if we find a system, almost every change we get by updating, will be a breaking change.

But what if we turn this question upside-down? What if the availability of an update, doesn’t mean you should do that update?

Introducing: partially updating #

If we go back to the kickstart-principle for components, and you edit the components directly where needed, Then we have little to no fragility, no complexity, and you got an incredibly fast kickstart to build your theme.

When you download a component from Compony.io, we give you a hidden way of version control! The component will contain a automatically generated hidden .component.yml file.  (Docs: .component.yml) This file lists all of the information at the time that you downloaded this component. 

While the contents of that file are quite long, the relevant bit for this blogpost is this part:

YAML Created with Sketch.
.component.yml
component:  
  ...
  repository:
    ...
    gitlab_project_id: '7511021'
    version_sha: ae7c929d9e3a8ca2122facc2170ad0b0b4dd54de
    diff_with_latest_version: 'https://gitlab.com/componies/flat-design/Core/status- 
 messages/compare/ae7c929d9e3a8ca2122facc2170ad0b0b4dd54de...master'
    ...

So if in 2 years time, you discover a bug in the JS of your form-component, you could check the diff_downloaded_and_latest_version url in this file. And see what changed in the component's repository since you've last downloaded it, to give you some hint to what your issue could be. (Example: diff with last commit)

Now let’s say that the component-contributor, changed some indentation in CSS and fixed a bug in JS. Then you could ignore the changes is CSS and only copy over over the changes you would want for your 2-year-old component to be fixed.

One of the advantages of this approach is that we don't cause subjective derailment on a component level. For example when the component contributor decided to change an animation, or effect.

Another advantage we avoid blind updating of un-updatable languages.

Published 26 July 2019
Updated 10 January 2020