CONTRIBUTING.md

# Contributing

# Getting Started

[Install][bazelisk-install] `bazelisk` and run the tests:

```sh
$ bazelisk test //...
$ (cd e2e; bazelisk test //...)
```

[bazelisk-install]: https://github.com/bazelbuild/bazelisk?tab=readme-ov-file#installation

# Workflow

- Follow the [contributions guide] to be granted forking permissions.
- [Fork] the project
- Implement the change
- [Create merge request] from fork

# Upgrading Binaries

First off take a look at the cosmos repo for the new release and determine whether any
of the binaries which are in the sections with this text:
`# TODO: remove these when future versions make them available`
appear in the new release. If so remove them from their previous download section and either
uncomment or add them to the download binaries for the new release.

## Generating new SHAs

Next up you will need to replace the urls in the download_file invocations to point to the new release.

It should just be a find and replace of the version number for those urls.

You may also need to comment out the first url for these new downloads, so that they go to cosmos
rather than our internal gitlab package registry.

Then run following script in a POSIX shell:
```console
# Clear out all integrities
sed -i 's|"\([a-z0-9-].\+\)": "sha256.\+",|"\1": "",|g' MODULE.bazel
# Run a fetch and update integrity
for BINARY in $(rg --no-line-number '^ +"([a-z0-9-].+)": "",' -or '$1' MODULE.bazel); do
  INTEGRITY="$(bazelisk fetch @${BINARY}//:entrypoint 2>&1 | rg -o 'sha256-[^"]+')"
  echo "${BINARY}: ${INTEGRITY}"
  sed -i "s|\"${BINARY}\": \"\",|\"${BINARY}\": \"${INTEGRITY}\",|" MODULE.bazel
done
```

You should now have all the sha's generated for the new release, if there are any sha's that don't
appear then it's possible they are not in the current release. So you will need to add that to a
new `# <old version> downloads` section. Then comment out that binary from the new binaries
download target.

If at any point you want to re-generate these sha's you will need to run `bazel clean --expunge`
to clear out the cached downloads.

## Uploading a new Package to Gitlab

Finally once you're happy with the sha's that have been generated you want to upload these to the
internal gitlab package registry.

First of all you will want to modify the url's in
`upload/BUILD.bazel` to point to the new release version, and run this in a POSIX shell:

```console
# Upload all binaries
for TARGET in $(bazelisk query 'upload:*' | tail -n +2); do
    bazelisk run "${TARGET}"
done
```

Now you can check the package registry to ensure a new package entry is there for the new version.

If at this point there are no new versions, you may want to ensure that your `~/.netrc` file is
setup for access to gitlab using a personal access token, and try again.

Finally ensure all the gitlab package registry urls in `MODULE.bazel` are uncommented so that they
can be used as a mirror going forward.

## Confirming Correct SHA's
One final check you can do is to comment out all the external urls in `MODULE.bazel` for the new
cosmo version to ensure it only retrieves the packages from the Gitlab Package Registry.

Then run `bazel clean --expunge` before re-running the commands from [Generating new SHA's](#generating-new-shas) then you should have no change to the `MODULE.bazel` file, other than your commented out urls.


# Release

`semantic-release` performs automatic releases of the project.

Release channels for `alpha`, `beta` and `stable` releases are used.

The [upstream configuration usage guide][semrel-release-channels-usage] provides information on how to perform a
release.

[semrel-release-channels-usage]: https://gitlab.arm.com/semantic-release/config-release-channels/-/blob/main/README.md?ref_type=heads#usage
[contributions guide]: https://gitlab.arm.com/documentation/contributions#contributions
[Fork]: https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#create-a-fork
[Create merge request]: https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#merge-changes-back-upstream