tex-framework/content.tex

\section{Gitlab workflow} \label{sec:glw}

\begin{figure}
	\begin{center}
		\input{img_gitlab.tex}
		\caption{Gitlab workflow}
		\label{fig:gitlab_workflow}
	\end{center}
\end{figure}

Figure \ref{fig:gitlab_workflow} gives an overview of the gitlab workflow.
The workflow is splitted in different phases:\\

\begin{itemize}
	\item Implementation phase
	\item Code freeze
	\item Release phase
\end{itemize}

For these different phases The continuous integration/delivery system
triggers different build stages. For further details please refer to
section \ref{sec:ci}.

\subsection{Implementation phase}

While in implementation phase every implementation for the next release is
done. Every implementation has to be done on a seperate branch. After
finishing an implementation the branch it was made on has to be merged back
to the master branch. As defined an implementation could be one of:\\

\begin{itemize}
	\item Feature
	\item Fix
\end{itemize}

\subsubsection{Feature implementation}

A feature is a a new piece of code that implements new functionality into
the system.

\subsubsection{Fix implementation}

If in any testing phase an issue is detected these issue can be fixed with
a fix implementation.

\subsubsection{Further kinds of implementation}

Beside these defined implementations any other kind of implementation is
possible but has to be made also on a seperate branch.

\subsection{Code freeze}

The transition between implementation phase and release phase is called
code freeze. Code freeze means each for the upcoming release planned
feature is implemented and merged to the main branch (normally master) of
the project's git repository (see figure \ref{fig:gitlab_workflow}). For
the upcoming release a "\texttt{release/...}" named branch is created.
For a proper release configuration it is necessary to configure the ci
build job before creating the release branch (see section \ref{sec:ci_conf})
.

\subsection{Release phase}

Any release relevant issue that is detected while release phase has to be
fixed at the release branch. The release phase is splitted into different
stages:

\begin{itemize}
	\item Internal release(s)
	\item External release
\end{itemize}

\subsubsection{Internal release(s)}

Each push to a release branch triggers the creation of an internal release.
Only internal releases must be used to system test the release branch. For
details please refer to section \ref{sec:ci_int}.

\subsubsection{External release}

If no further release relevant issues could be found (or are accepted as
known issues) an external release is created by tagging the commit which
should be delivered to the customer. For details please refer to section
\ref{sec:ci_ext}.

\section{Continuous integration/delivery} \label{sec:ci}

As continuous integration system the gitlab built in ci-system
\textit{gitlab-ci} is used. Beside the most important task of ci, ensure
constant high code quality, the ci system is used for various tasks:

\FloatBarrier
\begin{itemize}
	\item Automated static code analysis
	\item Automated build
	\item Automated test (not implemented yet)
	\item Internal release deployment
	\item External release deployment
	\item Automated release note generation (not implemented yet)
\end{itemize}
\FloatBarrier

\subsection{Internal release deployment} \label{sec:ci_int}

\begin{figure}
	\begin{center}
		\input{img_deploy.tex}
		\caption{Deployment of release candidats and releases}
		\label{fig:deployment}
	\end{center}
\end{figure}

For a branch named \texttt{release/...} the creation of a release candidate
is triggered automatically. Figure \ref{fig:deployment} illustrates the
deployment process. The internal release is processing the following steps:
\\

\begin{enumerate}
	\item Build project variant specific configuration
	\item Static code analysis of project variant specific configuration
	\item Name the release depending on the release naming convention
	\item Build release notes for the release candidate
	\item Deploy the release to the project's release candidate deploy
location
\end{enumerate}

\subsection{External release deployment} \label{sec:ci_ext}

To create an external release the commit to be released must be tagged
using the following naming convention:\\
\texttt{release/<project\_specific\_name>}.\\
The project specific naming convention for Agricola ruby is:\\
\texttt{release/174\_AG*}.\\

\begin{enumerate}
	\item Build project variant specific configuration
	\item Static code analysis of project variant specific configuration
	\item Name the release depending on the release naming convention
	\item Build release notes for the release
	\item Deploy the release to the project's release deploy location
\end{enumerate}

\subsection{Release note generation} \label{sec:rel_note}

\begin{figure}
	\begin{center}
		\input{img_history.tex}
		\caption{Git commit history}
		\label{fig:git_commit_history}
	\end{center}
\end{figure}

To generate release notes by commit messages special tagged commit messages
are used. Release notes are generated for release candidats and releases.
For release candidats (internal releases) more tags are analyzed. The
definition of the commit tag rules are somewhere in the Polarion :) Because
the release notes content is taken from the log history of a release branch
each commit in it's history has to use tagged commits. To show logs only of
direct parents (commits on the current release branch and commits on the
master) the log command\\
\texttt{git log <first\_commit>..HEAD --first parent master}\\
can be used. Figure \ref{fig:git_commit_history} illustrates the flow of the
log history of the release branch shown in figure \ref{fig:gitlab_workflow}.

\subsection{Configuring the build jobs} \label{sec:ci_conf}

The configuration of gitlab-ci is made in the \texttt{.gitlab-ci.yml} file
in the root directory of the project's repository. The certain build stages
are using variables to customize the build. These variables are defined in
the \texttt{variables} section of the config file. Table \ref{tab:conf_var}
and listing \ref{lst:ag_cfg} gives an overview about customizing a release
phase.

\captionof{table}{Variables to customize a release phase}
\label{tab:conf_var}
\begin{tabular}{l l l}
	\cellcolor{black}\color{white}variable & \cellcolor{black}\color{white}meaning & \cellcolor{black}\color{white}example\\
	PRODUCT\_NAME & Short of the product name & AG\\
	PRODUCT\_VARIANT & Short of the product variant & NA\\
	PROJECT\_VERSION & ?? & 10\\
	SW\_MAJOR & Software major number & 1\\
	SW\_MINOR & Software minor number & 2\\\\
\end{tabular}
\newline

\lstsetbash
\begin{lstlisting}[caption=variables configuration, label=lst:ag_cfg]
variables:
  PRODUCT_NAME: "AG"
  PRODUCT_VARIANT: "NA"
  PROJECT_VERSION: "10"
  SW_MAJOR: "1"
  SW_MINOR: "2"
\end{lstlisting}