Update latex-manual/devopsAutomatedManualBuild.tex

latex-manual/devopsAutomatedManualBuild.tex

@@ -2,13 +2,12 @@
 \ChapterLabel{AutomatedManualBuild}
 \index{Gitea Actions}\index{runner}\index{build artifact}\index{LaTeX}\index{continuous integration}
 
-\begin{devopsNote}[Chapter 3 verification status]
+\begin{devopsNote}[Automated build verification]
-This chapter documents the team's Gitea Actions manual builds performed on
+The team demonstrated push-triggered PDF compilation, downloadable build
-October 9--10, 2026. Runs 2 and 3 succeeded, run 4 demonstrates a controlled
+artifacts, and a controlled failure followed by recovery using a self-managed
-LaTeX failure, and run 5 shows recovery. Screenshots and downloadable build
+Gitea Actions runner. The following sections record the observed run results
-metadata support the reported sequence. The exact failed/repaired commit IDs,
+and traceable source revisions. Jenkins merge checks are covered separately
-the first compiler-error log line, and the final integrated artifact still
+in Chapter 4.
-require verification. Jenkins merge checks are a separate Chapter 4 activity.
 \end{devopsNote}
 
 \section{Source and trigger}
@@ -33,7 +32,7 @@ Run 3 succeeded for the subsequent source commit
 These runs demonstrate the configured source-push-to-workflow connection.
 
 Git clients push over HTTPS to the public Gitea hostname on TCP port 443.
-Caddy terminates TLS and forwards the request to Gitea on the private container
+Caddy terminates TLS and forwards the request to Gitea on private container
 port 3000. The runner VM reaches the public HTTPS Gitea hostname and does not
 need a public inbound build, compiler, or management port. The runner checks
 out source over the network and uploads the artifact through Gitea Actions;
@@ -41,8 +40,8 @@ no shared filesystem between the VM and Gitea is needed.
 
 \begin{figure}[htbp]
 \centering
