This project follows the fork and pull model.
The process:
- Fork the project to your own account
- Create a branch in your forked repository
- Push commit(s) to your branch
- Open a pull request targeting the
mainbranch of the upstream repository - Address any comments raised in the review. To update the pull request, don't add new commits with updates; instead amend your commit(s) and force push.
- Pull request can be approved by a Contributor (or Maintainer). Once at least one approve is received, a Maintainer can merge it.
CI is hosted on Github Actions. Currently it only includes basic build jobs for GNU/Linux, Windows, and a clang-format check. All three must pass in order to merge.
Any precompiled binaries uploaded to Github releases page are built using Github Actions.
Version tags should follow the format vX.Y.Z
Code must be cleanly formatted and cannot include any WIP leftovers, such as messy comments, debug prints, etc.
C code formatting is handled by clang-format. To format a file in-place:
clang-format -i $FILE
Alternatively --dry-run flag can be added to only print current style issues.
Note: checking code style with clang-format is a part of CI - there can be no warnings.
For automatic code style checks, see the pre-commit hook section.
A config file for clang-tidy is also present in the repository, however none of its checks are currently being
enforced.
Python/shell/CMake code style is currently not enforced.
All source files must start with a valid license header, which specifies license type and lists contributors with years in which they modified the file. When making changes to source files, authors should update the license header, adding/updating their line if necessary.
For automatic license header checks see the pre-commit hook section.
// SPDX-License-Identifier: GPL-3.0-only
//
// (c) $YEAR Author Name <[email protected]>
// (c) $YEAR-$YEAR Author Name <[email protected]>
# SPDX-License-Identifier: GPL-3.0-only
#
# (c) $YEAR Author Name <[email protected]>
# (c) $YEAR-$YEAR Author Name <[email protected]>
For shell scripts the interpreter directive line goes before the license header.
Contributors are strongly encouraged to enable a pre-commit hook, which automatically runs a few checks and aborts the
commit if any problems are found. Checks include C code formatting and license header validation. To enable the hook,
run
toolz/enable-pre-commit.sh.
Installed hook can be skipped with git commit --no-verify.
All resources (images, audio, json, etc.) must be located in the res directory. Note that everything inside res
is distributed under a different license than code (see res/LICENSE.txt).
In case of files that can be compressed/optimized without sacrificing quality, it is recommended to do so. For example,
for .svg files it is recommended to run them through scour.
Commits should be atomic. Whenever possible, don't mix two new features in one commit. When renaming/refactoring a large chunk of code, don't do it alongside other changes - rather split it off into a separate commit which is only renaming stuff. This way commits are way easier to understand and review.
Commits cannot break compilation, even if they are part of a bigger changeset. Code must compile (and scripts must execute) after every individual commit. There can't be any half-finished parts. However, if the change is part of a changeset, it doesn't strictly have to make sense logically - e.g. commit 1/2 could remove some feature which is actually being actively used, commit 2/2 could implement a similar feature replacing the original one.
All commits must include a non-empty commit message describing the change and providing other useful information.
Every commit message must be properly formatted. Only exceptions are commits made before 10-10-2023.
In general, the message format is loosely based on the one used in Linux Kernel.
Commit messages must be written in English, including proper grammar, spelling, punctuation, etc. Please make it understandable. Usage of a spell checker is recommended.
Line length limit is 75 characters. Only exceptions are links and tags.
Use imperative mood, e.g. make ::myMethod() return bananas, instead of
I changed ::myMethod() so it returns bananas or ::myMethod() returns bananas.
Commit message consists of three parts (described in detail in next sections):
- Title
- Description
- Tags and sign-off
The parts are separated by one empty newline.
First line of the message is the title. It should be short and concisely describe the whole change. Title must fit in one line.
Title contains a short identifier at the beginning, then a colon (:), then the actual title.
The identifier should point to the main part of the repository that is being changed. Identifiers in use:
foerr- most of the changes were done insrcdirectorystyle- code style refactors with no functional changestoolz- most of the changes were done intoolzdirectoryres- most of the changes were done inresorfontsdirectoriesbuild- changes related to the build system (CMake, dependencies)git- changes related to git (e.g..gitignoremodifications)github- changes related to Github actionsdocs- changes related to non-code documentation
It is encouraged to use words such as add, refactor, improve, or fix in the title.
Title example: toolz: refactor material importing logic
Description follows title (after one empty newline) and should make the bulk of the commit message. This is the place to explain the change in detail. It should contain information such as:
- What is the motivation for the change
- What improvements does the change make
- How does the code behave now
- How will the code behave after the change
- Are there any side effects or TODOs related to this subject that should be addressed in the future
It is encouraged to separate the description into short paragraphs, each dealing with separate aspect of the change.
If the change is small or trivial, the description doesn't have to be long, but it shouldn't be empty.
To add a link to the description, don't paste it straight into the text, as it would often make the line too long.
Instead, leave a reference mark ([$number], e.g. [1]) in the text, and paste the link at the end of description.
Example:
Description content which wants to link to some site [1] and then
continue on.
[1] https://example.com
This section follows description (after one empty newline) and contains specially formatted information. Each tag takes one line.
Please refer to Kernel contributing guide for detailed description of each tag. TLDR for most common ones:
Fixesis used to point that the commit fixes some other commit. It's usually used when the title contains thefixkeyword. Offending commit must be formatted as%h (\"%s\")with a 12 character SHA, e.g.Fixes: 1234567890ab ("foerr: sample commit")Co-developed-byis used to credit someone who helped prepare the change, e.g.Co-developed-by: User Name <[email protected]>Suggested-by,Reported-byare used for similar purposes asCo-developed-by
Last line after all the tags is always the sign-off, which can be automatically generated with
git commit -s. Example: Signed-off-by: User Name <[email protected]>. Sign-off must match commit author.
res: Fix toasters being unpickable
Currently the player can pick up objects such as lamps, fans, etc, but is
unable to pick up toasters, as reported in an user discussion [1]. Fix
that by setting a correct flag in items.json.
[1] https://example.com/some_discussion
Reported-by: Anon <[email protected]>
Fixes: aabbccddeeff ("foerr: Add the ability to pick up items")
Signed-off-by: User <[email protected]>
Project owner and collaborators reserve the right to have a final say in any decision related to the project. That being said, they must aim to listen to other contributors and users and ultimately take an action that is best for project goals.