maint: prep for next release (#23)

Move to 1.1.<release count> version scheme. Move to using neil to track version within `deps.edn`. I don't necessarily think this is better than the old `version.edn`, but it is consistent with what I've done on my other projects. Tweak changelog - move to [breaking] [minor breaking] attributes on release header scheme I've used on other projects - automatically add yyyy-mm-dd date to release header - describe commits for release link as "commit log" Add GitHub release creation to release workflow. Stick with release initiated through GitHub UI on release workflow. I still feel this is much simpler than a version tag triggered release.
lread · May 1, 2024 · b41bcbf · b41bcbf
1 parent b8920e8
commit b41bcbf
Show file tree

Hide file tree

Showing 13 changed files with 317 additions and 276 deletions.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -56,27 +56,22 @@ jobs:
     - name: Download Clojure Dependencies
       run: bb download-deps
 
-    - name: Release Prep (step 1 of 4)
+    - name: Release Prep (step 1 of 5)
       run: bb ci-release prep
 
-    - name: Release Deploy (step 2 of 4)
+    - name: Release Deploy (step 2 of 5)
       env:
         CLOJARS_USERNAME: ${{ secrets.CLOJARS_USERNAME }}
         CLOJARS_PASSWORD: ${{ secrets.CLOJARS_PASSWORD }}
       run: bb ci-release deploy-remote
 
-    - name: Release Commit (step 3 of 4)
+    - name: Release Commit (step 3 of 5)
       run: bb ci-release commit
 
-    - name: Make GitHub Actions aware of target version tag
-      run: echo "tag=v$(clojure -T:build built-version)" >> $GITHUB_OUTPUT
-      id: target-version
-
-    - name: Create GitHub release (step 4 of 4)
-      uses: actions/create-release@v1
+    - name: Create GitHub Release (step 4 of 5)
       env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      with:
-        tag_name: ${{ steps.target-version.outputs.tag}}
-        release_name: ${{ steps.target-version.outputs.tag}}
-        commitish: main
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: bb ci-release create-github-release
+
+    - name: Inform Cljdoc (step 5 of 5)
+      run: bb ci-release inform-cljdoc
diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
@@ -1,122 +1,118 @@
 // NOTE: release process automatically updates titles with "Unreleased" to title with actual release version
 = Change Log
 
-For a list of breaking changes see link:#breaking[breaking-changes]
+[.normal]
+A release with known breaking changes is marked with:
 
-// Release workflow will:
-// - Fail if there is no "== Unreleased" section header
-// - Helpfully fail when the section contains no descriptive text
-// - Replace the Unreleased section header with actual release version
-// - Prepend a new Unreleased section header
+* [breaking] you probably need to change your code
+* [minor breaking] you likely don't need to change your code
+
+// DO NOT EDIT: the "Unreleased" section header is automatically updated by the release workflow
+// which will fail on any of:
+// - unreleased section not found,
+// - unreleased section empty
+// - optional attribute is not [breaking] or [minor breaking]
+//   (adjust these in ci_relase.clj as you see fit)
 
 == Unreleased
 
+* Drop `alpha` status, we don't have many users, but folks have been using this lib for years
+* Reviewed and refreshed docs
 * Bumped library deps (these are used during test generation only)
-* No longer engaging clj-kondo's lint feature during code analysis.
+* No longer engaging clj-kondo's lint feature during code analysis
 
-== v1.0.166-alpha
+== v1.0.166-alpha - 2021-11-27 [[v1.0.166-alpha]]
 
 * While preserving our existing `-X` command line interface, add a more conventional main command line interface to support leiningen (and potentially Windows) users https://github.com/lread/test-doc-blocks/issues/8[#8]
 * Now failing when a requested file/glob does not exist https://github.com/lread/test-doc-blocks/issues/9[#9]
 * Bump deps
 * Internal test-doc-blocks developer facing:
 ** Migrate from `depstar` to `tools.build`
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.146-alpha\...v1.0.166-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.146-alpha\...v1.0.166-alpha[commit log]
 
-== v1.0.146-alpha
+== v1.0.146-alpha - 2021-08-30 [[v1.0.146-alpha]]
 
 * Add support for `(refer-clojure ...)` in doc blocks https://github.com/lread/test-doc-blocks/issues/5[#5]
 * Bump rewrite-clj to v1.0.682-alpha
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.137-alpha\...v1.0.146-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.137-alpha\...v1.0.146-alpha[commit log]
 
-== v1.0.137-alpha
+== v1.0.137-alpha - 2021-08-23 [[v1.0.137-alpha]]
 
 * Freshen up docs, deps and internal scripts
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.129-alpha\...v1.0.137-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.129-alpha\...v1.0.137-alpha[commit log]
 
-== v1.0.129-alpha
+== v1.0.129-alpha - 2021-04-16 [[v1.0.129-alpha]]
 
 * Maintenance release - bump deps
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.124-alpha\...v1.0.129-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.124-alpha\...v1.0.129-alpha[commit log]
 
-== v1.0.124-alpha
+== v1.0.124-alpha - 2021-03-26 [[v1.0.124-alpha]]
 
 * Maintenance release - deps, docs and ops updates
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.116-alpha\...v1.0.124-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.116-alpha\...v1.0.124-alpha[commit log]
 
-== v1.0.116-alpha
+== v1.0.116-alpha - 2021-03-17 [[v1.0.116-alpha]]
 
 * Switch to `com.github.lread/test-doc-blocks` for deployment artifact name as per new security measures at clojars.
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.114-alpha\...v1.0.116-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.114-alpha\...v1.0.116-alpha[commit log]
 
-== v1.0.114-alpha
+== v1.0.114-alpha - 2021-03-14 [[v1.0.114-alpha]]
 
 * Ensure test-doc-blocks works on Windows
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.107-alpha\...v1.0.114-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.107-alpha\...v1.0.114-alpha[commit log]
 
-== v1.0.107-alpha
+== v1.0.107-alpha - 2021-03-13 [[v1.0.107-alpha]]
 
 * Support generating tests from CommonMark code blocks found in Clojure source docstrings
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.103-alpha\...v1.0.107-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.103-alpha\...v1.0.107-alpha[commit log]
 
-== v1.0.103-alpha
+== v1.0.103-alpha - 2021-03-12 [[v1.0.103-alpha]]
 
 * Correct sort order in new tree-like report of found blocks
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.101-alpha\...v1.0.103-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.101-alpha\...v1.0.103-alpha[commit log]
 
-== v1.0.101-alpha
+== v1.0.101-alpha - 2021-03-11 [[v1.0.101-alpha]]
 
 * Don't trim trailing newline for test body if last item is comment
 * Switch from (too) wide table to tree-like report of found blocks
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.92-alpha\...v1.0.101-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.92-alpha\...v1.0.101-alpha[commit log]
 
-== v1.0.92-alpha
+== v1.0.92-alpha - 2021-03-11 [[v1.0.92-alpha]]
 
 * Upgraded from rewrite-clj v0 to rewrite-clj v1
 * Release workflow now creates a GitHub release
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.85-alpha\...v1.0.92-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.85-alpha\...v1.0.92-alpha[commit log]
 
-== v1.0.85-alpha
+== v1.0.85-alpha - 2021-02-06 [[v1.0.85-alpha]]
 
 * Correct public API for cljdoc
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.82-alpha\...v1.0.85-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.82-alpha\...v1.0.85-alpha[commit log]
 
-== v1.0.82-alpha
+== v1.0.82-alpha - 2021-02-06 [[v1.0.82-alpha]]
 
 * Developer facing only: more updates to release workflow
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.80-alpha\...v1.0.82-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.80-alpha\...v1.0.82-alpha[commit log]
 
-== v1.0.80-alpha
+== v1.0.80-alpha - 2021-02-06 [[v1.0.80-alpha]]
 
 * Developer facing only: updates to release workflow
 
-https://github.com/lread/test-doc-blocks/compare/v1.0.76-alpha\...v1.0.80-alpha[Gritty details of changes for this release]
+https://github.com/lread/test-doc-blocks/compare/v1.0.76-alpha\...v1.0.80-alpha[commit log]
 
-== v1.0.76-alpha
+== v1.0.76-alpha - 2021-02-05 [[v1.0.72-alpha]]
 
 * First release
 
-[#breaking]
-== Breaking Changes
-
-// Release workflow will:
-// - If an "=== Unreleased Breaking Changes" section header exists here:
-//   - Helpfully fail the section contains no descriptive text
-//   - Replace the Unreleased section header with actual release version
-
-Still in alpha, nothing to track yet!
-
-// === Unreleased Breaking Changes
diff --git a/README.adoc b/README.adoc
@@ -27,7 +27,7 @@ toc::[]
 
 == Status
 
-Alpha - early adopters and feedback welcome!
+Folks have been using test-doc-blocks for years without issue.
 
 == Rationale
 I wanted to make sure the code examples I provided in rewrite-clj v1 documentation do not mislead and function as expected for those who dare to try them.
@@ -49,11 +49,11 @@ Have an update? Let us know!
 
 == Versioning
 
-Test-doc-block versioning scheme is: `major`.`minor`.`patch`-`test-qualifier`
+Test-doc-block versioning scheme is: `major`.`minor`.`release`-`test-qualifier`
 
 * `major` increments when the API has been broken - something, as a rule, we'd like to avoid.
 * `minor` increments to convey significant new features have been added.
-* `patch` indicates bug fixes - it is the number of commits in the repo.
+* `release` starting with v1.1, the test-doc-blocks release count over the life of test-doc-blocks.
 * `test-qualifier` is absent for stable releases. Can be `alpha`, `beta`, `rc1`, etc.
 
 == People

diff --git a/bb.edn b/bb.edn
@@ -1,11 +1,11 @@
 {:min-bb-version "0.3.7"
- :paths ["script"]
+ :paths ["script" "build"]
  :deps {lread/status-line {:git/url "https://github.com/lread/status-line.git"
                            :sha "cf44c15f30ea3867227fa61ceb823e5e942c707f"}
         dev.nubank/docopt {:mvn/version "0.6.1-fix7"}
         version-clj/version-clj {:mvn/version "2.0.2"}
-        etaoin/etaoin {:mvn/version "1.0.40"}}
-
+        etaoin/etaoin {:mvn/version "1.0.40"}
+        io.github.babashka/neil {:git/tag "v0.3.65" :git/sha "9a79582"}}
  :tasks {;; setup
          :requires ([babashka.fs :as fs]
                     [clojure.string :as string]
@@ -115,6 +115,9 @@
          cljdoc-preview {:doc "preview what docs will look like on cljdoc, use --help for args"
                          :task cljdoc-preview/-main}
 
+         ;; let's not rely on a random version of neil
+         neil              {:task babashka.neil/-main     :doc "Pinned version of babashka/neil (used in scripting)"}
+
          ci-test {:doc "run continuous integration service tests"
                   :task (when (no-args-check)
                           (run 'clean)

diff --git a/build.clj b/build.clj
@@ -1,33 +1,25 @@
 (ns build
-  (:require [clojure.edn :as edn]
-            [clojure.java.io :as io]
+  (:require [build-shared]
+            [clojure.edn :as edn]
             [clojure.tools.build.api :as b]))
 
-(def lib 'com.github.lread/test-doc-blocks)
-(def version (let [version-template (-> "version.edn" slurp edn/read-string)
-                   patch (b/git-count-revs nil)]
-               (str (:major version-template) "."
-                    (:minor version-template) "."
-                    patch
-                    (cond->> (:qualifier version-template)
-                      true (str "-")))))
+(def version (build-shared/lib-version))
+(def lib (build-shared/lib-artifact-name))
+
 (def class-dir "target/classes")
 (def basis (b/create-basis {:project "deps.edn"}))
 (def jar-file (format "target/%s.jar" (name lib)))
-(def built-jar-version-file "target/built-jar-version.txt")
 
 (defn jar
   "Build library jar file.
-
-   Also writes built version to target/built-jar-version.txt for easy peasy pickup by any interested downstream operation.
-
-  We use the optional :version-suffix to distinguish local installs from production releases.
-  For example, when preview for cljdoc, we use the suffix: cjdoc-preview."
-  [{:keys [version-suffix]}]
+  Supports `:version-override` for local testing, otherwise official version is used.
+  For example, when testing 3rd party libs against rewrite-clj HEAD we use the suffix: canary."
+  [{:keys [version-override] :as opts}]
   (b/delete {:path class-dir})
   (b/delete {:path jar-file})
-  (let [version (if version-suffix (format "%s-%s" version version-suffix)
-                    version)]
+
+  (let [version (or version-override version)]
+    (println "jarring version" version)
     (b/write-pom {:class-dir class-dir
                   :lib lib
                   :version version
@@ -49,29 +41,17 @@
                  :target-dir class-dir})
     (b/jar {:class-dir class-dir
             :jar-file jar-file})
-    (spit built-jar-version-file version)))
-
-(defn- built-version* []
-  (when (not (.exists (io/file built-jar-version-file)))
-    (throw (ex-info (str "Built jar version file not found: " built-jar-version-file) {})))
-  (slurp built-jar-version-file))
-
-(defn built-version
-  ;; NOTE: Used by release script and github workflow
-  "Spit out version of jar built (with no trailing newline).
-  A separate task because I don't know what build.tools might spit to stdout."
-  [_]
-  (print (built-version*))
-  (flush))
+    (assoc opts :built-version version)))
 
 (defn install
-  "Install built jar to local maven repo"
-  [_]
-  (b/install {:class-dir class-dir
-              :lib lib
-              :version (built-version*)
-              :basis basis
-              :jar-file jar-file}))
+  [opts]
+  (let [{:keys [built-version]} (jar opts)]
+    (println "installing version" built-version)
+    (b/install {:class-dir class-dir
+                :lib lib
+                :version built-version
+                :basis basis
+                :jar-file jar-file})))
 
 (defn deploy
   "Deploy built jar to clojars"
@@ -81,11 +61,6 @@
      :artifact jar-file
      :pom-file (b/pom-path {:lib lib :class-dir class-dir})}))
 
-(defn project-lib
-  "Returns project groupid/artifactid"
-  [_]
-  (println lib))
-
 (defn download-deps
   "Download all deps for all aliases"
   [_]

diff --git a/build/build_shared.clj b/build/build_shared.clj
@@ -0,0 +1,21 @@
+(ns build-shared
+  "a few things that are both needed by bb script code and build.clj"
+  (:require [clojure.edn :as edn]))
+
+(defn- project-info []
+  (-> (edn/read-string (slurp "deps.edn"))
+      :aliases :neil :project))
+
+(def version-tag-prefix "v")
+
+(defn lib-version []
+  (-> (project-info) :version))
+
+(defn lib-artifact-name []
+  (-> (project-info) :name))
+
+(defn lib-github-coords []
+  (-> (project-info) :github-coords))
+
+(defn version->tag [version]
+  (str version-tag-prefix version))
diff --git a/deps.edn b/deps.edn
@@ -8,7 +8,14 @@
         metosin/malli {:mvn/version "0.16.0"}
         rewrite-clj/rewrite-clj  {:mvn/version "1.1.47"}}
 
- :aliases {;;
+ :aliases {;; we use babashka/neil for project attributes
+           ;; publish workflow references these values (and automatically bumps patch component of version)
+           :neil {:project {:version "1.1.18" ;; describes last release and is template for next release
+                            :name com.github.lread/test-doc-blocks
+                            ;; not neilisms - could potentially conflict with new neilisms
+                            :github-coords lread/test-doc-blocks}}
+
+           ;;
            ;; Clojure versions we support
            ;; min for generation is v1.9
            ;; min for running generated v1.8
@@ -77,6 +84,7 @@
            ;; Deployment
            ;;
            :build {:deps {io.github.clojure/tools.build {:mvn/version "0.10.1"}}
+                   :extra-paths ["src" "build"]
                    :ns-default build}
 
            ;; keep deploy deps separate from build deps to avoid download-deps issues