release: use commit SHA for [sources] instead of branch names

Previously, the [sources] entries in Project.toml referenced the
releases/YYYY-MM-DD branch names, requiring these branches to be kept
indefinitely. This change modifies the release process to reference
commit SHAs directly, allowing release branches to be deleted after
merging.

The new release flow in prepare-release.sh:
1. Generate vendor/ with local path references
2. Commit and push to get a stable commit SHA
3. Re-run vendor-deps.jl with --rev=<SHA> to update [sources]
4. Commit the final release

vendor-deps.jl now requires either --local or --rev=<sha> explicitly,
making the source reference strategy clear at invocation time.

Pinned installation now uses release tags (rev="YYYY-MM-DD") instead of
branch names (rev="releases/YYYY-MM-DD"). Existing release branches
will be kept until end of December 2025 for backward compatibility.

Written by Claude

Author: aviatesk

CHANGELOG.md

@@ -9,13 +9,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 > as it is not registered in General due to environment isolation requirements.
 >
 > Each dated section below corresponds to a release that can be installed via
-> `Pkg.Apps.add(; url="https://github.com/aviatesk/JETLS.jl", rev="releases/YYYY-MM-DD")`
+> `Pkg.Apps.add(; url="https://github.com/aviatesk/JETLS.jl", rev="YYYY-MM-DD")`
 
 ## Unreleased
 
 - Commit: [`HEAD`](https://github.com/aviatesk/JETLS.jl/commit/HEAD)
 - Diff: [`6ec51e1...HEAD`](https://github.com/aviatesk/JETLS.jl/compare/6ec51e1...HEAD)
 
+### Changed
+
+- Pinned installation now uses release tags (`rev="YYYY-MM-DD"`) instead of
+  branch names (`rev="releases/YYYY-MM-DD"`). The `releases/YYYY-MM-DD` branches
+  can now be deleted after merging since `[sources]` entries reference commit
+  SHAs directly. Existing release branches (`releases/2025-11-24` through
+  `releases/2025-11-27`) will be kept until the end of December 2025 for
+  backward compatibility.
+
 ### Removed
 
 - Removed the deprecated `runserver.jl` script. Users should use the `jetls`

DEVELOPMENT.md

@@ -226,9 +226,18 @@ analyzing.
   packages.
 - `releases/YYYY-MM-DD`: Release preparation branches. These branches are
   created from `release`, merged with `master`, vendored, and then merged back
-  into `release` via pull requests on GitHub. These branches must be kept
-  (not deleted) because the `release` branch's `[sources]` entries reference
-  them by name.
+  into `release` via pull requests on GitHub. These branches can be deleted
+  after merging because the `[sources]` entries reference specific commit SHAs,
+  not branch names.
+
+### Pinned installation
+
+Users can install a specific release version using Julia's package manager with
+the release tag:
+```julia
+julia -e 'using Pkg; Pkg.Apps.add(; url="https://github.com/aviatesk/JETLS.jl", rev="YYYY-MM-DD")'
+```
+Replace `YYYY-MM-DD` with the desired release date (e.g., `2025-11-27`).
 
 ### Release procedure
 
@@ -246,10 +255,8 @@ After the script completes:
    `master` commits are included in `release`. The CI will run tests on the
    vendored environment before merging.
 
-2. **Do NOT delete the `releases/YYYY-MM-DD` branch after merging.** These
-   branches must be kept because the `release` branch's `[sources]` entries
-   reference them by name. Keeping them also allows users to install specific
-   releases via the Julia package manager.
+2. The `releases/YYYY-MM-DD` branch can be deleted after merging. The `[sources]`
+   entries reference specific commit SHAs, so the branch is no longer needed.
 
 After the PR is merged, `CHANGELOG.md` on `master` will be automatically updated
 by the CI workflow.
@@ -267,36 +274,38 @@ The `prepare-release.sh` script automates the following steps:
    git merge master -X theirs
    ```
 
-2. Update the version file
+2. Vendor dependency packages with local paths
    ```bash
-   echo "$JETLS_VERSION" > JETLS_VERSION
+   julia --startup-file=no --project=. scripts/vendor-deps.jl --source-branch=master --local
+   ```
+   This generates `vendor/` with local path references in `[sources]`.
+
+3. Commit and push the vendor directory
+   ```bash
+   git add -A
+   git commit -m "release: update vendored dependencies ($JETLS_VERSION)"
+   git push -u origin releases/$JETLS_VERSION
    ```
 
-3. Vendor dependency packages
+4. Update `[sources]` to reference the vendor commit SHA
    ```bash
-   julia --startup-file=no --project=. scripts/vendor-deps.jl --source-branch=master
+   VENDOR_COMMIT=$(git rev-parse HEAD)
+   julia --startup-file=no --project=. scripts/vendor-deps.jl --source-branch=master --rev="$VENDOR_COMMIT"
    ```
-   This script performs the following:
-   - Fetches the latest `Project.toml` from the specified source branch (`master`)
-   - Backs it up as `Project.toml.bak`
-   - Cleans up `Manifest.toml` and runs `Pkg.update()`
-   - Loads JETLS and collects dependency packages from `Base.loaded_modules`
-   - Copies each package to `vendor/` and rewrites its UUID
-   - Removes unused weakdeps and extensions from vendored packages
-   - Updates `Project.toml` with vendored UUIDs and `[sources]` entries
-   - Cleans up `Manifest.toml` and runs `Pkg.instantiate()`
-
-4. Commit and push
+   This updates `[sources]` entries to use the commit SHA instead of local paths.
+
+5. Commit and push the release
    ```bash
+   echo "$JETLS_VERSION" > JETLS_VERSION
    git add -A
    git commit -m "release: $JETLS_VERSION"
-   git push -u origin releases/$JETLS_VERSION
+   git push origin releases/$JETLS_VERSION
    ```
    **Important**: The commit message must follow the `release: YYYY-MM-DD` format
    exactly. The documentation CI extracts this date to display in the release
    documentation's index page.
 
-5. Create a pull request from `releases/YYYY-MM-DD` to `release`.
+6. Create a pull request from `releases/YYYY-MM-DD` to `release`.
 
 > [!note]
 > `vendor-deps.jl` generates UUIDs using `uuid5(original_uuid, "JETLS-vendor")`.

docs/src/index.md

@@ -50,9 +50,9 @@ is properly added to your `PATH`.
     will fetch the most recent version since the `release` branch always
     points to the latest release.
 
-    To pin a specific version instead, use `rev="releases/YYYY-MM-DD"`:
+    To pin a specific version instead, use the release tag `rev="YYYY-MM-DD"`:
     ```bash
-    julia -e 'using Pkg; Pkg.Apps.add(; url="https://github.com/aviatesk/JETLS.jl", rev="releases/2025-11-25")'
+    julia -e 'using Pkg; Pkg.Apps.add(; url="https://github.com/aviatesk/JETLS.jl", rev="2025-11-25")'
     ```
     Note that pinned versions will not be updated by `Pkg.Apps.update("JETLS")`.
 

jetls-client/README.md

@@ -62,10 +62,10 @@ executable from your `PATH`.
 > will fetch the most recent version since the `release` branch always
 > points to the latest release.
 >
-> To pin a specific version instead, use `rev="releases/YYYY-MM-DD"`:
+> To pin a specific version instead, use the release tag `rev="YYYY-MM-DD"`:
 >
 > ```bash
-> julia -e 'using Pkg; Pkg.Apps.add(; url="https://github.com/aviatesk/JETLS.jl", rev="releases/2025-11-25")'
+> julia -e 'using Pkg; Pkg.Apps.add(; url="https://github.com/aviatesk/JETLS.jl", rev="2025-11-25")'
 > ```
 >
 > Note that pinned versions will not be updated by `Pkg.Apps.update("JETLS")`.

scripts/prepare-release.sh

@@ -3,10 +3,11 @@
 # Prepare a new JETLS release.
 #
 # Usage:
-#     ./scripts/prepare-release.sh YYYY-MM-DD
+#     ./scripts/prepare-release.sh YYYY-MM-DD [--local]
 #
 # Example:
 #     ./scripts/prepare-release.sh 2025-11-27
+#     ./scripts/prepare-release.sh 2025-11-27 --local  # skip push and PR creation
 #
 # This script automates the release procedure documented in DEVELOPMENT.md:
 # 1. Creates a release branch from `release` and merges `master`
@@ -16,14 +17,38 @@
 
 set -euo pipefail
 
-if [[ $# -ne 1 ]]; then
-    echo "Usage: $0 YYYY-MM-DD"
+LOCAL_MODE=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --local)
+            LOCAL_MODE=true
+            shift
+            ;;
+        -*)
+            echo "Unknown option: $1"
+            echo "Usage: $0 YYYY-MM-DD [--local]"
+            exit 1
+            ;;
+        *)
+            if [[ -z "${JETLS_VERSION:-}" ]]; then
+                JETLS_VERSION="$1"
+            else
+                echo "Error: Unexpected argument: $1"
+                echo "Usage: $0 YYYY-MM-DD [--local]"
+                exit 1
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "${JETLS_VERSION:-}" ]]; then
+    echo "Usage: $0 YYYY-MM-DD [--local]"
     echo "Example: $0 2025-11-27"
     exit 1
 fi
 
-JETLS_VERSION="$1"
-
 # Validate date format
 if ! [[ "$JETLS_VERSION" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
     echo "Error: Version must be in YYYY-MM-DD format"
@@ -57,38 +82,60 @@ git pull origin release
 git checkout -b "releases/$JETLS_VERSION"
 git merge origin/master -X theirs -m "Merge master into releases/$JETLS_VERSION"
 
-# Step 2: Update JETLS_VERSION file
-echo "==> Step 2: Updating JETLS_VERSION"
-echo "$JETLS_VERSION" > JETLS_VERSION
+# Step 2: Vendor dependency packages with local paths
+echo "==> Step 2: Vendoring dependencies (local paths)"
+julia --startup-file=no --project=. scripts/vendor-deps.jl --source-branch=master --local
+
+# Step 3: Commit vendor/ directory
+echo "==> Step 3: Committing vendor/ directory"
+git add -A
+git commit -m "vendor: update vendored dependencies"
+if [[ "$LOCAL_MODE" == false ]]; then
+    git push -u origin "releases/$JETLS_VERSION"
+fi
 
-# Step 3: Vendor dependency packages
-echo "==> Step 3: Vendoring dependencies"
-julia --startup-file=no --project=. scripts/vendor-deps.jl --source-branch=master
+# Step 4: Get the commit SHA and update [sources] to reference it
+echo "==> Step 4: Updating [sources] to reference commit SHA"
+VENDOR_COMMIT=$(git rev-parse HEAD)
+echo "Vendor commit SHA: $VENDOR_COMMIT"
+julia --startup-file=no --project=. scripts/vendor-deps.jl --source-branch=master --rev="$VENDOR_COMMIT"
 
-# Step 4: Commit and push
-echo "==> Step 4: Committing and pushing"
+# Step 5: Commit the final release
+echo "==> Step 5: Committing release"
+echo "$JETLS_VERSION" > JETLS_VERSION
 git add -A
 git commit -m "release: $JETLS_VERSION"
-git push -u origin "releases/$JETLS_VERSION"
 
-# Step 5: Create pull request
-echo "==> Step 5: Creating pull request"
-PR_URL=$(gh pr create \
-    --base release \
-    --head "releases/$JETLS_VERSION" \
-    --title "release: $JETLS_VERSION" \
-    --body "$(cat <<EOF
-This PR releases version `$JETLS_VERSION`.
+if [[ "$LOCAL_MODE" == true ]]; then
+    echo ""
+    echo "==> Local mode: skipping push and PR creation"
+    echo ""
+    echo "Release branch prepared locally: releases/$JETLS_VERSION"
+    echo "To complete the release manually:"
+    echo "  1. git push -u origin releases/$JETLS_VERSION"
+    echo "  2. Create a PR from releases/$JETLS_VERSION to release"
+    exit 0
+fi
+
+git push origin "releases/$JETLS_VERSION"
+
+# Step 6: Create pull request
+echo "==> Step 6: Creating pull request"
+PR_BODY="This PR releases version \`$JETLS_VERSION\`.
 
 ## Checklist
-- [ ] `release / Test JETLS.jl with release environment`
-- [ ] `release / Test jetls executable with release environment`
+- [ ] \`release / Test JETLS.jl with release environment\`
+- [ ] \`release / Test jetls executable with release environment\`
 
 ## Post-merge
-- Do NOT delete the \`releases/$JETLS_VERSION\` branch after merging
-- CHANGELOG.md will be automatically updated on master
-EOF
-)")
+- The \`releases/$JETLS_VERSION\` branch can be deleted after merging
+- CHANGELOG.md will be automatically updated on master"
+
+PR_URL=$(gh pr create \
+    --base release \
+    --head "releases/$JETLS_VERSION" \
+    --title "release: $JETLS_VERSION" \
+    --body "$PR_BODY")
 
 echo ""
 echo "==> Release preparation complete!"
@@ -98,4 +145,4 @@ echo ""
 echo "Next steps:"
 echo "  1. Wait for CI to pass"
 echo "  2. Merge the PR using 'Create a merge commit' (not squash or rebase)"
-echo "  3. Do NOT delete the releases/$JETLS_VERSION branch"
+echo "  3. The releases/$JETLS_VERSION branch can be deleted after merging"