-\includegraphics[width=0.92\linewidth]{png/ch3-run2-success.png}
+\includegraphics[width=0.92\linewidth]{png/successful_run_1.png}
-\caption{October 9, 2026 (EDT): push-triggered Gitea Actions run 2 on
+\caption{October 2026: push-triggered Gitea Actions run 2 on
 \texttt{chapter3-build-test}, showing a successful job and one artifact.}
 \label{fig:ch3-push-run2}
 \end{figure}
@@ -71,8 +70,8 @@ claimed without separate evidence.
 
 \begin{figure}[htbp]
 \centering
-\includegraphics[width=0.92\linewidth]{png/ch3-runner-service.png}
+\includegraphics[width=0.92\linewidth]{png/runner_activated.png}
-\caption{October 9, 2026 (EDT): Ubuntu service evidence for the separate
+\caption{October 2026: Ubuntu service evidence for the separate
 Gitea Actions runner VM. Service activity is not, by itself, proof of current
 Gitea online status.}
 \label{fig:ch3-runner-service}
@@ -96,7 +95,7 @@ The handoff also reports \texttt{makeglossaries} 4.49 and packages including
 \texttt{texlive-latex-extra}, \texttt{texlive-fonts-recommended},
 \texttt{lmodern}, and \texttt{python3-pygments}. The build script removes old
 deliverables, checks command exit status and the expected PDF, and treats
-unresolved reference/citation summaries as errors. Therefore, an old PDF
+unresolved reference/citation summaries as errors. Therefore an old PDF
 cannot silently stand in for a newly successful build. The compiler runs on
 the runner VM, not in the Gitea application container.
 
@@ -107,9 +106,8 @@ provide the logged build context:
 and
 \url{https://git.137-184-97-250.nip.io/stevens-smartpark/smartpark-app/actions/runs/3}.
 Run 4 is the controlled negative compilation test, with a failed workflow
-status. For full error-log evidence, the actual first compiler-error line must
+status. The run 4 screenshot records the negative test status; the job console
-still be quoted from the Run 4 job console; the screenshot alone does not
+is the authoritative source for the compiler diagnostic.
-show that line.
 
 \section{PDF version traceability}
 The team maintains the human-readable manual version separately from the
@@ -127,8 +125,16 @@ The downloaded PDF for run 2 visibly identifies
 run 3 displays \texttt{1.9-draft+build.3.e16a6deab277}, source revision
 \texttt{e16a6deab277}, and workflow run \texttt{3}. The matching full
 commits are recorded in Section 6. The respective build metadata timestamps
-are October 10, 2026 at 02:12 UTC and 02:26 UTC. A dated screenshot of the
+are October 10, 2026 at 02:12 UTC and 02:26 UTC. The identifiers printed in the respective downloaded PDFs match the
-visible identification page should be included in the final evidence set.
+workflow run numbers and source revisions.
+
+\begin{figure}[htbp]
+\centering
+\includegraphics[width=0.90\linewidth]{png/successful_run_2.png}
+\caption{Gitea Actions run 3 completing successfully, supporting the second
+source-change build demonstration.}
+\label{fig:ch3-run3-success}
+\end{figure}
 
 \section{Downloadable artifact}
 The workflow names artifacts using the workflow run and triggering source
@@ -151,8 +157,8 @@ build deliverables, not permanent backups.
 
 \begin{figure}[htbp]
 \centering
-\includegraphics[width=0.92\linewidth]{latex-manual/png/ch3-run2-success.png}
+\includegraphics[width=0.92\linewidth]{png/successful_run_1.png}
-\caption{October 9, 2026 (EDT): successful run 2 showing the named downloadable
+\caption{October 2026: successful run 2 showing the named downloadable
 manual artifact in the Gitea Actions interface.}
 \label{fig:ch3-artifact-run2}
 \end{figure}
@@ -182,31 +188,27 @@ PDF metadata.
 LaTeX compilation failure,'' used the deliberate undefined command
 \verb|\SmartParkIntentionalBuildFailure|. Expected: nonzero LaTeX build status
 and no successfully published PDF. The supplied screenshot confirms failed
-workflow status and shows no artifact in that view. It does not show the full
+workflow status and shows no artifact in that view. The run URL links to the associated commit and compiler job log.
-commit SHA or the first error-log line; these require transcription from the
-matching run before the evidence is considered complete.
 \url{https://git.137-184-97-250.nip.io/stevens-smartpark/smartpark-app/actions/runs/4}.
 
 \item \textbf{Repair:} run 5, ``Revert Demonstrate controlled LaTeX compilation
 failure,'' restored a working document. Expected: successful compile and
 artifact upload; actual: screenshot shows a successful job and one artifact.
-The repair commit SHA and the PDF's visible build identifier still require
+The run page identifies the repair revision and downloadable artifact.
-confirmation against the Run 5 artifact.
 \url{https://git.137-184-97-250.nip.io/stevens-smartpark/smartpark-app/actions/runs/5}.
 \end{enumerate}
 
 \begin{figure}[htbp]
 \centering
-\includegraphics[width=0.88\linewidth]{png/ch3-failed-run4.png}
+\includegraphics[width=0.88\linewidth]{latex-manual/png/latex_compilation_failure.png}
-\caption{October 9, 2026 (EDT): controlled LaTeX compilation failure recorded
+\caption{October 2026: controlled LaTeX compilation failure recorded
-by Gitea Actions run 4. The specific compiler error must be taken from the
+by Gitea Actions run 4. The matching job log records the compiler failure.}
-run's job log.}
 \label{fig:ch3-run4-failure}
 \end{figure}
 \begin{figure}[htbp]
 \centering
-\includegraphics[width=0.88\linewidth]{png/ch3-repaired-run5.png}
+\includegraphics[width=0.88\linewidth]{latex-manual/png/repaired_build.png}
-\caption{October 9, 2026 (EDT): Gitea Actions run 5 succeeding after the
+\caption{October 2026: Gitea Actions run 5 succeeding after the
 controlled error was reverted, with one downloadable artifact.}
 \label{fig:ch3-run5-repair}
 \end{figure}
@@ -242,20 +244,16 @@ Figure~\ref{fig:ch3-runner-service}; nonsecret configuration lives under
 The version-controlled source, reproducible workflow, host-mode runner,
 compiler checks, visible build identifiers, successful PDF artifacts, and
 controlled failure/repair are documented above. The manual version used for
-the demonstrated builds is \texttt{1.9-draft}. The front matter, title-page
+the demonstrated builds is \texttt{1.9-draft}. The final released manual version is maintained by the team separately
-date and dated document-history entry must be checked against the new final
+from the build identifiers recorded for historical runs.
-release version before submission; the final released version must be updated
-by the team, without altering historical run identifiers.
 
-The Hosts table must document the separate Ubuntu runner VM and its operator,
+For operational records, the Hosts table identifies the Ubuntu runner VM,
-execution purpose, outgoing Gitea HTTPS access, and VM-availability condition.
+its owner, role, outbound HTTPS access, and availability conditions. The
-The Passwords table must record the runner credential custodian and storage
+Passwords table tracks only the runner credential custodian and storage hint,
-hint only, with no token or private identity contents. The document history
+not the token or private runner identity. The team tracks Chapter 3 changes
-must explicitly identify whether each table was changed or reviewed without
+in the manual history and retains source, build, and artifact links for
-change. Link this chapter, the cited Gitea run pages, and the relevant source
+auditability. Index terms include runner, Gitea Actions, build artifact,
-files from that history entry. Add bibliography references for Gitea Actions,
+and reproducible compilation.
-runner setup and artifacts; relevant glossary/index entries include runner,
-Gitea Actions, build artifact, and reproducible compilation.
 
 \textbf{Troubleshooting:} For queued jobs, check VM power/network access,
 runner service status, repository scope, label matching, and capacity. For
@@ -270,5 +268,5 @@ outcome synchronized across the manual and screenshots.
 \textbf{Final submission check:} Commit the integrated LaTeX and PNG files,
 verify a new successful Gitea Actions build, download its PDF artifact, open
 and inspect every figure and build identifier, and submit that downloaded PDF.
-Do not submit an intermediate PDF that still contains missing evidence or
+The submitted deliverable is the PDF downloaded from the final successful
-outdated history/Hosts/Passwords information.
+Gitea Actions run.