Developer guide

Welcome to the developer guide of the Skirbi universe. This page exists to keep all the READMEs of each individual package clear of the boring bits that dictate software development.

Philosophy

As found in the Why Skirbi, Skirbi has the following philosophies:

The core principles of Skirbi are:

• YAGNI: 80/20% rule
• Stay in the light DOM
• Attributes are the API
• Components are one-shot compilers
• Components are resistant to morphing
• No build phase is needed
• Seperation of concerns are (strictly) enforced

But there are more. Mainly on the development side Skirbi differs from main stream Javascript development.

This document explains how Skirbi is developed and what rules dictate the project.

Development

Try to keep functions small and try not to depend on any outside functions. We aim to keep the dependency graph as small as possible. The use of esm is welcomed (well mandatory, let’s not kid ourselves) and writing tests is encouraged.

eslint

The ES Linting profile is flexible and does not try to enforce much. There is more than one way to do it (TIMTOWTDI).

Try to stay consistent, but forcing a programming style upon others is bad.

Easy things should be easy and hard things should be possible

This is another motto carried over from Perl. Skirbi lacks guard rails at times because it wants to give power users the tools to do the things they want to do in an easy way. If you want to shoot yourself in the foot: go ahead. Don’t blame us, blame yourself.

Typescript

This project does not write typescript. It is a layer on top of Javascript the project lead does not have interest in pursuing. It adds a build step, and complexity that isn’t needed in this project: Javascript in the browser is just strings, maybe integers and some nulls. Or “primitives” as JS developers will say. There are no objects, unless you do JSON.parse() which gives you a nice data structure. But again, no real objects.
Just ensure you have tests for your components and all is well in the world.

jsdoc

You can build the documentation by running npm run jsdoc.

Lock files

This project rejects lock files on a principle level. You can pin versions if you want reproducable builds on the consumer side of things. This project will always work with either latest or * or specific pins to version.

Gitlab or Codeberg

This project main location is found on Gitlab, a clone will be hosted on Codeberg.

Pull or merge requests

You can also mail me a patch series if you like. Your commits will not be squashed, so make proper commits. Document “the why” as much as the how. As we don’t do semantic versioning, the project doesn’t really care about conventional commits, you can add them or leave them out.

Code of Conduct

Be human

This means several things:

1. No personal attacks. It is not appropriate to make posts or comments that could be construed as personal attacks on individuals.
2. This project rejects bigotry – this project is woke, AF.
3. You can have a bad day, that’s ok too – touch some grass if you feel this way.

Semver

Skirbi does not adhere to semver and one should not rely on the version x.y.z notation to infer stability or reliability. Read the Changes file to see any updates a version may bring. The fact that a module sits at 0.x.z ranges does not indicate alpha or beta or even unstable associations. It is just a number and we started at 0.0.1.

In general the following hard guarantee will be given: We will not break your code. In case we do happen to cause breakage: we will fix it accordingly.

In case we foresee breaking changes we’ll add deprecation warnings. Giving you time to fix things before a breaking change will be introduced. When a change will be introduced is communicated in the Changes file. Security fixes may cause breakage at any given time without notice.

Skirbi packages are released by @opndev/rzilla, changes to package.json will be overridden. In addition to a little bit of promotion, this also means that version numbers are autoincremented at release time and bumped in all relevant files: Versioning for humans, not machines.