Developer Guide
Building binary
Use make build
to build all platform binaries to the bin/
directory.
Mac:
# builds to bin/darwin/amd64/oras
make build-mac
# builds to bin/darwin/arm64/oras
make build-mac-arm64
Linux:
# builds to bin/linux/amd64/oras
make build-linux
Linux ARM64:
# builds to bin/linux/arm64/oras
make build-linux-arm64
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
- https://github.com/oras-project/oras/blob/main/README.md
- In the repository settings, add values for the following secrets:
RELEASE_GITHUB_USER_TOKEN
- Your GitHub personal access token which will be used to add artifacts to the release page (note: you can/should delete this token after the release)RELEASE_GHCR_USER_NAME
- Your GitHub username, used to release container image to GHCRRELEASE_GHCR_USER_TOKEN
- Your GitHub personal access token, used to release container image to GHCR (note: you can/should delete this token after the release)
- 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.10.1
. Push the tag directly to the repo, for examplegit push origin v0.10.1
. - Wait for GitHub Actions to complete successfully for both the
release-ghcr
andrelease-github
pipelines - Download all of the artifacts uploaded to the new GitHub release locally (
*checksums.txt
,*darwin_amd64.tar.gz
,*linux_amd64.tar.gz
,*windows_amd64.tar.gz
). Create armored GPG signatures (.asc
) using the key in theKEYS
file.- TODO:
make fetch-dist sign
- TODO:
- Click "Edit release" button on the release, and add the
.asc
files created in the previous step. Also add a note to the release description indicating your GPG key was 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 "Update release" button to save. Double-check that the release contains a corresponding
.asc
file for each release artifact. - Download the release artifact and signature for your platform, as well as the checksum file and its signature.
- Verify the checksum of the file manually. It should match what is in
checksums.txt
. For example:$ shasum -a 256 oras_0.10.1_darwin_amd64.tar.gz
- Validate the signatures. Not that the
KEYS
file should be imported withgpg --import KEYS
. Run some form of the following (adapted from Linux project):$ function verify_signature { local filename="${1}" local num_goodlines=$(gpg --verify --status-fd=1 "${filename}" | grep -c -E '^\[GNUPG:\] (GOODSIG|VALIDSIG)') if [[ ${num_goodlines} -lt 2 ]]; then echo "Unable to verify the signature of ${filename}" return 1 fi echo "Verified the signature of ${filename}" } $ verify_signature oras_0.10.1_darwin_amd64.tar.gz.asc $ verify_signature oras_0.10.1_checksums.txt.asc
- Install this version of ORAS, and make sure that the version and git commit is what you expect it to be (same as the commit used to create the tag). Example:
$ mkdir -p oras-install/ $ tar -zxf oras_0.10.1_*.tar.gz -C oras-install/ $ mv oras-install/oras /usr/local/bin/ $ rm -rf oras_0.10.0_*.tar.gz oras-install/ $ /usr/local/bin/oras version Version: 0.10.0 Go version: go1.15.7 Git commit: 173c010570c48e4aa18ce186cae8cc812f8e8b6e Git tree state: clean
- Create a PR on fishworks/fish-food with the new ORAS version and checksums. This can be done by navigating to this file in your browser, and clicking the "Edit" button, making the changes and clicking "Propose changes", which will allow you to open a PR. You can also do this in your terminal/editor, of course.
- Consume beverage of choice.. you're done! Thanks for moving the project forward.
- Oh yea, tell people about it in
#oras
- goreleaser makes bad release notes... run the following to generate a better changelog:
git log --no-merges --pretty=format:'- %s %H (%aN)' ${PREVIOUS_RELEASE}..${RELEASE}
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 ingo build -ldflags="-X main.Version=foo"
or similar? - Step 4: use of personal tokens. We really should have a production token used to push releases out. We can discuss signing separately, but entering yours or my token in, to be used by Actions, and then removing it, is messy. It also means someone else could accidentally trigger with my token.
- Step 5: This is the heart of the release. Adding a tag triggers a github release and an image build pushed to GHCR.
- Step 5a: There are several steps in the GHCR push that probably could be simplfied down to a single one with the use of docker/build-push-action@v2
- 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 13: This is just verification, although it probably should be before steps 6-12 (verify before signing). Actually, is there any reason we cannot make this part of the GH release pipeline?
- Step 14: Got it. We should add homebrew, I suspect. Again, if we could automate this, it would be super.
- Step 15:
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.10.1, and the downstream problems go away. yet cutting a release also means all of the above, which are far more complicated.