From ffbb71c4efe3efb4305de4286f5aa6a20196d1c3 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 16 Aug 2017 15:25:09 -0700 Subject: [PATCH] tools: improve change notes process, make help system, make speed Draft change notes are now kept in CHANGENOTES.org in the top directory for easiest access. The changenotes-* rules for maintaining this have been renamed and improved. "make SECTION-help" has been added, as it's sometimes easier to type than "make help-SECTION". Eg if you append "-help" to any "make RULE" command you will likely see its help (and neighbouring RULEs' help. Specifically, it shows the "make help" output from the first match of the SECTION regexp to the next section end.) Makefile variables are now all of the dynamic/recursive type. This might mean shell commands are run redundantly when a variable is used multiple times, but it avoids running those shell commands at all when the variable is not used, which means most make rules should now feel more snappy. showreleaseauthors looks bitrotted and has been commented out. [ci skip] --- Makefile | 134 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 81 insertions(+), 53 deletions(-) diff --git a/Makefile b/Makefile index 214357707..3e9ca5622 100644 --- a/Makefile +++ b/Makefile @@ -48,12 +48,16 @@ $(call def-help-heading,TODO: some of these need updating) $(call def-help-heading,---------------------------------------) $(call def-help-heading, ) -# just to include "make help" in help: -help2: $(call def-help,[help], list documented rules in this makefile. "make RULE -n" shows more detail. ) +add-to-help-1: $(call def-help,[help], list documented rules in this makefile ) -help-%: $(call def-help,[help-SECTION], list documented rules in one section of this makefile. ) +help-%: $(call def-help,help-SECTION, list documented rules in the given section ) make help 2>&1 | sed -n '/$*/,/: $$/p' +%-help: $(call def-help,SECTION-help, same but easier to type (can append "-help" to any "make RULE") ) + @make help 2>&1 | sed -n '/$*/,/: $$/p' + +add-to-help-2: $(call def-help,RULE -n, show what RULE would do ) + ############################################################################### # VARS @@ -176,10 +180,10 @@ VERSIONSENSITIVEFILES=\ VERSIONFILE=.version # two or three-part version string, whatever's in VERSION -VERSION:=$(shell cat $(VERSIONFILE)) +VERSION=$(shell cat $(VERSIONFILE)) # the number of commits since the last tag -PATCHLEVEL:=$(shell git describe --tags --match 'hledger-[0-9]*' --long | awk -F- '{print $$3}') +PATCHLEVEL=$(shell git describe --tags --match 'hledger-[0-9]*' --long | awk -F- '{print $$3}') #PATCHLEVEL:=$(shell git describe --tags --match 'hledger-web-[0-9]*' --long | awk -F- '{print $$4}') # the number of commits since the last_release tag #PATCHLEVEL:=$(shell git rev-list last_release..HEAD | wc -l) @@ -223,8 +227,8 @@ WARNINGS:=\ # from stack's dist dir, hopefully there's just one. If not (after cabal upgrade), will get warnings. Maybe obsolete ? #CABALMACROSFLAGS=-optP-include -optP hledger/.stack-work/dist/*/*/build/autogen/cabal_macros.h -BUILDFLAGS1:=-rtsopts $(WARNINGS) $(INCLUDEPATHS) $(PREFERMACUSRLIBFLAGS) $(GHCMEMFLAGS) $(CABALMACROSFLAGS) -DPATCHLEVEL=$(PATCHLEVEL) -DDEVELOPMENT -BUILDFLAGS:=$(BUILDFLAGS1) -DVERSION='"$(VERSION)dev"' +BUILDFLAGS1=-rtsopts $(WARNINGS) $(INCLUDEPATHS) $(PREFERMACUSRLIBFLAGS) $(GHCMEMFLAGS) $(CABALMACROSFLAGS) -DPATCHLEVEL=$(PATCHLEVEL) -DDEVELOPMENT +BUILDFLAGS=$(BUILDFLAGS1) -DVERSION='"$(VERSION)dev"' # PROFBUILDFLAGS:=-prof -fprof-auto -osuf hs_p # # sp needs different quoting: # AUTOBUILDFLAGS:=$(BUILDFLAGS1) -DVERSION='\"$(VERSION)dev\"' # $(PROFBUILDFLAGS) @@ -240,8 +244,8 @@ BUILDFLAGS:=$(BUILDFLAGS1) -DVERSION='"$(VERSION)dev"' # # some other thing for linux binary filenames # RELEASEBINARYSUFFIX=$(shell echo "-$(VERSION)-`uname`-`arch`" | tr '[:upper:]' '[:lower:]') -TIME:=$(shell date +"%Y%m%d%H%M") -MONTHYEAR:=$(shell date +'%B %Y') +TIME=$(shell date +"%Y%m%d%H%M") +MONTHYEAR=$(shell date +'%B %Y') ############################################################################### $(call def-help-subheading,INSTALLING:) @@ -1100,47 +1104,6 @@ haddock: \ # # cd site/api && \ # # hoogle --convert=main.txt --output=default.hoo -# changelogs -# -# commits are appended as date-ordered org nodes to doc/CHANGES.org -# for easy editing. This is used as the basis for package changelogs -# (hledger*/CHANGES) and release notes (site/release-notes.md). - -DRAFTCHANGELOG=doc/CHANGES.org -LASTCHANGELOGREF:=`grep -E '^[a-f0-9]{8}$$' $(DRAFTCHANGELOG) | tail -1` -#TODO: list only from LASTTAG if no refs are present -#LASTTAG:=`git describe --tags --abbrev=0` -#GREPCHANGELOGREF:=grep -E '^[a-f0-9]{8}$$' $(DRAFTCHANGELOG) -#LASTCHANGELOGREF:=`($(GREPCHANGELOGREF) -q && ($(GREPCHANGELOGREF) | tail -1))` || `echo $(LASTTAG)` - -draft-changelog-start: \ - $(call def-help,draft-changelog-start, add an empty changelog outline to $(DRAFTCHANGELOG) ) - @make draft-changelog-template >>$(DRAFTCHANGELOG) - -draft-changelog-template: \ - $(call def-help,draft-changelog-template, print an empty org outline for drafting changelogs. ) - @echo "* draft changelog for `git describe --tags --abbrev=0`" - @echo "** hledger-lib" - @echo "** hledger" - @echo "** hledger-ui" - @echo "** hledger-web" - @echo "** hledger-api" - @echo "** project" - -draft-changelog-update: \ - $(call def-help,draft-changelog-update, add any new commits as org nodes to $(DRAFTCHANGELOG) ) - @make draft-changelog-$(LASTCHANGELOGREF) >> $(DRAFTCHANGELOG) - -draft-changelog-%: \ - $(call def-help,draft-changelog-STARTREF, print commits from STARTREF as org nodes. Eg: make draft-changelog-hledger-1.3 ) - @git log --abbrev-commit --reverse --pretty=format:'ORGNODE %s (%an)%n%b%h' $*.. \ - | sed -e 's/^\*/-/' -e 's/^ORGNODE/***/' \ - | sed -e 's/ (Simon Michael)//' - -draft-changelog-add-%: \ - $(call def-help,draft-changelog-add-STARTREF, add commits from STARTREF as org nodes to $(DRAFTCHANGELOG). Eg: make draft-changelog-add-HEAD~1 ) - @make draft-changelog-$* >>$(DRAFTCHANGELOG) - # # in subsequent rules, allow automatic variables to be used in prerequisites (use $$) @@ -1219,6 +1182,71 @@ site/manual2-1.md: site/manual-start.md site/manual-end.md $(MANPAGES) \ # echo pandoc $< -t man -s --template doc/webmanual.template -o $@ # too hard, see Shake.hs +######################## +# 2017 changelog process +# make help-changenotes + +# Commit messages are periodically appended to this org outline, +# and before release it is edited down to make the package changelogs +# (hledger*/CHANGES) and release notes (site/release-notes.md). +# The notes for past releases are kept in the outline, +# in case they might come in handy again. +# It is not specific to any particular branch, and not tracked with git. +CHANGENOTES=CHANGENOTES.org + +LASTTAG=$(shell git describe --tags --abbrev=0) + +# The last git revision referenced in the change notes. +# (Or, if there are no change notes, the last tag. +# Tries hard to be warning free and run shell commands only when needed.) +CHANGENOTESLASTREV=$(subst %,,$(subst %%,$(LASTTAG),%$(shell [ -f $(CHANGENOTES) ] && (grep -E '^[a-f0-9]{8}$$' $(CHANGENOTES) | tail -1) )%)) + +# create change notes file if it doesn't exist.. shouldn't happen much. +$(CHANGENOTES): + @make changenotes-start + +changenotes-start: \ + $(call def-help,changenotes-start, add a new outline named after $(VERSIONFILE) in $(CHANGENOTES). Run after bumping $(VERSIONFILE). ) + @(\ + echo "* change notes for hledger-$(VERSION)" ;\ + echo "** hledger-lib" ;\ + echo "** hledger" ;\ + echo "** hledger-ui" ;\ + echo "** hledger-web" ;\ + echo "** hledger-api" ;\ + echo "** hledger-install" ;\ + echo "** project" ;\ + ) >>$(CHANGENOTES) + +# TODO problem: this only checks the last (bottom-most) git rev in the +# change notes file, so after manual editing has begun this may re-add +# commits which are already in the file. +changenotes-update: $(CHANGENOTES) \ + $(call def-help,changenotes-update, add any not-yet-added(*) commits to $(CHANGENOTES). Run periodically (* it may get this wrong once manual editing has begun). ) + @make changenotes-show-from-$(CHANGENOTESLASTREV) >>$(CHANGENOTES) + @echo "Latest items in $(CHANGENOTES):" + @make changenotes-show | tail -10 + @make changenotes-show-last + +changenotes-update-from-%: \ +# $(call def-help,changenotes-update-from-REV, add commits from this git revision onward to $(CHANGENOTES) ) + @make changenotes-show-from-$* >>$(CHANGENOTES) + +changenotes-show-from-%: \ +# $(call def-help,changenotes-show-from-REV, show commits from this git revision onward as org nodes ) + @git log --abbrev-commit --reverse --pretty=format:'ORGNODE %s (%an)%n%b%h' $*.. \ + | sed -e 's/^\*/-/' -e 's/^ORGNODE/***/' \ + | sed -e 's/ (Simon Michael)//' + +changenotes-show: $(CHANGENOTES) \ + $(call def-help,changenotes-show, show all the org headlines recorded in $(CHANGENOTES) ) + @cat $(CHANGENOTES) | grep '*' + +# git l is a local alias with output like "2017-08-16 0a0e6d18 tools: make help-SECTION (HEAD -> master)" +changenotes-show-last: $(CHANGENOTES) \ + $(call def-help,changenotes-show-last, show the last commit recorded in $(CHANGENOTES) ) + @git l -1 $(CHANGENOTESLASTREV) + ############################################################################### $(call def-help-subheading,RELEASING:) #$(call def-help-subheading,see also developer guide -> how to -> do a release) @@ -1433,9 +1461,9 @@ hackageupload: \ describe: $(call def-help,describe, show a precise git-describe version string ) @git describe --tags --match 'hledger-[0-9]*' --dirty -showreleaseauthors: $(call def-help,showreleaseauthors, show author names since last release) - @echo Commit authors since last release: - @git shortlog -sn $(CHANGELOGSTART).. +# showreleaseauthors: $(call def-help,showreleaseauthors, show author names since last release) +# @echo Commit authors since last release: +# @git shortlog -sn $(CHANGELOGSTART).. # TODO undefined cloc: $(call def-help,cloc, count lines of source code ) @echo Lines of code including tests: