aswi2023brainstorm-gitlab/doc/internal/doc.tex @ f314eab4

\documentclass[12pt, a4paper]{article}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%-----------------------VYUŽITÉ PACKAGES----------------------------%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage[czech]{babel}
\usepackage{geometry}
\usepackage[final]{graphicx}
\usepackage{anyfontsize}
\usepackage{setspace}
\usepackage{hyperref}
\usepackage[T1]{fontenc}
\usepackage{subcaption}
\hypersetup{
    colorlinks,
    citecolor=black,
    filecolor=black,
    linkcolor=black,
    urlcolor=black
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%-----------------------ZAČÁTEK VLASTNÍHO TEXTU---------------------------%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}

\begin{titlepage}
\title{
\vspace{-4cm}\hspace{-10cm}
\includegraphics[width=8cm]{assets/logo.png} \\
\vspace{5cm}
\begingroup
\setstretch{4}\fontsize{30}{10}\selectfont\fontdimen2\font=0.8ex
\parbox{13.3cm}{
    \centering{\textbf{ASWI - Neurorehablitační systém BrainIn}\\
    \fontsize{24}{10}\selectfont\centering{{Interní týmové předpisy a dokumentace}}
}}
\endgroup}
\date{}
\author{}
\maketitle \thispagestyle{empty}
\vspace{3cm}
\hspace{0cm}\parbox[b][5cm][b]{8cm}{{\setstretch{1.5}
Autor: Bc. Jan Hereš\\
Datum: 27.02.2023\\
Poslední úprava: \today\\}}
\end{titlepage}
\newpage


\tableofcontents
\newpage

\section{Úvod}
\paragraph{} Tento dokument slouží jakožto analogie ,,interních směrnicí'' pro sjednocení a ustálení vývojových procesů napříč celým týmem.

\section{Interní management}
\paragraph{} V rámci řízení projektu bylo ustanoveno, že se tým bude \textbf{pravidelně} scházet v on-site/online formě \textbf{každé úterý od 13:00 do 14:00} (tzv. \textit{weekly-standups; případně každý čtvrtek v závislosti na možnostech všech zúčastněných)}. V rámci těchto schůzek bude probrána odvedená a naplánovaná práce, případně jakákoliv nastávající problematika. Z těchto meetingů bude \textbf{vždy} vytvořen ,,záznam ze schůzky dne XXX'', který bude součástí dokumentu se všemi takovými záznamy. 

\section{Verzovací systém Git}
\paragraph{} Tato sekce se týká verzovacího systému Git (potažmo repozitáře Gitlab). 
Vzhledem k faktu, že je již od začátku aplikace vyvíjena pro české pacienty, terapeuty, \dots (a z důvodu zachování již zaběhlých konvencí) budou veškeré komentáře, názvy a komunikace popsány v \textbf{českém} jazyce.

\subsection{Tvorba vývojových větví (\textit{branches})}
\paragraph{} V rámci projektu existuje hlavní vývojová větev \textbf{master}.
V této větvi budou dostupné veškeré \textbf{funkční a otestované} verze projektu ve formě otagovaných \textbf{releases}.
Nadále bude existovat větev \textbf{development (dev)}, na které bude dostupná \textbf{poslední} upravená, fuknční a neotestovaná verze.
Ve chvíli, kdy bude verze na development větvi otestována, může být vytvořen merge request do hlavní větve (za předpokladu, že jsou splněny všechny požadavky na novou verzi).
Pro nové \textit{features} nebo pro \textit{change requests} bude vždy vytvořena \textbf{nová} separátní větev z development větve.
Workflow mezi jednotlivými větvemi je vyobrazen na obrázku \ref{fig:branches_workflow}.

\begin{figure}[h]
    \centering
    \includegraphics[width=\linewidth]{assets/aswi_branches.png}
    \caption{Workflow mezi jednotlivými větvemi v rámci repozitáře}
    \label{fig:branches_workflow}
\end{figure}


\subsection{Tvorba a správa úkolů (\textit{Tickets and Issues})}
\paragraph{} Každý úkol bude mít svůj \textit{ticket} (v případě, že je tak obsáhlý, že se bude muset dále dělit na podúkoly).
Pokud bude úkol ,,jednoduchý'' (tj. nebude vyžadovat žádnou, případně velice minimální dekompozici), bude k němu adresována daná \textit{issue}. 

\subsubsection{Issues (Tickets)}
\paragraph{} Ticketem se rozumí takový úkol, který je nutné dekomponovat do menší, ideálně atomických podúkolů.
Samotný ticket bude reprezentován v repozitáři jakožto \textit{issue}, nicméně v rámci jeho popisů (\textit{Tasks}) bude výčet všech úkolů (volně popsaných), které je nutné splnit.
V rámci Ticketu bude využito i sekce \textit{Linked Items}, kde budou linknuté konkrétní podúkoly ve formě jednotlivých \textit{issues} (přesná korelace mezi sekcí \textit{Tasks a Linked Items} je tedy zřejmá).
\par Z pragmatického hlediska bude tedy Ticket pouze speciální issue, která agreguje veškeré logicky související podúkoly. 

