how-to-docs.html

<!DOCTYPE html>
<html lang="en-US">

<head>
<meta charset="utf-8">
<title>How To</title>
</head>

<body>

<p>Revised:
2 November 2024</p>

<h1>How To Instructions</h1>
<p>These instructions assume you keep the issues lists source files in a directory named <code>issues</code>.
Each issue is stored in an XML file.
The code in <code>src</code> generates the HTML issues lists from the XML sources.
When changes to the XML files are pushed to the GitHub repository an automated
<a href="https://docs.github.com/en/actions">GitHub Actions</a> workflow
generates new HTML files and commits them to the <code>gh-pages</code> branch.
The content of the <code>gh-pages</code> branch is automatically deployed
to <a href="https://cplusplus.github.io/LWG/">https://cplusplus.github.io/LWG/</a>.
</p>

<h2>Prerequisites</h2>
<ul>
  <li>Git</li>
  <li>A C++17 compiler. Clang 9 works. GCC 8.x works for unix-like systems, but GCC 9.3 is recommended (because its <code>std::filesystem</code> supports Windows, and no additional <code>-lstdc++fs</code> linker option is needed).</li>
  <li>Windows is a prerequisite to use the Windows <code>.bat</code> scripts;
  a POSIX environment is a prerequisite to use the equivalent <code>make</code>
  commands.</li>
</ul>

<h2>Initial setup</h2>
<p><b>Do this once only:</b></p>
<blockquote>
<pre>cd path-to-where-you-want-to-keep-this-stuff
git clone git@github.com:cplusplus/LWG.git issues
</pre>
</blockquote>
<p>
The commands shown below assume you are in the <code>issues</code> directory
that contains the git repository cloned by the command above.
</p>
<p>
The repository contains a <code>Makefile</code> that has recipes for
building the software (<code>make pgms</code>),
updating the meta-data (<code>make new-papers</code> etc.),
and regenerating the HTML lists (<code>make lists</code>).
</p>

<h2>Working with the issues lists on Windows</h2>
<p>
If you can't use <code>make</code> then the steps are a little more manual:
</p>
<blockquote>
<pre>cd issues
mkdir mailing
bin\build_pgms
bin\build_lists
</pre></blockquote>
<p>
You will need to re-run <code>bin\build_pgms</code>
whenever the source code (in <code>issues/src</code>) changes.
(This isn't needed when using <code>make</code> because the makefile
will automatically do <code>make pgms</code> as a prerequisite of
<code>make lists</code>.)
</p>

<h2>Add or change issues</h2>
<p>There is one source file per issue, in <code>issues/xml</code>. The file
<code>issues/xml/lwg-template.xml</code> is a template for a
new issue.</p>
<p>Commit files locally as you update them:</p>
<blockquote>
  <pre><em># edit the XML files or add new XML files</em>
<em># ...</em>
<em># stage the edited XML files (and any new ones) to be committed:</em>
git add xml/issues*.xml
git commit -m "your commit message here"</pre>
</blockquote>
<p>Verify your changes had the desired effect by regenerating the
issues lists and inspecting your changes, by running
<code>make lists</code> (or <code>bin\build_lists</code> on Windows).
</p>
<p>Once you are happy with your changes, push them up to the GitHub
public repository:</p>
<blockquote>
  <pre>git push</pre>
</blockquote>
<p>New versions of the issues lists will be automatically published online.</p>

