refactor: move 'git archive' config to .gitattributes (#101)

.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

.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}')
 

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