create/CONTRIBUTING.md

Contributing to Kindred Create

Kindred Create is maintained at git.kindred-systems.com/kindred/create. Contributions are submitted as pull requests against the main branch.

Getting started

git clone --recursive ssh://git@git.kindred-systems.com:2222/kindred/create.git
cd create
pixi run configure
pixi run build
pixi run freecad

See the README for full build instructions.

Branch and PR workflow

1. Create a feature branch from main:

   git checkout -b feat/my-feature main
   

2. Make your changes, commit with conventional commit messages (see below).
3. Push and open a pull request against main.
4. CI builds and tests run automatically on all PRs.

Commit messages

Use Conventional Commits:

Prefix	Purpose
feat:	New feature
fix:	Bug fix
chore:	Maintenance, dependencies
docs:	Documentation only
art:	Icons, theme, visual assets

Examples:

• feat: add datum point creation mode
• fix(gui): correct menu icon size on Wayland
• chore: update silo submodule

Code style

C/C++

Formatted with clang-format (config in .clang-format). Static analysis via clang-tidy (config in .clang-tidy).

Python

Formatted with black (100-character line length). Linted with pylint (config in .pylintrc).

Pre-commit hooks

pip install pre-commit
pre-commit install

This runs clang-format, black, and pylint automatically on staged files.

Submodules

Kindred Create uses git submodules for addon workbenches:

Submodule	Path	Repository
ztools	mods/ztools	git.kindred-systems.com/forbes/ztools
silo-mod	mods/silo	git.kindred-systems.com/kindred/silo-mod

To update a submodule:

cd mods/silo
git checkout main && git pull
cd ../..
git add mods/silo
git commit -m "chore: update silo submodule"

If you cloned without --recursive, initialize submodules with:

git submodule update --init --recursive

Theme and QSS changes

The Catppuccin Mocha theme has three QSS copies that must be kept in sync:

1. resources/preferences/KindredCreate/KindredCreate.qss (canonical)
2. src/Gui/Stylesheets/KindredCreate.qss
3. src/Gui/PreferencePacks/KindredCreate/KindredCreate.qss

When modifying the theme, apply changes to all three files. Note that the copies have intentional differences (e.g., tree branch rendering style), so do not blindly copy between them -- apply edits individually.

See KNOWN_ISSUES.md for the planned QSS consolidation.

Preference pack

Default preferences are defined in resources/preferences/KindredCreate/KindredCreate.cfg. This XML file uses FreeCAD's parameter format:

<FCParamGroup Name="GroupName">
  <FCBool Name="Setting" Value="1"/>
  <FCInt Name="Setting" Value="42"/>
  <FCText Name="Setting">value</FCText>
</FCParamGroup>

Changes here affect the out-of-box experience for all users.

CI/CD

• Build workflow (build.yml): Runs on every push to main and on PRs. Builds in Ubuntu 24.04 container, runs C++ and Python tests.
• Release workflow (release.yml): Triggered by v* tags. Builds AppImage and .deb packages.

See docs/CI_CD.md for full details.

Architecture

For an overview of the codebase structure, bootstrap flow, and design decisions, see:

• docs/ARCHITECTURE.md -- Bootstrap flow and source layout
• docs/COMPONENTS.md -- Feature inventory
• docs/INTEGRATION_PLAN.md -- Architecture layers and roadmap

License

All contributions must be compatible with LGPL-2.1-or-later.