<h2>Update meta-data</h2>
<p>
The files in <code>issues/meta-data</code> need to be updated whenever
there is a new draft of the working paper.
</p>
<p>
To do this, we need an up-to-date copy of the data in Annex F in a file <code>meta-data/annex-f</code>.
</p>
<p>This can be more or less automatically generated (on a Unix system):</p>
<ol>
<li>Get a current copy of the source for the standard, and build it at the right Git revision for the new working draft
(there is usually a Git tag for each N-numbered working draft).</li>
<li>Run <code>make meta-data/section.data</code> to regenerate it.
You can set the Make variables <code>WG21</code> or <code>NET</code>
to tell the makefile where to find the LaTeX sources.</li>
<li>Use <code>git diff meta-data/section.data</code> to check that the changes look OK.</li>
<li>Optionally, repeat this procedure for the Networking TS.
First build the TS sources at the desired revision,
then run <code>rm meta-data/networking-annex-f ; make meta-data/section.data</code>.
The makefile rule for the TS meta-data will only try to regenerate the file
if it doesn't exist, so that having the TS sources present is not required.
You can set the Make variables <code>WG21</code> or <code>NET</code>
to tell the makefile where to find the LaTeX sources.
</li>
</ol>
<p>If you are happy with the deltas of the <code>annex-f</code> files, commit them to Git.</p>
<p>
To update the list of paper titles, run <code> make new-papers </code>
(this needs <code>curl</code> and <code>python</code> to be installed).
</p>

<h2>Generate Issues Lists for a Mailing</h2>
<p>We no longer include lists of issues, accepted/resolved issues, and rejected/closed issues in each mailing.
However, we still generate these lists, and send them to Keld for posting. These documents are produced directly by the software above.</p>
<p>The following steps should be pursued by <i>only</i> the Library Working Group chair, or someone delegated the
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><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 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>
    <li>The current date</li>
    </ol>
</li>
<li>Confirm that the following <code>xml/lwg-issues.xml</code> information is correct:
    <ol>
    <li>The LWG chair contact address (unlikely to change)</li>
    <li>The mailing title</li>
    <li>No new edits are needed to the boiler-plate text (changes are rare)</li>
    <li>The revision history is up to date for the <b><i>preceding</i></b> mailing</li>
    <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>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>
</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>
<ol>
<li>Update <code>xml/lwg-issues.xml</code> with:
    <ol>
    <li>The revision history (this should be done first)
        <ol>
        <li>Run <code>make history</code> (or equivalently, <code>bin/lists revision history</code>)
            to print the new revision history.</li>
        <li>Paste the new revision under the <code>&lt;revision_history&gt;</code> tag</li>
        </ol>
    </li>
    <li>The provisional 'D' revision of the next list ('R' &rarr; 'D', and increment the number).</li>
    <li>An estimated date close to the next mailing.</li>
    <li>The mailing title.</li>
    </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>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>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>

<hr>

<h2>Generate Issues Lists for Straw Polls</h2>

<p>
Follow the steps above to create the generated lists in the <code>mailing</code>
directory, then use the <code>bin/issues_to_be_moved.sh</code> script.
During the meeeting (or in the week preceding a virtual meeting),
set status="Voting" for all the issues that are being moved in the straw polls.
This records that they are going to be subject to a vote, and help to keep
them separate from any other issues that move to a "Ready" status during that
time.
</p>

<hr>

<h2>Managing issues during a meeting</h2>
<p><i>preliminary notes here; more to come</i></p>
<p>Typical use was to move all Ready issues to Voting after the pre-meeting mailing, so that Issues moving to Ready during the meeting would not be confused.</p>
<p>Similarly, Voting issues could then easily move to Pending WP after the straw polls, and to WP once the new draft is available.</p>
<p>Likewise, you will want to move all the WP issues to C++23 once we approve the FDIS.</p>

<ul>
<li><code>list_issues &lt;status&gt;</code> will list all the issues with a specific status</li>
<li><code>set_status &lt;issue&gt; &lt;status&gt; ["optional comment"]</code> will set a single issue to a new status, with an optional comment if desired.</li>
<li><code>update_status.sh &lt;status&gt;</code> will read a list of issue numbers from stdin and update the status of each of them.</li>
</ul>

<p>For example, <code>bin/list_issues "Ready" | bin/update_status.sh "Voting"</code> will change the status of all the "Ready" issues to "Voting" (w/o committing them).</p>

</body></html>