README

Releasing instructions

earthly

• Make sure you have access to the earthly-technologies organization secrets.
  bashCopy

  ./earthly secrets --org earthly-technologies --project core ls
  

• Choose the next release tag.
  bashCopy

  export RELEASE_TAG="v..."
  

• Is it a pre-release?
  bashCopy

  export PRERELEASE="true-or-false"
  

• Make sure you are on main
  bashCopy

  git checkout main && git pull
  

• Update the CHANGELOG.md with the corresponding release notes and open a PR
  • Use a comparison such as https://github.com/earthly/earthly/compare/v0.8.13...main (replace the versions in the URL with the previously released version) or a tool such as gitk (aka git-gui) to see which PRs will go into this release.
• Make sure that main build is green for all platforms (check build status for the latest commit on GitHub).
• Make sure the following build status are green:

  Platform	Status
  MacOS (x86)
  MacOS (M1)

• Run
  bashCopy

  cd release
  env -i HOME="$HOME" PATH="$PATH" SSH_AUTH_SOCK="$SSH_AUTH_SOCK" RELEASE_TAG="$RELEASE_TAG" USER="$USER" PRERELEASE="$PRERELEASE" ./release.sh
  

• Wait for the Merge main to docs-0.8 on New Earthly Release workflow to complete; this workflow automatically merges main into docs-0.8. You can watch for it here: In case the workflow fails the manual process is:
  shellCopy

    git checkout docs-0.8 && git pull && git merge main && git push
  

• Updating the Earthly version in our docs: Renovate will open a PR targeting docs-0.8 branch to update all docs as soon as a new release is available in this repo which you should then review & merge (An example PR can be found here).
• Merge docs-0.8 into main.
  shellCopy

    git checkout main && git merge docs-0.8 && git push
  

  • Note: If you don't have permissions to push directly to main branch, do the following:
    • git checkout -b soon-to-be-main && git push origin soon-to-be-main
    • Open a PR against the new branch and get it approved; IMPORTANT: don't squash-merge via github
    • Once all (required) checks pass, try pushing the branch again: git checkout main && git push

• Wait for the Check Docs for Broken Links workflow to complete; this workflow validates https://docs.earthly.dev does not contain any broken links. You can watch for it here:
• Verify the Homebrew release job has successfully run and has merged the new release-v... branch into main.
• Copy the release notes you have written before and paste them in the Earthly Community slack channel #announcements, together with a link to the release's GitHub page. If you have Slack markdown editing activated, you can copy the markdown version of the text.

One-Time (clear this section when done during release)

• Add new one-time items here.

Performing a test release

To perform a test release to a personal repo, first:

1. fork a copy of both earthly/earthly, and earthly/homebrew-earthly
2. commit your changes you wish to release and push them to your personal repo.
3. save a copy of your GitHub token to user/github-token (e.g. earthly secrets set /user/github-token keep-it-secret)

Then run:

RELEASE_TAG=v0.5.10 GITHUB_USER=mygithubuser DOCKERHUB_USER=mydockerhubuser EARTHLY_REPO=earthly BREW_REPO=homebrew-earthly GITHUB_SECRET_PATH=user/github-token ./release.sh

NOTE: apt and yum repos do not currently support test releases. (TODO: fix this)

Troubleshooting

If the release-homebrew fails with a rejected git push, you may have to delete the remote branch by running the following under the interactive debugger:

git push "$GIT_USERNAME" --delete "release-$RELEASE_TAG"

Rollbacks

If you need to rollback/disable a version:

1. Go to GitHub releases, click on the edit release button, then check the This is a prerelease checkbox.
2. Check out the earthly/homebrew-earthly repo, and run:

git checkout main
git revert --no-commit 123abc..HEAD # where `123abc` is the sha1 commit to roll back to
git commit # enter a message saying you are rolling back
git push

3. Mark the release title in CHANGELOG.log as (aborted release/not recommended), e.g.: ## v0.7.18 - 2023-09-18 (aborted release/not recommended)
4. TODO need to create targets for apt and yum Earthfiles to perform rollbacks

dind

Docker-in-Docker (dind) images change less frequently than earthly, but take a long time to build. earthly/dind images and their releases are maintained in project repo.

Syntax Highlighting Releases

We currently have syntax highlighting for the following:

1. vscode + github
2. intellij (py, go, java)
3. vim
4. sublime
5. emacs

VSCode + GitHub

Release instructions can be found in the project repo.

Intellij

Intellij pulls its syntax highlighting from the same repo used by VSCODE + GitHub and so should be released after to keep up to date.

1. Go to the repo

2. Make relevant changes to the branches + test in this order:

   1. py
   2. go
   3. main

3. Sign + release the changes from each branch in this order:

   1. py
   2. go
   3. main

   Follow the instructions on how to sign and release as written in the README

Vim

1. Go to the repo
2. Make relevant updates and test
3. Once merged to main it will be released

Sublime Text

1. Go to the repo
2. Make relevant updates and test
3. Once merged to main it will be released

Emacs

1. Go to the repo
2. Make relevant updates and test
3. Once merged to main it will be released