From e7bf1849afd18f12ba485304e5699376b951b5f3 Mon Sep 17 00:00:00 2001 From: Boud Roukema Date: Mon, 20 Apr 2020 01:59:20 +0200 Subject: Minor edits to 4 Maneage intro This drops the word count in the introductory part of the Maneage section by about 15 words. --- paper.tex | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/paper.tex b/paper.tex index 9ed85a3..6773dc5 100644 --- a/paper.tex +++ b/paper.tex @@ -313,14 +313,14 @@ IPOL is thus not scalable to large projects, which commonly involve dozens of hi \section{Maneage} \label{sec:maneage} Maneage is an implementation of the principles of Section \ref{sec:principles}. -In practice, Maneage is a collection of plain-text files that are distributed in pre-defined sub-directories by context (a modular source), and are all under version-control, currently with Git. -The main Maneage Branch is a fully-working skeleton of a project without much flesh: it contains all the low-level infrastructure, but without any actual high-level analysis operations. +In practice, Maneage is a collection of plain-text files that are distributed in pre-defined sub-directories by context (a modular source), and are all under version control, currently with Git. +The main Maneage Branch is a fully working skeleton of a project without much flesh: it contains all the low-level infrastructure, but without any actual high-level analysis operations. Maneage contains a file called \inlinecode{README-hacking.md} (the \inlinecode{README.md} file is reserved for the project using Maneage, not Maneage itself) that has a complete checklist of steps to start a new project and remove demonstration parts. There are also hands-on tutorials to help new users. -To start a new project, the authors \emph{clone} Maneage, create a branch, and start their project by customizing it by following good practice, as opposed to focing a good data management strategy in the end, \citet{fineberg19} also note the importance of this. +To start a new project, the authors \emph{clone} Maneage, create a branch, and start their project by customizing it. Thus, the start their project with a good data management strategy rather than try to impose it later, as recommended by \citet{fineberg19}. Customization is done by adding the names of the necessary software, references to input data, analysis and visualization commands and a narrative description. -This will usually be done in multiple commits in the project's duration (perhaps multiple years), thus preserving the project's history: the causes of all choices, the authors and times of each change, failed tests, etc. +This will usually be done in multiple commits during the project, preserving the project's history: the descriptions of and motivations for changes or test failures and successes, and the authors and timestamps of each change. \begin{lstlisting}[language=bash] git clone https://gitlab.com/maneage/project.git # Clone Maneage, default branch `maneage'. @@ -329,7 +329,7 @@ This will usually be done in multiple commits in the project's duration (perhaps git checkout -b master # Make new `master' branch, start customizing. \end{lstlisting} -Figure \ref{fig:files} shows the directory structure of the cloned project and some representative files in each directory. +Figure \ref{fig:files} shows the directory structure of the cloned project and typical files. The top-level source has only very high-level components: the \inlinecode{project} shell script (POSIX-compliant) that is the main interface to the project, as well as the paper's \LaTeX{} source, documentation and a copyright statement. Two sub-directories are also present: \inlinecode{tex/} (containing \LaTeX{} files) and \inlinecode{reproduce/} (containing all other parts of the project). @@ -349,19 +349,19 @@ Two sub-directories are also present: \inlinecode{tex/} (containing \LaTeX{} fil } \end{figure} -The \inlinecode{project} script is a high-level wrapper to interface with Maneage. -It has two main phases as shown below: (1) configuration, where the necessary software are built and the environment is setup, and (2) analysis, where data are accessed and the software is run on them to create visualizations and the final report. -In practice, these steps are run with two commands: +The \inlinecode{project} script is a high-level wrapper. +It has two main phases: (1) configuration, where the necessary software is built and the environment is set up, and (2) analysis, where data are accessed and the software is run on these to create visualizations and the final report. +These steps are run with two commands: \begin{lstlisting}[language=bash] ./project configure # Build all necessary software from source. ./project make # Do the analysis (download data, run software on data, build PDF). \end{lstlisting} -The general implementation of Maneage is discussed below. +The implementation of Maneage has the following aspects. Section \ref{sec:usingmake} elaborates why Make was chosen as the main job manager. -Sections \ref{sec:projectconfigure} \& \ref{sec:projectanalysis} then discuss the operations done during the configuration and analysis phase. -Afterwards, we describe how Maneage projects benefit from version control in Section \ref{sec:projectgit}. +Sections \ref{sec:projectconfigure} \& \ref{sec:projectanalysis} discuss the operations done during the configuration and analysis phase. +The benefit from version control is described in Section \ref{sec:projectgit}. Section \ref{sec:collaborating} discusses the sharing of a built environment, and in Section \ref{sec:publishing} the publication/archival of Maneage projects is discussed. \subsection{Job orchestration with Make} -- cgit v1.2.1