Skip to content

Component Contribution Guide

This guide covers contributing code and design to any component of the Naftiko Fleet. For contributing documentation, see Documentation Guide. For authoring tutorials, see Tutorial Authoring.

Repository map

Component Repository
Ikanos engine github.com/naftiko/ikanos
Polychro linter github.com/naftiko/polychro
Fleet (Crafter, Warden, Skipper) github.com/naftiko/fleet

Each component has its own CONTRIBUTING.md and AGENTS.md covering repo-specific conventions. This page captures the cross-cutting rules.

Before you start

  1. Check for an existing issue. If a similar one is open, comment there rather than opening a duplicate.
  2. For features: open an issue or design discussion first. Direct PRs without prior alignment may be closed.
  3. For bug fixes: an issue is helpful but not required for small fixes.

Development environment

Component Toolchain
Ikanos Java 21 LTS, Maven 3.9+
Polychro Java 21 LTS, Maven 3.9+, GraalVM 23 for native image builds
Polychro Action Node.js 20+, TypeScript
Documentation Zensical (pip install zensical)

All Java components use the Restlet-style Maven structure under a root pom.xml with module sub-projects.

Code conventions

Java

  • Java 21 LTS — use record, pattern matching, sealed types, etc.
  • Spotless format enforced via Maven (mvn spotless:apply)
  • Null analysis via JDT — see memory/repo/ikanos-jdt-null-analysis.md
  • Tests with JUnit 5 + AssertJ

YAML schemas

  • Schema files live under src/main/resources/schemas/
  • Schema changes require a corresponding polychro:governance rule addition or update

Commit messages

  • Conventional Commits format: feat:, fix:, docs:, refactor:, test:, chore:
  • Reference issue in the body: Fixes #123 or Closes #123

Submitting changes

  1. Fork the repository
  2. Create a topic branch off main
  3. Make your changes with tests
  4. Run the local checks: 
    mvn verify
polychro lint .            # for capability/schema changes
  5. Open a PR against main
  6. CI runs unit tests, integration tests, native image builds (Polychro), and Polychro linting against any YAML changes
  7. A reviewer merges after approval and clean CI

Schema version policy

While in alpha (1.0.0-alpha*), schema versions can introduce breaking changes between alphas, but each alpha is internally stable. Breaking changes require:

  • An entry in the component's CHANGELOG.md
  • A migration note in the affected pages
  • A polychro:ai-safety rule that catches the old shape, if feasible

License

By contributing, you agree that your contributions will be licensed under one of:

  • The Apache License 2.0 — for contributions to Ikanos and Polychro, which are released as standalone OSS projects.
  • The Naftiko Fleet Freeware EULA — for contributions to the Community-edition Fleet bundle (Shipyard, Crafter, Warden, Skipper baselines, VS Code extension, Backstage templates).
  • The Naftiko Commercial License — for contributions to Standard- or Enterprise-edition premium features.

See Fleet → License for the full three-license picture.