Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
87 lines (60 loc) · 3.25 KB

CONTRIBUTING.md

File metadata and controls

87 lines (60 loc) · 3.25 KB

Contributing

Pull Requests

All pull requests should be made against the main branch from your own fork of the repository. Please ensure that your pull request includes a clear description of the changes made and all CI checks pass.

Linting & Formatting

golangci-lint should be used to lint this project. CI will automatically run this, but you can run linting locally by running:

make lint # requires docker/podman to be installed

IDE Formatting

It is recommended to have goimports installed locally and have your IDE set to auto-format on save. You can install it by running:

go install golang.org/x/tools/cmd/goimports@latest

For vscode users, you can set up your editor to use goimports for auto-formatting by adding the following to your workspace or user settings:

{
  ...
  "go.formatTool": "goimports"
}

For jetbrains users see https://www.jetbrains.com/help/go/integration-with-go-tools.html#goimports

Canonical Representation

The API normalizes certain identifiers (resource types, reporter types) to a canonical form to ensure consistent behavior:

  • Resource types: lowercase, / replaced with _.
  • Reporter types: lowercase

This normalization:

  • Prevents duplicate entries that differ only in casing (host vs Host or k8s_cluster vs K8s_Cluster)
  • Ensure case-insensitive lookups work correctly.
  • Maintains consistency across the API surface.

The canonical form is what gets stored and returned in response. This is acceptable because:

  1. It is considered part of the business logic and not presentation logic.
  2. It's applied consistently across all operations.
  3. It's optimized for simplicity. Assuming we're based on spicedb but also open to others.

Schema Changes

When making changes to schema configuration files in data/schema/, you must rebuild and commit both the resources tarball and schema cache. This ensures that schema changes are properly captured and consumable in deployments.

Required Steps for Schema Changes

  1. Make your changes to files in data/schema/resources/
  2. Rebuild the tarball and update deployment configs: 
    make build-schemas
  3. Regenerate the schema cache: 
    go run main.go preload-schema
  4. Stage and commit all schema changes and generated files: 
    git add data/schema/ resources.tar.gz schema_cache.json deploy/kessel-inventory-ephem.yaml
git commit -m "Update schema: <description of changes>"

Verification

Before pushing your PR, you can verify that your schema changes are properly synchronized:

./scripts/verify-schema-tarball.sh

This check is also enforced automatically in CI. PRs that modify schema files without updating the generated files will fail the Verify Schema Tarball check.

Why This Matters

  • resources.tar.gz: Used in production deployments as a ConfigMap. Schema changes must be reflected in the tarball to be available to running services.
  • schema_cache.json: A preloaded cache file for faster schema loading at runtime. Keeping it in sync prevents validation failures and performance issues.

If these files aren't updated, deployments may fail or exhibit runtime errors due to schema mismatches.