Contributing to Gemara

The project welcomes your contributions whether they be:

• reporting an issue
• making a code contribution (create a fork)
• updating our docs

PR guidelines

All changes to the repository should be made via PR (OSPS-AC-03).

PRs MUST meet the following criteria:

• Clear title that conforms to the Conventional Commits spec
• Descriptive commit message
• DCO signoff (via git commit -s -- OSPS-LE-01)
• All checks must pass (OSPS-QA-04)

Useful make tasks when making schema changes

Make sure to update the docs/schema-nav.yml, after making any changes to the schemas in the layer.cue files For instance: You have added a new schema 'newschema' in layerN.cue( where N is a number from 1 - 7), the docs/schema-nav.yml should look like:

- title: "Layer N"
    filename: "layer-N"
    schemas:
      - "SchemaA"
      - "SchemaB"
      - "SchemaC"
      - newschema //new schema added

Use cue fmt . and make cuefmtcheck to ensure proper formatting and make lintcue to validate the syntax of your changes. If you forget to do this before opening a PR and your changes are invalid, the CI workflow will fail and alert you.

Adding a new artifact type

Adding a new artifact type requires schema changes, test data, and documentation updates. Follow the checklist below.

Step	Action
1	Define the new #YourArtifact definition in the appropriate layer-N.cue file
2	Add "YourArtifact" to the #ArtifactType enum in base.cue
3	Add new enum or alias types to docs/schema-nav.yml under the correct layer
4	Create a valid test data file in test/test-data/ (prefix with good-)
5	Add positive and/or negative test cases to test/schema_test.go
6	Run cue vet -d '#YourArtifact' . test/test-data/good-your-artifact.yaml to validate locally
7	Run cue fmt . and make cuefmtcheck to verify formatting
8	Run make lintcue and make test to confirm all checks pass

Releases

Releases are automatically created when a PR is merged into main with the release label. To trigger a release:

1. Add the release label to your PR before merging
2. Merge the PR into main

The release workflow will automatically:

• Create a GitHub release with the appropriate version tag
• Generate release notes from the PR using release-drafter
• Publish the CUE module to the central registry

Note: Only PRs merged into main with the release label will trigger a release. Other labels (such as breaking, feature, or vuln) will not trigger releases.