# Contributing to Gemara

The project welcomes your contributions whether they be:

* reporting an [issue](https://github.com/ossf/gemara/issues/new/choose)
* making a code contribution ([create a fork](https://github.com/ossf/gemara/fork))
* updating our [docs](https://github.com/ossf/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

Use `cue fmt ./schemas` 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. Use `make cuegen` to regenerate `go` types based on your changes.

### Generated Code

This project contains both schema and Go code. Some of that go, specifically the contents of [layer2/generated_types.go](layer2/generated_types.go) is generated by `make cuegen` based on the `cue` schema contents in [schemas/](/schemas).

If you change any schema, ensure you run `make cuegen` and commit the result of that generation as part of your PR. If you forget to do this, the [CI workflow](.github/workflows/ci.yml) will fail and remind you.

### Validate OSCAL Artifacts

This project supports the generation of OSCAL [Control Layer](https://pages.nist.gov/OSCAL/learn/concepts/layer/control/) artifacts.

To validate this functionality using `gemara` test artifacts, perform the following steps:

1. Install the `oscal-cli`. Instructions on installation are available in this [guide](https://github.com/usnistgov/oscal-cli?tab=readme-ov-file#installing).
2. Generate OSCAL test data by running `make oscalgenerate`
3. Use the `oscal-cli` to validate the generated artifacts under the `artifacts` directory.

Example: `oscal-cli catalog validate ./artifacts/catalog.json `