From cae3c21ea113b62a25b24099300d034921e111ba Mon Sep 17 00:00:00 2001 From: Dilum Aluthge Date: Wed, 26 Jun 2024 14:18:44 -0400 Subject: [PATCH] Make the devdocs more complete and self-contained (#252) * Make the devdocs more complete and self-contained * Rename devdocs/misc-notes-from-contributors.md to devdocs/misc/misc_notes_for_committers.md * Document the dependencies of the build script * No need to manually make multiple commits --------- Co-authored-by: Ian Butterworth --- CONTRIBUTING.md | 12 +- README.md | 4 + devdocs/README.md | 7 + devdocs/local_setup.md | 47 +++++++ devdocs/making_a_new_release.md | 128 ++++++++++++++++++ .../misc/misc_notes_for_committers.md | 4 +- 6 files changed, 190 insertions(+), 12 deletions(-) create mode 100644 devdocs/README.md create mode 100644 devdocs/local_setup.md create mode 100644 devdocs/making_a_new_release.md rename docs/contributors.md => devdocs/misc/misc_notes_for_committers.md (93%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a2d7cd8..4f9bd19 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,3 @@ -# Dev docs / Contributing guide +# Contributing -## Building and tagging a release (requires write access) - -1. Test your changes, merge into `master`. -2. Checkout `master`. -3. Bump the version number in [`package.json`](package.json). -4. Run `./bin/build-release julia-actions/setup-julia` to create a release branch and build a release. -5. Push the branch (**without tags**) and verify that CI is passing on it. -6. Run `git push --tags --force` to update the tags. -7. Create a release for the `vX.Y.Z` tag. +Please see the README in the [`devdocs/`](devdocs/) folder. diff --git a/README.md b/README.md index 11784b7..d72321d 100644 --- a/README.md +++ b/README.md @@ -285,3 +285,7 @@ Note that when debug logs are enabled, a request will be sent to `https://httpbi ## Third party information Parts of this software have been derived from other open source software. See [THIRD_PARTY_NOTICE.md](THIRD_PARTY_NOTICE.md) for details. + +## Contributing to this repo + +Please see the README in the [`devdocs/`](devdocs/) folder. diff --git a/devdocs/README.md b/devdocs/README.md new file mode 100644 index 0000000..80f87c2 --- /dev/null +++ b/devdocs/README.md @@ -0,0 +1,7 @@ +# Devdocs for the `setup-julia` repo + +If you want to make a pull request to this repo, please read the following: +1. [Local development](local_setup.md) + +If you have commit access to this repo, you may be interested in the following: +1. [Making a new release of this action](making_a_new_release.md) diff --git a/devdocs/local_setup.md b/devdocs/local_setup.md new file mode 100644 index 0000000..01597b2 --- /dev/null +++ b/devdocs/local_setup.md @@ -0,0 +1,47 @@ +# Local development + +## 1. Clone the repo + +```bash +git clone git@github.com:julia-actions/setup-julia.git +cd setup-julia +``` + +## 2. Install NodeJS + +### Unix, using `asdf` (recommended, but not required) + +First, make sure that you have installed [`asdf`](https://asdf-vm.com/) on your local machine. + +Then, `cd` to your clone of the repo and run the following commands: + +```bash +asdf plugin add nodejs +asdf install +``` + +This will use `asdf` to install the correct version of NodeJS. + +### Unix, but not using `asdf` + +Instead of using `asdf`, you can instead choose to install NodeJS manually. + +First, check the `.tool-versions` file in this repo, and see what version of NodeJS you need. Then, install that same version of NodejS on your local machine. + +### Windows + +`asdf` does not (currently) support Windows. So on Windows, you have to install NodeJS manually. + +First, check the `.tool-versions` file in this repo, and see what version of NodeJS you need. Then, install that same version of NodejS on your local machine. + +## 3. Working locally + +First, `cd` to your clone of the repo. Now you can run the following commands: + +```bash +npm ci + +npm run build +``` + +When you are ready, you can commit your changes and push them to your PR. diff --git a/devdocs/making_a_new_release.md b/devdocs/making_a_new_release.md new file mode 100644 index 0000000..dc5fd5e --- /dev/null +++ b/devdocs/making_a_new_release.md @@ -0,0 +1,128 @@ +# Making a new release of this action (requires commit access) + +If you have commit access to this repo, you can make a new release. + +Here are the instructions. + +## Step 1: Clone a fresh copy of the repo + +We intentionally work in a brand-new copy of the repo. + +```bash +git clone git@github.com:julia-actions/setup-julia.git +cd setup-julia +git checkout master +git submodule init +git submodule update +``` + +## Step 2: Make sure you have the right version of NodeJS + +If you use [`asdf`](https://asdf-vm.com/), this is as simple as: + +```bash +asdf plugin add nodejs +asdf install +``` + +If you don't use `asdf`, then you need to: +1. Open the `./tool-versions` file in the root of the repo. +2. Make note of the NodeJS version listed in the `.tool-versions` file. +3. Install that same version of NodeJS on your machine. +4. Make sure that you are currently using that version of NodeJS (i.e. it is at the front of your PATH). + +## Step 3: Edit the `version` field in `package.json` + +```bash +vim package.json + +# Edit the `version` number (should be line 2) +# Save your changes in Vim. Then exit Vim. + +# For the remaining of this guide, let MAJOR.MINOR.PATCH refer +# to the new version number that you set. + +git add package.json + +# No need to commit yet. +# The release script will run `git commit`. +``` + +## Step 4: Remove the `dist/` line from the `.gitignore` file + +```bash +vim .gitignore +# Delete the line that says `dist/` (it should be line 3) +# Save your changes in Vim. Then exit Vim. + +git add .gitignore + +# No need to commit yet. +# The release script will run `git commit`. +``` + +## Step 5: Make sure you have the necessary dependencies + +The `build-release.sh` script requires the following dependencies: + +1. Bash +2. `curl` +3. `git` +4. `jq` +5. `sed` + +## Step 6: Run the `build-release.sh` script + +```bash +ls -l bin/build-release.sh +chmod +x bin/build-release.sh +ls -l bin/build-release.sh + +./bin/build-release.sh julia-actions/setup-julia +``` + +Wait a minute or two. The script will build everything and will create a new release branch named `releases/vMAJOR.MINOR.PATCH`. + +## Step 7: Push ONLY the `releases/vMAJOR.MINOR.PATCH` branch + +Only push the `releases/` branch. Do NOT push any tags yet. + +```bash +git push origin releases/vMAJOR.MINOR.PATCH +``` + +Now you need to go to https://github.com/julia-actions/setup-julia/tree/releases/vMAJOR.MINOR.PATCH and wait for CI to finish running. + +Do NOT proceed to the next step until CI is all green on the `releases/vMAJOR.MINOR.PATCH` branch. + +## Step 8: Push the tags (only after CI is all green) + +Once CI is all green on the `releases/vMAJOR.MINOR.PATCH` branch, you can push the tags. + +You need to force-push. + +```bash +git push --tags --force +``` + +## Step 9: Use the GitHub web UI to create a new GitHub Release + +Go to https://github.com/julia-actions/setup-julia/releases and create a new release for the now-existant `vMAJOR.MINOR.PATCH` tag using the GitHub web interface. + +## Step 10: Clean up your local repo + +```bash +git submodule deinit --force . +git submodule update --init +git fetch --all --prune +git checkout master +git reset --hard origin/master +``` + +## Step 11: Delete your local repo + +```bash +cd .. +ls setup-julia +rm -rf setup-julia +``` diff --git a/docs/contributors.md b/devdocs/misc/misc_notes_for_committers.md similarity index 93% rename from docs/contributors.md rename to devdocs/misc/misc_notes_for_committers.md index fece2ea..47c687f 100644 --- a/docs/contributors.md +++ b/devdocs/misc/misc_notes_for_committers.md @@ -1,4 +1,4 @@ -# Contributors +# Misc notes for contributors ### Checkin @@ -19,4 +19,4 @@ git commit -m "Informative commit message" # Commit. This will run Husky ``` During the commit step, Husky will take care of formatting all files with [Prettier](https://github.com/prettier/prettier) as well as pruning out devDependencies using `npm prune --production`. -It will also make sure these changes are appropriately included in your commit (no further work is needed) \ No newline at end of file +It will also make sure these changes are appropriately included in your commit (no further work is needed)