# Contributing to Gemara

The project welcomes your contributions whether they be:

* reporting an [issue](https://github.com/gemaraproj/gemara/issues/new/choose)
* making a code contribution ([create a fork](https://github.com/gemaraproj/gemara/fork))
* updating our [docs](https://github.com/gemaraproj/gemara/blob/main/README.md)

## PR guidelines

All changes to the repository should be made via PR ([OSPS-AC-03](https://baseline.openssf.org/#osps-ac-03)).

PRs MUST meet the following criteria:

* Clear title that conforms to the [Conventional Commits spec](https://www.conventionalcommits.org/)
* Descriptive commit message
* DCO signoff (via `git commit -s` -- [OSPS-LE-01](https://baseline.openssf.org/#osps-le-01))
* All checks must pass ([OSPS-QA-04](https://baseline.openssf.org/#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](.github/workflows/ci.yml) 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.