\subsubsection{Issues (Tasks)}
\paragraph{} Jak bylo již řečeno výše, \textit{issue} bude buďto jednoduchý úkol, který je součástí daného \textit{tasku}. 
Pravidla pro vytváření těchto úkolů:
\begin{itemize}
    \item Každá \textit{issue} bude obsahovat krátký, nicméně dostatečně deskriptivní popis, čeho konkrétně se týká
    \item Každá \textit{issue} bude \textbf{jednoznačně identifikovatelná} za pomocí tzv. \textbf{labelů} (specifikováno dále)
    \item Každá \textit{issue}, která bude v jiné, než \textbf{Backlog} fázi (specifikováno dále) bude \textbf{jednoznačně přiřazena} danému vývojáři (případně testerovi či zákazníkovi, bude-li třeba)
    \item Každá \textit{issue} bude označena jednou z možností \textbf{,,urgentnosti''} (viz dále)
    \item U každé issue, které je ve fázi ,,In progress'', či dále, bude jednoznačně stanoveno datum, kdy by měl být úkol dokončen (neměl by přesáhnout koncové datum iterace, v rámci které je úkol řešen)
    
\end{itemize}

\paragraph{Jednotlivé fáze úkolů}
\begin{itemize}
    \item Backlog - analogie s TODO
    \item In progress
    \item To test (dev) - testování \textbf{vždy provádí jiný vývojář/tester!} 
    \item Code review 
    \item To deploy (dev) - funkcionalita implementována, nicméně je nutné funkční verzi \textit{deploynout} na testovací prostředí k umožnění testování
    \item To test (prod) - otestování na produkčním prostředí
    \item To deploy (prod) - končí schválením merge requestu do \textbf{masteru}
    \item Done - Issue hotova, uzavřena 
\end{itemize}

\paragraph{} Poznámka: Ze stavu ,,To deploy (dev)'' lze přejít do stavu ,,Done'', pokud není žádoucí ovlivňovat produkční prostředí (zejména pro malé změny, které budou součástí větší úpravy). 


\paragraph{Typy issues}
\begin{itemize}
    \item Epic - velký logický blok, který obaluje novou funkcionalitu nebo velké množství úprav
    \item Feature - nová funkcionalita (zejména front-endové změny)
    \item Ticket - jakýkoliv další úkol, který implicitně není novou funkcionalitou, spíše například vytvoření obsáhlejší dokumentace, případně nových tříd či struktur
    \item Task - základní úkol (ideálně atomický); využití na rozdělení ticketu do menších podúkolů
    \item Bug - Chyba, kterou je nutno opravit
    \item Change request - vyžádaná změna od zákazníka/uživatele, která byla již dříve implementována 
\end{itemize}

\paragraph{Typy priority/urgentnosti}
\begin{itemize}
    \item \textbf{Low} - nevyžaduje velkou pozornost (příkladem mohou být nekritické části aplikace, ,,nice to have(s)''),
    \item \textbf{Medium} - vyžaduje vyšší míru pozornosti - již by neměly zůstávat nedokončeny v rámci přiřazené iterace (v krajních případech je možné posunout do další),
    \item \textbf{High} - vysoká priorita vyžadujicí privilegované řešení,
    \item \textbf{Severe} - maximální důležitost - vyžaduje okamžité řešení (například v případech, kdy tyto problémy způsobují nestabilitu či přímo rozbíjí produkční prostředí)
\end{itemize}

\paragraph{} V rámci jakýchkoliv úkolů \textbf{není potřeba} vést časové údaje a odhady. Tato činnost bude probíhat v systému \textbf{Jira}.


\section{Aplikace pro řízení projektů - Jira}
\paragraph{} Pro účely předmětu ASWI bylo schváleno garantem předmětu doc.Ing. Přemyslem Bradou, MsC., Ph.D. a vedoucími projektu použití nástroje \textbf{Jira} pro správu vývoje a projektu.
Pro sjednocení vývojového procesu byl vytvořen následující projektový workflow:

\begin{figure}
    \centering
    \includegraphics[width=\linewidth]{assets/jira_workflow.png}
    \caption{Projektový workflow v systému Jira}
\end{figure}

\paragraph{} Poznámka: Je tedy zřejmé, že tento workflow přesně koreluje s navrženou stukturou repozitáře projektu.


% \cite{Example}


% \clearpage
% \section{Závěr}

% \newpage
% \bibliographystyle{unsrt}
% {\raggedright\small
% \bibliography{literatura}
% }

\end{document}