First draft of the version control section and figure complete

The figure was greatly improved, becoming much more clear and descriptive
of some of the main advantages of having version control in a complete
project like Maneage.

6 files changed, 110 insertions, 88 deletions

diff --git a/paper.tex b/paper.tex
index 0a85da2..167dea3 100644
--- a/paper.tex
+++ b/paper.tex
@@ -1270,35 +1270,55 @@ This style of managing project parameters therefore produces a much more healthy
 
 Maneage is fully composed of plain-text files distributed in a directory structure (see Sections \ref{principle:text} \& \ref{sec:generalimplementation} and Figure \ref{fig:files}).
 Therefore it can be maintained under under version control systems like Git (for more on version control, see Appendix \ref{appendix:versioncontrol}).
-Every commit in the version controlled history contains a complete snapshot of the executable data lineage, for more see the completeness principle in Section \ref{principle:complete}.
-Maneage is maintained by its developers in a central branch, which we'll call \inlinecode{maneage} hereafter.
+Every commit in the version controlled history contains \emph{a complete} snapshot of the data lineage, for more see the completeness principle in Section \ref{principle:complete}.
 
-The \inlinecode{maneage} branch contains all the low-level infrastructure that is necessary for any project; primarily the configuration features discussed in Section \ref{sec:projectconfigure} that are located under \inlinecode{reproduce/software} in Figure \ref{fig:files}, and executed with the \inlinecode{./project configure} command.
-The main branch only contains a minimal/demonstration analysis in order to be complete.
-The names of all the files related to the demonstration of the \inlinecode{maneage} branch have a \inlinecode{delete-me} prefix to highlight that they must be deleted when starting a new project.
+Maneage is maintained by its developers in a central branch, which we'll call \inlinecode{man\-eage} hereafter.
+The \inlinecode{man\-eage} branch contains all the low-level infrastructure, or skeleton, that is necessary for any project.
+This skeleton is primarily the configuration features discussed in Section \ref{sec:projectconfigure}\footnote{Recall that project configuration files are located under \inlinecode{reproduce/software} in Figure \ref{fig:files}, and executed with the \inlinecode{./project configure} command.}.
+The \inlinecode{maneage} branch only contains a minimal demonstration analysis in order to be complete\footnote{The names of all the files related to the demonstration of the \inlinecode{maneage} branch have a \inlinecode{delete-me} prefix to highlight that they must be deleted when starting a new project.}.
 
 To start a new project, users simply clone it from its reference repository and build their own Git branch over the most recent commit.
-They can then start customizing Maneage for their project in their own branch, and push that branch to their own Git repository for management.
-Project customization will usually start with deleting the demonstration files that have a \inlinecode{delete-me} prefix, and adding their own input datasets, analysis and narrative instead.
+This is demonstrated in the first phase of Figure \ref{fig:branching}: the project started by branching of commit \inlinecode{0c120cb} in \inlinecode{maneage}.
+They can then start customizing Maneage for their project and adding their high-level analysis in their own branch and push it to their own Git repository.
 Manages contains a file called \inlinecode{README-hacking.md} that has a complete checklist of steps to start a new project and remove demonstration parts.
-This file is updated on the \inlinecode{maneage} branch and will always be uptodate with the low-level infrastructure.
+This file is updated on the \inlinecode{maneage} branch and will always be up-to-date with the low-level infrastructure.
 
+%% Exact URLs of imported images.
+%% Collaboration icon: https://www.flaticon.com/free-icon/collaboration_809522
+%% Paper done:         https://www.flaticon.com/free-icon/file_2521838
+%% Paper processing:   https://www.flaticon.com/free-icon/file_2521989
 \begin{figure}[t]
   \includetikz{figure-branching}
   \vspace{-3mm}
