From 4e541c8083645da37eb570c23e04dc65e1d6446c Mon Sep 17 00:00:00 2001
From: Alex Eagle <alex@aspect.dev>
Date: Fri, 3 Nov 2023 05:43:07 -0700
Subject: [PATCH] refactor: move 'git archive' config to .gitattributes (#101)

---
 .gitattributes                    | 12 ++++++++++++
 .github/workflows/release_prep.sh | 11 ++++-------
 README.md                         |  3 ++-
 3 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/.gitattributes b/.gitattributes
index fb496ed..cee54d6 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1 +1,13 @@
+# In code review, collapse generated files
 docs/*.md linguist-generated=true
+
+#################################
+# Configuration for 'git archive'
+# See https://git-scm.com/docs/git-archive#ATTRIBUTES
+
+# Don't include examples in the distribution artifact, to reduce size.
+# You may want to add additional exclusions for folders or files that users don't need.
+examples export-ignore
+
+# Occasionally there's a need to "stamp" the release version into a file
+mylang/version.bzl export-subst
diff --git a/.github/workflows/release_prep.sh b/.github/workflows/release_prep.sh
index 0f1445f..3f32e1e 100755
--- a/.github/workflows/release_prep.sh
+++ b/.github/workflows/release_prep.sh
@@ -2,19 +2,16 @@
 
 set -o errexit -o nounset -o pipefail
 
-# Don't include examples in the distribution artifact, to reduce size.
-# You may want to add additional exclusions for folders or files that users don't need.
-# NB: this mechanism relies on a `git archive` feature, which is much simpler and less
-# error-prone than using Bazel to build a release artifact from sources in the repository.
-# See https://git-scm.com/docs/git-archive#ATTRIBUTES
-echo >>.git/info/attributes "examples export-ignore"
-
 # Set by GH actions, see
 # https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables
 TAG=${GITHUB_REF_NAME}
 # The prefix is chosen to match what GitHub generates for source archives
+# This guarantees that users can easily switch from a released artifact to a source archive
+# with minimal differences in their code (e.g. strip_prefix remains the same)
 PREFIX="rules_mylang-${TAG:1}"
 ARCHIVE="rules_mylang-$TAG.tar.gz"
+
+# NB: configuration for 'git archive' is in /.gitattributes
 git archive --format=tar --prefix=${PREFIX}/ ${TAG} | gzip > $ARCHIVE
 SHA=$(shasum -a 256 $ARCHIVE | awk '{print $1}')
 
diff --git a/README.md b/README.md
index fa91ce1..bdf8b0a 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,8 @@ Features:
 - includes stardoc API documentation generator
 - includes typical toolchain setup
 - CI configured with GitHub Actions
-- Release using GitHub Actions just by pushing a tag
+- release using GitHub Actions just by pushing a tag
+- the release artifact doesn't need to be built by Bazel, but can still exclude files and stamp the version
 
 See https://docs.bazel.build/versions/main/skylark/deploying.html#readme