# Contributing to Kindred Create

Kindred Create is maintained at [git.kindred-systems.com/kindred/create](https://git.kindred-systems.com/kindred/create). Contributions are submitted as pull requests against the `main` branch.

## Getting started

```bash
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](README.md) for full build instructions.

## Branch and PR workflow

1. Create a feature branch from `main`:
   ```bash
   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](https://www.conventionalcommits.org/):

| 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

```bash
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 |
|-----------|------|------------|
| silo-mod | `mods/silo` | `git.kindred-systems.com/kindred/silo-mod` |
| gears | `mods/gears` | `git.kindred-systems.com/kindred/gears` |
| datums | `mods/datums` | `git.kindred-systems.com/kindred/datums` |
| solver | `mods/solver` | `git.kindred-systems.com/kindred/solver` |

To update a submodule:

```bash
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:

```bash
git submodule update --init --recursive
```

## Theme and QSS changes

The Catppuccin Mocha theme canonical source is `src/Gui/Stylesheets/KindredCreate.qss`. The copy at `src/Gui/PreferencePacks/KindredCreate/KindredCreate.qss` is **generated at build time** via `configure_file()` in CMake -- do not edit it directly.

Only edit `src/Gui/Stylesheets/KindredCreate.qss` when modifying the theme.

## Preference pack

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

```xml
<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](docs/CI_CD.md) for full details.

## Architecture

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

- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) -- Bootstrap flow and source layout
- [docs/COMPONENTS.md](docs/COMPONENTS.md) -- Feature inventory
- [docs/INTEGRATION_PLAN.md](docs/INTEGRATION_PLAN.md) -- Architecture layers and roadmap

## License

All contributions must be compatible with [LGPL-2.1-or-later](LICENSE).