-  \caption{\label{fig:branching} Schematic view of main Maneage branch, and how new projects start by branching off of it in two scenarios: pre-publicatioin (allowing easy collaboration) and post-publication (allowing other scientists to easily build upon each other's published work).
-    In the pre-publication scenario, another co-author has made two commits in parallel to the main author, which have later been merged as the project evolves.
-    In the post-publication scenario, another scientist builds upon the published work of another scintist, then merges with the Maneage branch to improve the low-level infrastructure.
+  \caption{\label{fig:branching} Projects start by branching off the main Maneage branch and developing their high-level analysis over the common low-level infrastructure: add flesh to a skeleton.
+    The low-level infrastructure can always be updated (keeping the added high-level analysis intact), with a simple merge between branches.
+    Two phases of a project's evolution shown here: in phase 1, a co-author has made two commits in parallel to the main project branch, which have later been merged.
+    In phase 2, the project has finished: note the identical first project commit and the Maneage commits it branches from.
+    The dashed parts of Scenario 2 can be any arbitraty history after those shown in phase 1.
+    A second team now wants to build upon that published work in a derivate branch, or project.
+    The second team applies two commits and merges their branch with Maneage to improve the skeleton and continue their research.
+    The Git commits are shown on their branches as colored ellipses, with their hash printed in them.
+    The commits are colored based on the team that is working on that branch.
+    The collaboration and paper icons are respectively made by `mynamepong' and `iconixar' and downloaded from \url{www.flaticon.com}.
   }
 \end{figure}
 
-Having the uniform Maneage branch at the core of all projects that use it has the following benefits:
+After a project starts, Maneage will evolve.
+For example new features will be added, low-level bugs will be fixed that are useful for any project.
+Because all the changes in Maneage are committed on the \inlinecode{maneage} branch (that projects also branch-off from) updating the project's low-level infra-structure is as easy as merging the \inlinecode{maneage} branch into the project's branch.
+For example see how Maneage's \inlinecode{3c05235} commit has been merged into project's branch trough commit \inlinecode{2ed0c82} in Figure \ref{fig:branching} (phase 1).
+
+This doesn't just apply to the pre-publication phase, when done in Maneage, a project can be revived at any later date by other researchers as shown in phase 2 of Figure \ref{fig:branching}.
+In that figure, a new team of researchers have decided to experiment on the results of the published paper and have merged it with the Maneage branch (commit \inlinecode{a92b25a}) to fix some possible portability problem for their operating system that was fixed as a bug in Maneage after the paper's publication.
+Propagating bug fixes or improvements in the low-level infrastructure to all projects using Maneage has been one of the reasons it evolved so well over the last 5 years, see Section \ref{sec:futurework}.
+As we started using it in more projects by more users, many bugs were found and improvements made.
+We would then implement it in Maneage and that fix would propagate to all other projects automatically in their next merge.
+
+Modern version control systems provide many more capabilities that can be exploited through Maneage, and the shared branch it has with \emph{all} projects that use it.
+For example a third project can easily merge various high-level components from different projects into its own branch, thus adding a temporal dimension to their data lineage.
+
+
 
-\begin{itemize}
-\item The project's infrastructure can be updated even after publication, when the operating systems or hardware may not be compatible with the project's core components.
-\item Other projects can branch-off an existing project and update their infrastructure while retaining the high-level analysis that they will edit.
-\item Merging work from multiple projects can be as easy as merging their branches: they all share the common \inlinecode{maneage} branch.
-\end{itemize}
 
 
 \subsection{Collaborating with same build directory}
@@ -1325,7 +1345,7 @@ Once the project is complete, publishing the project (its narrative report as we
 
 
 \subsection{Future of Maneage and its past}
-\label{sec:futureworkx}
+\label{sec:futurework}
 As with any software, the core architecture of Maneage will inevitably evolve after the publication of this paper.
 The current version introduced here has already experienced 5 years of evolution and several reincarnations.
 Its primordial implementation was written for \citet{akhlaghi15}.
@@ -1410,10 +1430,6 @@ Once the improvements become substantial, new paper(s) will be written to comple
 Work on the reproducible paper template has been funded by the Japanese Ministry of Education, Culture, Sports, Science, and Technology ({\small MEXT}) scholarship and its Grant-in-Aid for Scientific Research (21244012, 24253003), the European Research Council (ERC) advanced grant 339659-MUSICOS, European Union’s Horizon 2020 research and innovation programme under Marie Sklodowska-Curie grant agreement No 721463 to the SUNDIAL ITN, and from the Spanish Ministry of Economy and Competitiveness (MINECO) under grant number AYA2016-76219-P.
 The reproducible paper template was also supported by European Union’s Horizon 2020 (H2020) research and innovation programme via the RDA EU 4.0 project (ref. GA no. 777388).
 
-%% Collaboration icon: https://www.flaticon.com/free-icon/collaboration_809522?term=collaboration&page=1&position=36
-%% Paper icon: https://www.flaticon.com/free-icon/paper_2541979?term=paper&page=1&position=28
-The collaboration and paper icons in Figure \ref{fig:branching} were respectively made by `mynamepong' and `freepik' and downloaded from \url{www.flaticon.com}.
-
 %% Tell BibLaTeX to put the bibliography list here.
 \printbibliography
 
diff --git a/tex/img/collaboration-icon.pdf b/tex/img/icon-collaboration.pdf
index 7bb5795..7bb5795 100644
--- a/tex/img/collaboration-icon.pdf
+++ b/tex/img/icon-collaboration.pdf
diff --git a/tex/img/icon-complete.pdf b/tex/img/icon-complete.pdf
new file mode 100644
index 0000000..a19970f
--- /dev/null
+++ b/tex/img/icon-complete.pdf
diff --git a/tex/img/icon-processing.pdf b/tex/img/icon-processing.pdf
new file mode 100644
index 0000000..d69cee2
--- /dev/null
+++ b/tex/img/icon-processing.pdf
diff --git a/tex/img/paper-icon.pdf b/tex/img/paper-icon.pdf
deleted file mode 100644
index db7660c..0000000
--- a/tex/img/paper-icon.pdf
+++ /dev/null
diff --git a/tex/src/figure-branching.tex b/tex/src/figure-branching.tex
index bc6fb41..e264746 100644
--- a/tex/src/figure-branching.tex
+++ b/tex/src/figure-branching.tex
@@ -31,110 +31,116 @@
 
   %% Just for a reference (so the image size always remains fixed). It also
   %% helps in defining easy coordinates for all the other elements.
-  \draw [white] (0,0) -- (0,10cm);
+  \draw [white] (0,0) -- (0,8cm);
   \draw [white] (0,0) -- (\linewidth,0);
 
   %% Maneage branch line.
-  \draw [black!40!white, dashed, line width=2mm] (2cm,0) -- (2cm,0.6cm);
-  \draw [->, black!40!white, line width=2mm] (2cm,0.6cm) -- (2cm,7.9cm);
-  \draw [anchor=south, black!20!white] (2cm,4cm) node [rotate=90, scale=2]
-        {\bf Maneage branch};
+  \draw [black!40!white, dashed, line width=2mm] (1.5cm,0) -- (1.5cm,0.6cm);
+  \draw [->, black!40!white, line width=2mm] (1.5cm,0.6cm) -- (1.5cm,7.9cm);
+  \draw [anchor=north, black!40!white] (1.5cm,0.1cm) node [scale=1.5]
+        {\bf Maneage};
 
   %% Project branch line.
   \draw [->, black!40!white, rounded corners, line width=2mm]
-        (2cm,2cm) -- (3.5cm,2.5cm) -- (3.5cm,7.9cm);
-  \draw [black!40!white, line width=2mm] (2cm,5cm) -- (3.5cm,5.5cm);
-  \draw [anchor=south, black!20!white] (3.5cm,5cm) node [rotate=90, scale=2]
-        {\bf Project branch};
+        (1.5cm,2cm) -- (3cm,2.5cm) -- (3cm,7.9cm);
+  \draw [black!40!white, line width=2mm] (1.5cm,5cm) -- (3cm,5.5cm);
+  \draw [anchor=north, black!40!white] (3cm,2.3cm) node [scale=1.5]
+        {\bf Project};
 
   %% Derivative project
   \draw [black!40!white, rounded corners, line width=2mm]
-        (3.5cm,4.5cm) -- (5cm,5cm) -- (5cm,6cm) -- (3.5cm,6.5cm);
+        (3cm,4.5cm) -- (4.5cm,5cm) -- (4.5cm,6cm) -- (3cm,6.5cm);
 
   %% Maneage commits.
-  \branchcommit{green!70!blue}{2cm}{1cm}{1d72e26}
-  \branchcommit{green!70!blue}{2cm}{2cm}{0c120cb}
-  \branchcommit{green!70!blue}{2cm}{3cm}{5781173}
-  \branchcommit{green!70!blue}{2cm}{4cm}{0774aac}
-  \branchcommit{green!70!blue}{2cm}{5cm}{3c05235}
-  \branchcommit{green!70!blue}{2cm}{6cm}{6ec4881}
-  \branchcommit{green!70!blue}{2cm}{7cm}{852d996}
+  \branchcommit{green!70!blue}{1.5cm}{1cm}{1d72e26}
+  \branchcommit{green!70!blue}{1.5cm}{2cm}{0c120cb}
+  \branchcommit{green!70!blue}{1.5cm}{3cm}{5781173}
+  \branchcommit{green!70!blue}{1.5cm}{4cm}{0774aac}
+  \branchcommit{green!70!blue}{1.5cm}{5cm}{3c05235}
+  \branchcommit{green!70!blue}{1.5cm}{6cm}{6ec4881}
+  \branchcommit{green!70!blue}{1.5cm}{7cm}{852d996}
 
   %% Project commits.
-  \branchcommit{red!60!green}{3.5cm}{2.5cm}{4483a81}
-  \branchcommit{red!60!green}{3.5cm}{3.5cm}{5e830f5}
-  \branchcommit{red!60!green}{3.5cm}{4.5cm}{01dd812}
-  \branchcommit{red!60!green}{3.5cm}{5.5cm}{2ed0c82}
-  \branchcommit{red!60!green}{3.5cm}{6.5cm}{f62596e}
+  \branchcommit{red!60!green}{3cm}{2.5cm}{4483a81}
+  \branchcommit{red!60!green}{3cm}{3.5cm}{5e830f5}
+  \branchcommit{red!60!green}{3cm}{4.5cm}{01dd812}
+  \branchcommit{red!60!green}{3cm}{5.5cm}{2ed0c82}
+  \branchcommit{red!60!green}{3cm}{6.5cm}{f62596e}
 
   %% Derivate project commits.
-  \branchcommit{red!60!green}{5cm}{5cm}{f69e1f4}
-  \branchcommit{red!60!green}{5cm}{6cm}{716b56b}
-  \node[inner sep=0pt] at (4.5cm,7cm)
-       {\includegraphics[width=9mm]{tex/img/collaboration-icon.pdf}};
+  \branchcommit{red!60!green}{4.5cm}{5cm}{f69e1f4}
+  \branchcommit{red!60!green}{4.5cm}{6cm}{716b56b}
+  \node[inner sep=0pt] at (3.92cm,5.55cm)
+       {\includegraphics[width=6.5mm]{tex/img/icon-collaboration.pdf}};
 
+  %% Paper being processed icon. The white rectangle over it is to blend it
+  %% into the background.
+  \node[anchor=south,inner sep=0pt] at (3.92cm,6.7cm)
+       {\includegraphics[width=1cm]{tex/img/icon-processing.pdf}};
+  \draw[white, fill=white, opacity=0.7] (3.42cm,6.7) rectangle (5cm,7.7cm);
 
   %% Description of this scenario:
-  \draw [anchor=west, black] (2.7cm,1.5cm) node {\textbf{Scenario 1} (pre-publication):};
-  \draw [anchor=west, black] (2.8cm,1.1cm) node {\small Collaborating on a project while};
-  \draw [anchor=west, black] (2.8cm,0.7cm) node {\small working in parallel, then merging.};
+  \draw [rounded corners, fill=black!10!white] (3.1cm,0) rectangle (7.5cm,1.25cm);
+  \draw [anchor=west, black] (3.1cm,1.0cm) node {\small \textbf{Phase 1} (pre-publication):};
+  \draw [anchor=west, black] (3.3cm,0.6cm) node {\footnotesize Collaborating on a project while};
+  \draw [anchor=west, black] (3.3cm,0.2cm) node {\footnotesize working in parallel, then merging.};
+
+
+
 
 
 
-  %% Middle line.
-  \draw [black] (8cm,0.5) -- (8cm,7.5cm);
 
 
 
 
   %% Maneage branch line.
-  \draw [black!40!white, dashed, line width=2mm] (10cm,0) -- (10cm,0.6cm);
-  \draw [->, black!40!white, line width=2mm] (10cm,0.6cm) -- (10cm,9.9cm);
-  \draw [anchor=south, black!20!white] (10cm,4cm) node [rotate=90, scale=2]
-        {\bf Maneage branch};
+  \draw [black!40!white, dashed, line width=2mm] (9.5cm,0) -- (9.5cm,0.6cm);
+  \draw [black!40!white, line width=2mm] (9.5cm,0.6cm) -- (9.5cm,2.5cm);
+  \draw [black!40!white, line width=2mm, dashed] (9.5cm,2.5cm) -- (9.5cm,3.5cm);
+  \draw [->,black!40!white, line width=2mm] (9.5cm,3.5cm) -- (9.5cm,7.9cm);
+  \draw [anchor=north, black!40!white] (9.5cm,0.1cm) node [scale=1.5]
+        {\bf Maneage};
 
   %% Project branch line.
   \draw [black!40!white, rounded corners, line width=2mm]
-        (10cm,2cm) -- (11.5cm,2.5cm) -- (11.5cm,6.9cm);
-  \draw [black!40!white, line width=2mm] (10cm,5cm) -- (11.5cm,5.5cm);
-  \draw [anchor=south, black!20!white] (11.5cm,5cm) node [rotate=90, scale=2]
-        {\bf Project branch};
+        (9.5cm,2cm) -- (11cm,2.5cm) -- (11cm,3cm);
+  \draw [black!40!white, line width=2mm, dashed] (11cm,3cm) -- (11cm,4cm);
+  \draw [black!40!white, line width=2mm, dashed] (9.5cm,3cm) -- (11cm,3.5cm);
+  \draw [black!40!white, line width=2mm] (11cm,4cm) -- (11cm,4.9cm);
+  \draw [anchor=north, black!40!white] (11cm,2.3cm) node [scale=1.5]
+        {\bf Project};
 
   %% Derivative project
   \draw [->, black!40!white, rounded corners, line width=2mm]
-        (11.5cm,6.5cm) -- (13cm,7cm) -- (13cm,9.9cm);
-  \draw [black!40!white, line width=2mm] (10cm,8cm) -- (13cm,9cm);
-  \draw [anchor=south, black!20!white] (13cm,6.5cm) node [rotate=90, scale=2]
-        {\bf Derivative branch};
+        (11cm,4.5cm) -- (12.5cm,5cm) -- (12.5cm,7.9cm);
+  \draw [black!40!white, line width=2mm] (9.5cm,6cm) -- (12.5cm,7cm);
+  \draw [anchor=north, black!40!white] (12.7cm,4.8cm) node [scale=1.5]
+        {\bf Derivative};
+  \draw [anchor=north, black!40!white] (12.7cm,4.4cm) node [scale=1.5]
+        {\bf project};
 
   %% Maneage commits.
-  \branchcommit{green!70!blue}{10cm}{1cm}{1d72e26}
-  \branchcommit{green!70!blue}{10cm}{2cm}{0c120cb}
-  \branchcommit{green!70!blue}{10cm}{3cm}{5781173}
-  \branchcommit{green!70!blue}{10cm}{4cm}{0774aac}
-  \branchcommit{green!70!blue}{10cm}{5cm}{3c05235}
-  \branchcommit{green!70!blue}{10cm}{6cm}{6ec4881}
-  \branchcommit{green!70!blue}{10cm}{7cm}{852d996}
-  \branchcommit{green!70!blue}{10cm}{8cm}{13a1881}
-  \branchcommit{green!70!blue}{10cm}{9cm}{61b6b01}
+  \branchcommit{green!70!blue}{9.5cm}{1cm}{1d72e26}
+  \branchcommit{green!70!blue}{9.5cm}{2cm}{0c120cb}
+  \branchcommit{green!70!blue}{9.5cm}{4cm}{b47b2a3}
+  \branchcommit{green!70!blue}{9.5cm}{5cm}{340a7ec}
+  \branchcommit{green!70!blue}{9.5cm}{6cm}{a92b25a}
+  \branchcommit{green!70!blue}{9.5cm}{7cm}{6e1e3ff}
 
   %% Project commits.
-  \branchcommit{red!60!green}{11.5cm}{2.5cm}{4483a81}
-  \branchcommit{red!60!green}{11.5cm}{3.5cm}{5e830f5}
-  \branchcommit{red!60!green}{11.5cm}{4.5cm}{01dd812}
-  \branchcommit{red!60!green}{11.5cm}{5.5cm}{2ed0c82}
-  \branchcommit{red!60!green}{11.5cm}{6.5cm}{f62596e}
-  \node[inner sep=0pt] at (11.5cm,7.2cm) {\includegraphics[width=9mm]{tex/img/paper-icon.pdf}};
-  \draw [anchor=north, black] (11.5cm,8cm) node {\scriptsize Published};
+  \branchcommit{red!60!green}{11cm}{2.5cm}{4483a81}
+  \branchcommit{red!60!green}{11cm}{4.5cm}{\projectversion}
+  \node[anchor=south, inner sep=0pt, color=white] at (11.05cm,4.8cm) {\includegraphics[width=1cm]{tex/img/icon-complete.pdf}};
 
   %% Derivate project commits.
-  \branchcommit{purple!60!yellow}{13cm}{7cm}{b177c7e}
-  \branchcommit{purple!60!yellow}{13cm}{8cm}{5ae1fdc}
-  \branchcommit{purple!60!yellow}{13cm}{9cm}{bcf4512}
+  \branchcommit{purple!60!yellow}{12.5cm}{5cm}{b177c7e}
+  \branchcommit{purple!60!yellow}{12.5cm}{6cm}{5ae1fdc}
+  \branchcommit{purple!60!yellow}{12.5cm}{7cm}{bcf4512}
 
   %% Description of this scenario:
-  \draw [anchor=west, black] (10.7cm,1.5cm) node {\textbf{Scenario 2} (post-publication):};
-  \draw [anchor=west, black] (10.8cm,1.1cm) node {\small Other researchers building upon};
-  \draw [anchor=west, black] (10.8cm,0.7cm) node {\small previously published work.};
-
+  \draw [rounded corners, fill=black!10!white] (11.1cm,0) rectangle (15.3cm,1.25cm);
+  \draw [anchor=west, black] (11.1cm,1.0cm) node {\small \textbf{Phase 2} (post-publication):};
+  \draw [anchor=west, black] (11.3cm,0.6cm) node {\footnotesize Other researchers building upon};
+  \draw [anchor=west, black] (11.3cm,0.2cm) node {\footnotesize previously published work.};
 \end{tikzpicture}