---

name: ink-dev description: Use when contributing code to ink and needing repository-specific branching, local validation, PR, and CI conventions. allowed-tools: Bash Read Edit Write Grep Glob

ink-dev

Overview

Use this skill to follow the standard contributor workflow for the ink 2D rendering library.

Related: Use ink-release for nightly/stable release policy, gates, and hotfix handling.

This repository uses a PR-first flow even for solo development: work on branch, open PR, merge to master.

When to Use

Use when:

• starting a feature, bugfix, or refactor in this repo
• preparing a pull request to master
• checking what local commands to run before push
• preparing code for release readiness checks

Do not use when you need language-level coding patterns unrelated to repository workflow.

Branch Strategy

• Treat master as protected; use PRs instead of direct pushes.
• Feature branch: feat/<short-description>
• Bugfix branch: fix/<short-description>
• Refactor branch: refactor/<short-description>
• Docs branch: docs/<short-description>
• Chore/CI branch: chore/<short-description>
• Do not commit feature work directly on master.

Development Cycle

1. Create branch from latest master:

   git switch master
   git pull
   git switch -c feat/<name>
   

2. Commit with conventional prefixes:

   • <type>: <concise description>
   • Types: feat, fix, refactor, test, docs, chore, ci

3. Update README.md when API/behavior/build/release workflow changed.

4. Run local validation before push:

   # Format check (matches CI)
   find include src -name '*.hpp' -o -name '*.cpp' | xargs clang-format --dry-run -Werror
   
   # Build + test
   cmake -B build -DINK_BUILD_TESTS=ON -DINK_ENABLE_GL=OFF
   cmake --build build -j$(nproc)
   ctest --test-dir build --output-on-failure
   

5. Push branch and open PR to master:

   git push -u origin feat/<name>
   gh pr create --base master --title "<type>: <description>" --body "$(cat <<'EOF'
   ## Summary
   - <what changed and why>
   
   ## Test plan
   - [ ] Local `ctest` passes
   - [ ] Format check passes
   EOF
   )"
   

6. Wait for CI checks before merge.

7. Merge via GitHub (squash merge is the default convention).

Quick Reference

| Area | Current convention | |------|--------------------| | Target branch | master | | CI trigger | PR to master, push to master | | CI checks | Format, Build & Test (gcc/clang x Debug/Release), clang-tidy, Sanitizers | | Nightly trigger | schedule/manual in nightly.yml on default branch | | Stable release trigger | push tag v* | | Release outputs | CPU tarball, GL tarball, source tarball, GitHub Release notes |

Code Conventions

• C++17 with strict warnings (-Wall -Wextra -Wpedantic).
• Public headers live in include/ink/; implementation in src/.
• GPU renderer sources live in src/gpu/<api>/.
• New features include tests in tests/ (typically test_<component>.cpp).
• Tests use Google Test (TEST, EXPECT_EQ, and related assertions).
• When adding/removing a public header, keep include/ink/ink.hpp (umbrella header) in sync.
• When adding/removing source files, update CMakeLists.txt accordingly.

Common Mistakes

• Skipping local ctest and relying only on CI feedback.
• Skipping clang-format check locally — CI will reject unformatted code.
• Forgetting README updates when public behavior or usage changes.
• Using vague commit titles instead of typed prefixes.
• Adding a public header but forgetting to include it in ink.hpp or the CMake install list.
• Pushing release tags before the changelog PR is merged and release preflight passes.