Simplify how-to instructions on publishing a new revision of the lists

Author: jwakely

Makefile

@@ -65,6 +65,16 @@ history: bin/lists
 mailing:
 	mkdir $@
 
+LISTREV := $(shell xpath -q -e 'substring(issueslist/@revision,2)' xml/lwg-issues.xml)
+
+zip-file: lwg$(LISTREV).zip
+
+lwg$(LISTREV).zip: lists
+	@cd mailing && zip ../$@ \
+		lwg-active.html lwg-closed.html lwg-defects.html \
+		lwg-index.html lwg-index-open.html lwg-status.html lwg-toc.html
+	@echo Created $@
+
 lists: mailing bin/lists dates meta-data/paper_titles.txt
 	bin/lists
 
@@ -115,7 +125,7 @@ meta-data/section.data: meta-data/annex-f meta-data/networking-section.data bin/
 	cat meta-data/lfts-v3-section.data >> $@.tmp
 	$(call update,$@)
 
-.PHONY: all pgms clean distclean lists history
+.PHONY: all pgms clean distclean lists history zip-file
 
 dates: meta-data/dates
 

how-to-docs.html

@@ -144,16 +144,15 @@ <h2>Generate Issues Lists for a Mailing</h2>
 responsibility for publishing the issues lists by the Library Working Group chair.  They are recorded for future
 reference to ease the burden on incoming chairs.</p>
 <ol>
-<li>inspect <code>git branch</code> to confirm that you are on the <code>master</code> branch</li>
+<li>Inspect <code>git branch</code> to confirm that you are on the <code>master</code> branch</li>
 <li><code>git pull</code> any last changes that may have been committed by others at github</li>
 <li>Confirm that the issues data is in its publishable state</li>
 <li>Push the current branch to github with a pre-mailing commit message
     <ol>
-    <li><code>git commit -a -m&quot;<i>commit message</i>&quot;</code></li>
+    <li><code>git commit -a -m &quot;<i>commit message</i>&quot;</code></li>
     <li><code>git push</code></li>
     </ol>
 </li>
-<li>Fork a new branch to hold the final mailing with <code>git checkout -b <i>branch-name</i></code></li>
 <li>Update <code>xml/lwg-issues.xml</code> with:
     <ol>
     <li>The final 'R' revision of the list (provisional lists use a 'D')</li>
@@ -169,13 +168,14 @@ <h2>Generate Issues Lists for a Mailing</h2>
     <li>(this mailing's revision history will be generated by the software)</li>
     </ol>
 </li>
-<li>Generate the lists only - do <b>not</b> run the generate-<i>and-publish</i> script above</li>
+<li>Generate the lists (<code>make lists</code>)</li>
 <li>Inspect the generated lists in the <code>mailing</code> directory</li>
 <li>Correct any problems, and repeat the process until satisfied</li>
-<li>Commit changes to git branch, with a suitable commit message</li>
-<li>Zip the whole <code>mailing</code> directory, and email it to Keld Simmonsen</li>
+<li>Commit changes to git, with a suitable commit message</li>
+<li>Create a zip file by running <code>make zip-file</code> and email it to Keld Simmonsen
+</li>
 </ol>
-<p>Now it is time to prepare the branch for the next mailing.  This work should be completed <i>before</i> merging back to master.</p>
+<p>Now it is time to prepare the files for the next mailing.</p>
 <ol>
 <li>Update <code>xml/lwg-issues.xml</code> with:
     <ol>
@@ -192,18 +192,13 @@ <h2>Generate Issues Lists for a Mailing</h2>
     </ol>
 </li>
 <li>Replace <code>metadata/lwg-toc.old.html</code> with <code>mailing/lwg-toc.html</code> (note the name change, adding <code>.old</code></li>
-<li>Generate the lists only - do <b>not</b> run the generate-<i>and-publish</i> script above</li>
+<li>Generate the lists (<code>make lists</code>)</li>
 <li>Confirm that the document numbers are provisional, and the revision history is correct for the next mailing preview</li>
 <li>Repeat the process until satisfied</li>
-<li>Commit the git branch with an appropriate commit comment - <i>do not merge yet</i></li>
-<li>Run <code>git checkout master</code> to switch back to the <code>master</code> branch
-<li>Run <code>git pull</code> to ensure the current branch is in synch with github
-<li>Run <code>git merge <i>branch-name</i></code> where <code><i>branch-name</i></code> matches the branch above</li>
-<li>Resolve any conflicts (typically there are none)</li>
-<li>Regenerate the issues lists again, to confirm that branch and tools are in a good state</li>
+<li>Commit to git with an appropriate commit message</li>
+<li>Regenerate the issues lists again, to confirm that XML files and tools are in a good state</li>
 <li>Run <code>git status</code> to confirm there are no unexpected last minute edits that are not committed</li>
 <li>Run <code>git push</code> to publish the updated <code>master</code> branch</li>
-<li>Regenerate <i>and publish</i> the interim issues lists as described in the Add-an-issue process</li>
 <li>Notify any collaborators to pull the updated <code>master</code> branch - the main list is open for business again</li>
 </ol>