Developer Guide

Prerequisites

• Go 1.20+
• Git
• Make

Clone the repository

Once you have the basic tools installed, fork the repository on GitHub and clone it locally:

MY_GITHUB_NAME="my-name"
git clone git@github.com:${MY_GITHUB_NAME}/oras.git
cd oras

Building binary

To compile and run the tests, just run the make command. 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

info

This section needs a lot of love and automation 🙂

1. Make sure your GPG is available on GitHub at https://github.com/<username>.gpg. This can be added at https://github.com/settings/keys

2. If you haven't already, open PR to add your GPG key to the KEYS file (see file for instructions)

3. Open a release PR to

   • Build with latest golang: replace go version of binary and image to latest stable one
   • Update oras version: replace current stable version with upcoming release version

4. After the release PR got merged, create an issue to call for vote on cutting off a release branch named release-<major>.<minor> based on the version update commit.

5. Make fresh clone of the repo after all above steps are completed. Create a new tag for the version prefixed with "v" and push the tag directly to the repo.

   version=1.0.0
   git tag v${version}
   git push origin v${version}

6. Wait for GitHub Actions to complete successfully for both the release-ghcr and release-github pipelines

7. 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).

8. Verify the checksum of the file, downloaded platform should pass the check:

   shasum -c oras_${version}_checksums.txt

9. 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

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

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

11. 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

12. 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 `BE6F A8DD A48D 4C23 0091 A0A9 276D 8A72 4CE1 C704` (@qweeah's GPG key) which can be found [here](https://github.com/qweeah.gpg).

13. Click "Publish Release" button to save. Double-check that the release contains a corresponding .asc file for each release artifact.

14. Consume beverage of choice.. you're done! Thanks for moving the project forward.

15. 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 6: This is the heart of the release. Adding a tag triggers a github release and an image build pushed to GHCR.
• Steps 7-13: 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 15: 🍺

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

1. Prepare the release
2. Cut the release
3. Verify the release (hopefully automated)
4. Sign the release
5. 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 v1.0.0, and the downstream problems go away. yet cutting a release also means all of the above, which are far more complicated.