diff --git a/manual/development.tex b/manual/development.tex index 79184b95..2c680dce 100644 --- a/manual/development.tex +++ b/manual/development.tex @@ -20,6 +20,49 @@ \subsection{Visual Studio Code} updated as versions of .Net Core and VSCode change over time. +\subsection{GitHub Workflows} + +The GitHub workflows are part of the official CxAnalytix repository that are used to build and publish release and pre-release builds. Forks of the CxAnalytix +repository can also use these workflows to build and publish release artifacts.\footnote{GitHub will, by default, disable the workflows on forks. You will need token +visit the \texttt{Actions} tab of your repository to enable the workflows.} + +\noindent\\By default, the \texttt{build-ci} workflow executes on pushes, pull requests, or pull request updates on any branch. The CI build is meant to +assure that code changes have not broken the build process. No artifacts are published as part of the CI build. + +\noindent\\The \texttt{build-release} and \texttt{build-prerelease} workflows are used to publish release and pre-release artifacts. Platform specific zip and pdf +artifacts are published in the code Releases section of GitHub. A Docker image is also published in the owning organization's GitHub packages repository as +\\\texttt{cxanalytix/cxanalytix:\textit{}}. Each workflow requires the following Action secrets to be defined: + +\begin{table}[h] + \caption{GitHub Action Secrets} + \begin{tabularx}{\textwidth}{ll} + \toprule + \textbf{Secret Name} & \textbf{Description} \\ + \midrule + \texttt{PACKAGE\_PAT} & \makecell[l]{A personal access token that has the appropriate permissions\\to perform build operations.} \\ + \midrule + \texttt{PACKAGE\_USER} & The user associated with the PAT. \\ + \bottomrule + \end{tabularx} +\end{table} + +\noindent\\The package PAT requires the permissions that allow the following build operations:\\ + +\begin{enumerate} + \item Set and delete tags on the CxAnalytix repository. + \item Publish releases for the CxAnalytix repository. + \item Publish packages in the CxAnalytix repository's owning organization. +\end{enumerate} + +\subsubsection{Invoking the GitHub Release and Pre-Release Workflows} + +\noindent\\The \texttt{build-release} and \texttt{build-prerelease} workflows are typically manually invoked by navigating to \texttt{Actions} +and highlighting the workflow that is to be invoked. The \texttt{Run Workflow} button on the right side of the screen, as shown in the screen +shot below, allows a branch to be chosen and a release version to be defined. If everything executes correctly, a release or pre-release +is published and the repository is tagged. + +\noindent\\\includegraphics[scale=.4]{graphics/github-workflow.png} + \section{Developing New Modules} The transformation and output modules are dynamically loaded at runtime. They are developed with an SDK component included in the CxAnalytix source tree. diff --git a/manual/graphics/github-workflow.png b/manual/graphics/github-workflow.png new file mode 100755 index 00000000..dd3eb452 Binary files /dev/null and b/manual/graphics/github-workflow.png differ