1# Contributing to Gemara
 2
 3The project welcomes your contributions whether they be:
 4
 5* reporting an [issue](https://github.com/gemaraproj/gemara/issues/new/choose)
 6* making a code contribution ([create a fork](https://github.com/gemaraproj/gemara/fork))
 7* updating our [docs](https://github.com/gemaraproj/gemara/blob/main/README.md)
 8
 9## PR guidelines
10
11All changes to the repository should be made via PR ([OSPS-AC-03](https://baseline.openssf.org/#osps-ac-03)).
12
13PRs MUST meet the following criteria:
14
15* Clear title that conforms to the [Conventional Commits spec](https://www.conventionalcommits.org/)
16* Descriptive commit message
17* DCO signoff (via `git commit -s` -- [OSPS-LE-01](https://baseline.openssf.org/#osps-le-01))
18* All checks must pass ([OSPS-QA-04](https://baseline.openssf.org/#osps-qa-04))
19
20### Useful make tasks when making schema changes
21
22Make sure to update the `docs/schema-nav.yml`, after making any changes to the schemas in the layer.cue files
23For instance:
24You 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:
25```
26- title: "Layer N"
27    filename: "layer-N"
28    schemas:
29      - "SchemaA"
30      - "SchemaB"
31      - "SchemaC"
32      - newschema //new schema added
33```
34
35Use `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.
36
37### Adding a new artifact type
38
39Adding a new artifact type requires schema changes, test data, and documentation updates. Follow the checklist below.
40
41| **Step** | **Action**                                                                                    |
42|:---------|:----------------------------------------------------------------------------------------------|
43| 1        | Define the new `#YourArtifact` definition in the appropriate `layer-N.cue` file               |
44| 2        | Add `"YourArtifact"` to the `#ArtifactType` enum in `base.cue`                                |
45| 3        | Add new enum or alias types to `docs/schema-nav.yml` under the correct layer                  |
46| 4        | Create a valid test data file in `test/test-data/` (prefix with `good-`)                      |
47| 5        | Add positive and/or negative test cases to `test/schema_test.go`                              |
48| 6        | Run `cue vet -d '#YourArtifact' . test/test-data/good-your-artifact.yaml` to validate locally |
49| 7        | Run `cue fmt .` and `make cuefmtcheck` to verify formatting                                   |
50| 8        | Run `make lintcue` and `make test` to confirm all checks pass                                 |
51
52## Releases
53
54Releases are automatically created when a PR is merged into `main` with the `release` label. To trigger a release:
55
561. Add the `release` label to your PR before merging
572. Merge the PR into `main`
58
59The release workflow will automatically:
60- Create a GitHub release with the appropriate version tag
61- Generate release notes from the PR using release-drafter
62- Publish the CUE module to the central registry
63
64**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.