From 2a787ccb7b9c28097a678f50da05102bc9fb74a4 Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Tue, 16 Jun 2020 15:56:10 +0100 Subject: Acknowledged contributions of Marios Karouzos Marios had read the first draft of the paper (Commit f990bba) and provided valuable feedback (shown below) that ultimately helped in the current version. But because of all the work that was necessary in those days, I forgot to actually thank him in the acknowledgment, while I had implemented most of his thoughts. Following Marios' thoughts on the Git branching figure, with this commit, I am also adding a few sentences at the end of the caption with a very rough summary of Git. I also changed the branch commit-colors to shades of brown (incrementally becoming lighter as higher-level branches are shown) to avoid the confusion with the blue and green signs within the schematic papers shown in the figure. Marios' comments (April 28th, 2020, on Commit f990bba) ------------------------------------------------------ I think the structure of the paper is more or less fine. There are two places that I thought could be improved: 1) Section 3 (Principles) was somewhat confusing to me in the way that it was structured. I think the main source of confusion is the mixing of what Maeage is about and what other programs have done. I would suggest to separate the two. I would have short intro for the section, similar to what you have now. However, I would suggest to highlight the underlying goals motivating the principles that follow: reproducibility, open science, something else? Then I would go into the details of the seven principles. Some of the principles are less clear to me than others. For example, why is simplicity a guiding principle? Then some other principles appear to be related, for example modularity, minimal complexity and scalability to my eyes are not necessarily separate. Finally, I would separate the comparison with other software and either dedicate a section to that somewhere toward the end of the paper (perhaps a subsection for section 5) or at least condense it and put it as a closing paragraph for Section 3. As it is now I think it draws focus from Maneage and also includes some repetitions. 2) Section 4 (Maneage) was at times confusing because it is written, I think in part as a demonstration of Maneage (i.e., including examples that showed how Maneage was used to write this or other papers) and a manual/description of the software. I wonder whether these two aspects can be more cleanly separated. Perhaps it would be possible to first have a section 4 where each of the modules/units of Maneage are listed and explained and then have the following section discuss a working example of Maneage using this or another paper. 3) I found Figure 7 [the git branching figure] and its explanation not very intuitive. This probably has to do with my zero knowledge of github and how versioning there works, but perhaps the description can be a bit more "user friendly" even for those who are not familiar with the tool. 4) I find Section 6 to be rather inconsequential. It does not add anything and it more or less is just a summary of what was discussed. I would personally remove it and include a very short summary of the ideals/principles/goals of Maneage at the beginning of Section 5, before the discussion. --- tex/src/figure-branching.tex | 56 +++++++++++++++++++++++--------------------- tex/src/preamble-project.tex | 1 - 2 files changed, 29 insertions(+), 28 deletions(-) (limited to 'tex') diff --git a/tex/src/figure-branching.tex b/tex/src/figure-branching.tex index 56a76e8..56c1652 100644 --- a/tex/src/figure-branching.tex +++ b/tex/src/figure-branching.tex @@ -17,12 +17,14 @@ -%% To simplify the adding of new commits. +%% Basic definitions to facilitate the plot code. \newcommand{\branchcommit}[4]{ \draw [fill=#1, opacity=0.8] (#2,#3) circle [x radius=5.5mm, y radius=2.1mm]; \draw [anchor=center] (#2,#3) node {\textcolor{white}{\scriptsize\texttt{#4}}}; } - +\definecolor{maneagebranchcolor}{HTML}{46211A} +\definecolor{projectbranchcolor}{HTML}{BA5536} +\definecolor{derivedbranchcolor}{HTML}{C28556} @@ -61,24 +63,24 @@ (3cm,4.5cm) -- (4.5cm,5cm) -- (4.5cm,6cm) -- (3cm,6.5cm); %% Maneage commits. - \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} + \branchcommit{maneagebranchcolor}{1.5cm}{1cm}{1d72e26} + \branchcommit{maneagebranchcolor}{1.5cm}{2cm}{0c120cb} + \branchcommit{maneagebranchcolor}{1.5cm}{3cm}{5781173} + \branchcommit{maneagebranchcolor}{1.5cm}{4cm}{0774aac} + \branchcommit{maneagebranchcolor}{1.5cm}{5cm}{3c05235} + \branchcommit{maneagebranchcolor}{1.5cm}{6cm}{6ec4881} + \branchcommit{maneagebranchcolor}{1.5cm}{7cm}{852d996} %% Project commits. - \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} + \branchcommit{projectbranchcolor}{3cm}{2.5cm}{4483a81} + \branchcommit{projectbranchcolor}{3cm}{3.5cm}{5e830f5} + \branchcommit{projectbranchcolor}{3cm}{4.5cm}{01dd812} + \branchcommit{projectbranchcolor}{3cm}{5.5cm}{2ed0c82} + \branchcommit{projectbranchcolor}{3cm}{6.5cm}{f62596e} %% Derivate project commits. - \branchcommit{red!60!green}{4.5cm}{5cm}{f69e1f4} - \branchcommit{red!60!green}{4.5cm}{6cm}{716b56b} + \branchcommit{projectbranchcolor}{4.5cm}{5cm}{f69e1f4} + \branchcommit{projectbranchcolor}{4.5cm}{6cm}{716b56b} %% Paper being processed icon. The white rectangle over it is to blend it %% into the background. @@ -128,23 +130,23 @@ {\bf project}; %% Maneage commits. - \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} + \branchcommit{maneagebranchcolor}{9.5cm}{1cm}{1d72e26} + \branchcommit{maneagebranchcolor}{9.5cm}{2cm}{0c120cb} + \branchcommit{maneagebranchcolor}{9.5cm}{4cm}{b47b2a3} + \branchcommit{maneagebranchcolor}{9.5cm}{5cm}{340a7ec} + \branchcommit{maneagebranchcolor}{9.5cm}{6cm}{a92b25a} + \branchcommit{maneagebranchcolor}{9.5cm}{7cm}{6e1e3ff} %% Project commits. - \branchcommit{red!60!green}{11cm}{2.5cm}{4483a81} - \branchcommit{red!60!green}{11cm}{4.5cm}{\projectversion} + \branchcommit{projectbranchcolor}{11cm}{2.5cm}{4483a81} + \branchcommit{projectbranchcolor}{11cm}{4.5cm}{\projectversion} \node[anchor=south, inner sep=0pt, color=white] at (11cm,4.8cm) {\includegraphics[width=1cm]{tex/img/icon-complete.eps}}; %% Derivate project commits. - \branchcommit{purple!60!yellow}{12.5cm}{5cm}{b177c7e} - \branchcommit{purple!60!yellow}{12.5cm}{6cm}{5ae1fdc} - \branchcommit{purple!60!yellow}{12.5cm}{7cm}{bcf4512} + \branchcommit{derivedbranchcolor}{12.5cm}{5cm}{b177c7e} + \branchcommit{derivedbranchcolor}{12.5cm}{6cm}{5ae1fdc} + \branchcommit{derivedbranchcolor}{12.5cm}{7cm}{bcf4512} %% Description of this scenario: \draw [rounded corners, fill=black!10!white] (11.1cm,0) rectangle (15.3cm,1.25cm); diff --git a/tex/src/preamble-project.tex b/tex/src/preamble-project.tex index e14fbf6..16a9ddc 100644 --- a/tex/src/preamble-project.tex +++ b/tex/src/preamble-project.tex @@ -55,7 +55,6 @@ %% Custom macros \newcommand{\inlinecode}[1]{\textcolor{blue!35!black}{\texttt{#1}}} - \newcommand\eprint[1]{\href{https://arXiv.org/abs/#1}{{arXiv:#1}}} \newcommand\doi[1]{\href{https://oadoi.org/#1}{{DOI:#1}}} -- cgit v1.2.1