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 <[email protected]>

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.

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.

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)

devdocs/local_setup.md

@@ -0,0 +1,47 @@
+# Local development
+
+## 1. Clone the repo
+
+```bash
+git clone [email protected]: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.

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 [email protected]: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
+```

docs/contributors.md → 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)
+It will also make sure these changes are appropriately included in your commit (no further work is needed)