Skip to main content

Key Git Principles

This document provides an overview of the fundamental principles we follow within our GitHub repositories.

Be kind!โ€‹

Yes, it sounds silly, but it's probably the most important principle of them all. Open-Source contributions are, in 99 % of the cases, side-projects. Open-Source is an excellent principle, and you can be proud to contribute to the pool of open-source software. Don't use comments like "RTFM!" in this community.

Contributing to an open-source project is scary enough already: Your code is available for the world to see (and judge). But you do need and should appreciate these contributions. Therefore, if the best you can do is post some discouraging comment about why something is "just bad", keep it to yourself!

Constructive criticism is appreciated, but you should always combine it with explicit appreciation for the time the other person has taken.

caution

Online comments often get misinterpreted in the worst possible way (as it is, unfortunately, also the safest way for the person receiving them). Unfortunately, misunderstandings happen far sooner than you might think, especially when they begin to cross cultures and languages. So please keep that in mind when writing comments.

Keep main instantly releasableโ€‹

Always keep the state of the main branch releasable. As this project implements automation in such a way that pre-configured tools automatically release the correct kind of semantic release on the press of a button (which, theoretically, anyone should be able to press). Pressing that button should result in a good release whenever it gets pressed.

info

Keeping main instantly releasable enables this project to release changes in no time, if needed or wanted

One branch per changeโ€‹

Don't try to put more than one kind of change (bug fix, feature, or anything else) into a single branch, except if explicitly advised to do so by one of the maintainers. Having one branch per change ensures the ability to correctly merge it with a conventional commit message, should the need arise, and guarantees correct generation of release notes and changelog in releases.

Use the conventional commit commit-name systemโ€‹

The conventional commit system lets this project generate release notes and the required semantic type of release at the push of a button without having to think about it (sticking with the instantly releasable theme).

So don't worry if you might do something wrong. Even the "worst" of mistakes a maintainer can fix. Either when merging your Pull Request (by squashing the commits with a new commit message) or another way.

Choose the correct conventional commit type ยป./conventional-commit-types

Don't be afraid to askโ€‹

While everyone claims that JavaScript and Java are easy compared to other languages (that may or may not be the case), what this project uses is a rather complex and a large ecosystem with plenty of tooling.

While, at its core, it's still "easy old JS or Java," a lot might not be apparent immediately. So always feel free to ask about anything. If someone isn't kind in their response, they don't belong into this project, and in 99 % of the cases, you'll get a kind reply from someone else.

Remember: You're not the first to feel this way (and even the most experienced of developers sometimes have to ask someone else to find out they've forgotten to hit Compile ๐Ÿ˜‰)