Developer Guide

Prerequisites

Go 1.18+
Git

Clone the repository

You can clone the repository and get the main branch using the following command:

git clone https://github.com/oras-project/oras.git

Enter the oras directory:

cd oras

Building binary

Use make build to build all platform binaries to the bin/ directory.

Mac:

# builds to
# - bin/darwin/amd64/oras
# - bin/darwin/arm64/oras
make build-mac

# builds to bin/darwin/amd64/oras
make build-mac-amd64

# builds to bin/darwin/arm64/oras
make build-mac-arm64

Linux:

# builds to
# - bin/linux/arm64/oras
# - bin/linux/amd64/ora
# - bin/linux/arm/v7/orass
make build-linux

# builds to bin/linux/arm64/oras
make build-linux-arm64

# builds to bin/linux/amd64/oras
make build-linux-amd64

# builds to bin/linux/arm/v7/oras
make build-linux-arm-v7

Windows:

# builds to bin/windows/amd64/oras.exe
make build-windows

Cleaning workspace

To remove all files not manged by git, run make clean (be careful!)

Managing dependencies

Using Go Modules to manage dependencies.

To update or add new dependencies, run go get <package name>.

Release checklist

Note: this section needs a lot of love and automation 🙂

Make sure your GPG is available on GitHub at https://github.com/<username>.gpg. This can be added at https://github.com/settings/keys
If you haven't already, open PR to add your GPG key to the KEYS file (see file for instructions)
Look for any references to the current stable version, and replace with upcoming version. Open a PR with these changes, such as "prepare for
". Examples:
- https://github.com/oras-project/oras/blob/main/internal/version/version.go#L5
Make fresh clone the repo after all above steps are completed and merged. Create a new tag for the version prefixed with "v", for example: git tag v0.15.0. Push the tag directly to the repo, for example git push origin v0.15.0.
```
version=0.15.0
git tag v${version}
git push origin v${version}
```
Wait for GitHub Actions to complete successfully for both the release-ghcr and release-github pipelines
Download all of the artifacts uploaded to the new GitHub release locally (*checksums.txt, *darwin_amd64.tar.gz, *linux_armv7.tar.gz, *linux_arm64.tar.gz, *linux_amd64.tar.gz, *windows_amd64.zip).
Verify the checksum of the file, downloaded platform should pass the check:
```
shasum -c oras_${version}_checksums.txt
```
Run version command and make sure that version number and git commit digest is what you expect it to be (same as the commit used to create the tag). Example:
```
mkdir -p oras-bin/
tar -zxf oras_${version}_linux_amd64.tar.gz -C oras-bin
./oras-bin/oras version
```

Create armored GPG signatures (.asc) using the key in the KEYS file.

for file in `ls`; do
    gpg --armor --detach-sign $file
done

Validate the signatures. Not that the KEYS file should be imported with gpg --import KEYS. Run some form of the following (adapted from Linux project):
```
for file in `ls *.asc`; do
    gpg --verify $file
done
```
Click "Edit release" button on the release, and add the .asc files created in the previous step. Edit the release description for change logs and also add a note indicating your GPG key used to sign the artifacts. Example (replace with your fingerprint etc.):
```
## Notes

This release was signed with `E97F 9DA5 AE2E 39CF 48A1 42B7 852A 7470 A39F B81D` (@jdolitsky's GPG key) which can be found [here](https://github.com/jdolitsky.gpg).
```
Click "Publish Release" button to save. Double-check that the release contains a corresponding .asc file for each release artifact.
Consume beverage of choice.. you're done! Thanks for moving the project forward.
Oh yea, tell people about it in #oras

Some Comments

There is a large number of steps here, mostly manual. Here are some comments and/or thoughts on it.

Step 3: Editing files for stable version. I can see that in one place, say, README.md. But do we really have to edit the code? Could we not use build-time flags as in go build -ldflags="-X main.Version=foo" or similar?
Step 5: This is the heart of the release. Adding a tag triggers a github release and an image build pushed to GHCR.
Steps 6-12: These are all signing and verifying. Of course, it is possible that GH Actions built and released something other than what we thought, but we cannot counter every single possible risk. It still would be nice if we could automate this somehow.
Step 14:

From a documentation perspective, I would break this down into sections:

Prepare the release
Cut the release
Verify the release (hopefully automated)
Sign the release
Make available elsewhere (hopefully automated)

Once ready, this should be a doc in the project itself.

Library vs Utility

oras actually serves 2 purposes: library and utility. All of the above steps, except for the tag, are entirely about the utility.

For better or for worse, semver is tied up with both. As an example, the current issue with the go modules solely affects its inclusion as a library, but it is immediate. It can be fixed by cutting v0.15.0, and the downstream problems go away. yet cutting a release also means all of the above, which are far more complicated.

Last update: September 27, 2022