proposal_and_decisions.tex

\documentclass[pdf, 8pt]{beamer}
\usepackage{color}
\usepackage[utf8]{inputenc}
\usepackage{fancyvrb}
\usepackage{xcolor}
\usepackage{multicol}

\mode<presentation>{}

\title{OpenSim2Git}

\subtitle{progress, decisions to make, remaining tasks}

\author{Chris Dembia, Justin Si}

\date{\today}

% Macros, etc.
\fvset{commandchars=\\\{\}}

\def\NUMDECISIONS{7}
\def\GUICOLOUR{black}
\def\CORECOLOR{green!60!black}
\def\IDKCOLOUR{orange}
\def\CFSQPCOLR{black}
\def\DELETE{red}
\def\PRESERVE{green!60!black}
\def\TOTAG{blue}

\begin{document}

\begin{frame}
\maketitle

\end{frame}

\begin{frame}[fragile]{What's been done}

\begin{itemize}
\item Created git repository (github.com/chrisdembia/opensim2git) containing
    python scripts.
\item authors.txt (e.g., \verb|nallana = Nabeel Allana <nallana@uwaterloo.ca>|)
\item Fork/patch of svn2git Ruby tool (same as what Sherm used for Simbody).
\item Run svn2git for CFSQP (to live at github.com/opensim-org/opensim-cfsqp).
\item Run svn2git for opensim-core (to live at opensim-org/opensim-core).
\item Save output of svn2git to a log file.
\item Decide which files to exclude from Git opensim-core history.
\item Normalize line endings to \verb|\n| (instead of mix of \verb|\r\n| and
\verb|\n|).
\item Delete most SVN branches, keep some as Git tags.
\item Once Git repositories are created, edit their content:
    \begin{itemize}
    \item CFSQP: Edit CMakeLists.txt so it's an independent project.
    \item OpenSim: Clean up CMakeLists.txt for removed directories (Gui, Installer,
    Vendors/CFSQP, Java wrapping installation).
    \end{itemize}
\end{itemize}
\end{frame}

\begin{frame}[fragile]{opensim-core}{The current paths that end up in
    opensim-core}

    \textbf{opensim-core will be the green directories.}

\begin{Verbatim}
\textcolor{\CORECOLOR}{Applications/}
\textcolor{\GUICOLOUR}{Gui/}
\textcolor{\GUICOLOUR}{Installer/}
\textcolor{\IDKCOLOUR}{Models/}
\textcolor{\CORECOLOR}{OpenSim/}
Vendors/\textcolor{\CFSQPCOLR}{CFSQP/}
       /\textcolor{\CORECOLOR}{lepton/}
       /\textcolor{\GUICOLOUR}{vtk_dll/}
\textcolor{\CORECOLOR}{ApiDoxygen.cmake}
\textcolor{\CORECOLOR}{CMakeLists.txt}
\textcolor{\CORECOLOR}{Copyright.txt}
\textcolor{\CORECOLOR}{CTestConfig.cmake}
\textcolor{\CORECOLOR}{Doxyfile.in}
\textcolor{\CORECOLOR}{FindSimbody.cmake}
\textcolor{\CORECOLOR}{NOTICE}
\textcolor{\GUICOLOUR}{NSIS.InstallOptions.ini.in}
\textcolor{\GUICOLOUR}{NSIS.template.in}
\textcolor{\CORECOLOR}{OpenSimAPI.html}
\textcolor{\CORECOLOR}{ReadMe.txt}
\textcolor{\GUICOLOUR}{WriteEnvStr.nsh}
\end{Verbatim}
\end{frame}

\begin{frame}
    About \NUMDECISIONS~ decisions to make.
\end{frame}

\begin{frame}[fragile]{1/\NUMDECISIONS: Starting at r6665}

    \textbf{r6663 commit message}

    \begin{Verbatim}
    Phase 1: Rearrange repository such that:
    1. Examples are moved up to Models top level directory
    2. Applications are moved up to top level directory
    3. Gui is moved to its own top level directory
    4. Prebuilt simtk libraries have been removed from Vendors directory
    5. CMakeLists.txt files have been updated to correspond to new layout
\end{Verbatim}

    \textbf{r6665 commit message}

\begin{Verbatim}
    More restructuring of repository in particular:
    remove top level API folder
    move API/doc folder to OpenSim/doc 
    move API/examples/plugin to OpenSim/Plugin
    Adjust Makefiles to copy Simbody libraries to build directory
    Add swig output files now under OpenSim/Java/src
    Fix install locations to correspond to latest repository layout.
    All test cases pass and installation maintains same layout (except for
    Plugin now under APIExamples)
\end{Verbatim}


    \begin{itemize}
            \item svn2git bug: cannot bring over the following old SVN tags:
                \begin{Verbatim}
                    Tags/Release_02_00_Jamboree
                    Tags/OpenSim_BuiltOn_SimTK_1_1
                \end{Verbatim}
        \end{itemize}
\end{frame}

\begin{frame}{2/\NUMDECISIONS: Models, and OutputReference}
    Options:
    \begin{itemize}
            \item As-is (Models in opensim-core).
            \item Keep Models in opensim-core, but put OutputReference
                elsewhere.
            \item Do not keep Models in opensim-core.
    \end{itemize}
    Would people ever want the API, etc. without models?
\end{frame}

\begin{frame}[fragile]{3/\NUMDECISIONS: Excluding files/directories from the
history (files existing after r6665).}

\begin{Verbatim}
.*CFSQP.*
Gui
OpenSim/Applications/Gui
Installer
NSIS.InstallOptions.ini.in
NSIS.template.in
WriteEnvStr.nsh
OpenSim/doc/html
API/doc/html
Documentation/OpenSim_Splash.psd
Documentation/OpenSim_Splash_2_2_1.psd
OpenSim/Java/src
OpenSim/Java/OpenSimJNI/OpenSimJNI_wrap.*
OpenSim/Wrapping/Java/OpenSimJNI/OpenSimJNI_wrap.*
OpenSim/Wrapping/Python/pyOpenSim_wrap.cxx
OpenSim/Wrapping/Python/pyOpenSim_wrap.h
OpenSim/Wrapping/Python/pyOpenSim.py
OpenSim/Utilities/importOldModels/SimTKlapack.dll
OpenSim/Utilities/importOldModels/xerces-c_2_7.dll
Vendors/xerces-c_2_8_0
Vendors/vtk_dll
\end{Verbatim}

\end{frame}

\begin{frame}[fragile]{3/\NUMDECISIONS: Excluding OutputReference from the history}

\begin{Verbatim}
Models/Arm26/OutputReference
Models/Leg39/OutputReference
Models/Gait10dof18musc/OutputReference
Models/Gait2354_Simbody/OutputReference
Models/Gait2392_Simbody/OutputReference
Models/Leg6Dof9Musc/Stance/Reference
OpenSim/Examples/ControllerExample/OutputReference/(*.sto|*.mot|*.osim)
OpenSim/Examples/CustomActuatorExample/OutputReference/(*.sto|*.mot|*.osim)
OpenSim/Examples/OptimizationExample_Arm26/OutputReference/(*.sto|*.mot|*.osim)
OpenSim/Examples/ExampleMain/OutputReference/(*.sto|*.mot|*.osim)
\end{Verbatim}

\end{frame}

\begin{frame}[fragile]{3/\NUMDECISIONS: Excluding files that only existed
before r6665}

\begin{Verbatim}
Documentation
Vendors/xerces-c-src_2_7_0
Vendors/xerces-c-src_2_4_0
Vendors/xerces-c-src2_4_0
Vendors/lib
Vendors/core
Vendors/SimTK
Specs
OpenSim/Examples/Gait2354_Simbody/OutputReference
OpenSim/Examples/Gait2392_Simbody/OutputReference
OpenSim/Examples/Gait/OutputReference
OpenSim/Examples/Leg39/OutputReference
OpenSim/Examples/Gait2354/OutputReference
(NMBLTK)

Tags/Release_02_00_Jamboree
Tags/OpenSim_BuiltOn_SimTK_1_1
\end{Verbatim}

Could continue to find big (mostly binary) files to remove from history.

\end{frame}

\begin{frame}{4/\NUMDECISIONS: Branches: SVN branches vs Git branches}

    SVN stores diffs, Git stores snapshots of the working copy, and refers
    to ``revisions'' using hashes.

\begin{itemize}
    \item In both SVN and Git, branches and tags are different names for the
        same mechanism, and the terms distinguish their roles.
    %\item In SVN, a branch is literally a copy of the repository, in a
    %    different place in the repository. Each revision contains each branch.
    \item In SVN, history is linear.
    \item Git history is a tree. Branches just point to a ``revision'' anywhere
        in that tree.
     %   branches are different branches in the history tree. Can only
     %   view one at a time. Very lightweight. Branches are just pointers or
     %   labels into the history tree.
    \item In Git, branches are ephemeral, and tags are permanent, not changed,
        for releases.
\end{itemize}

The take-away: all SVN branches should be deleted in Git except for ones that
are actively worked on. All releases should be Git tags.

\end{frame}

\begin{frame}[fragile]{4/\NUMDECISIONS: SVN Branches: what happens to them in Git?}

\textcolor{\PRESERVE}{This SVN branch will be a \textbf{branch} in Git.}

\textcolor{\TOTAG}{This SVN branch will be a \textbf{tag} in Git.}

\textcolor{\DELETE}{This SVN branch will not appear anywhere in Git.}

\hrule
\begin{multicols}{2}
\begin{Verbatim}
\textcolor{\DELETE}{1728Branch}
\textcolor{\PRESERVE}{CableWrapping}
\textcolor{\DELETE}{Engines}
\textcolor{\DELETE}{Integrator}
\textcolor{\DELETE}{Integrator@1105}
\textcolor{\DELETE}{JasonEmel485Project}
\textcolor{\DELETE}{JasonEmel485Project@1683}
\textcolor{\DELETE}{JasonEmel485Project@1741}
\textcolor{\DELETE}{JasonEmel485Project@1755}
\textcolor{\DELETE}{JasonEmel485Project@4133}
\textcolor{\PRESERVE}{ModelBuilding} TODO
\textcolor{\DELETE}{OpenSim}
\textcolor{\DELETE}{OpenSim15}
\textcolor{\DELETE}{OpenSim18}
\textcolor{\DELETE}{OpenSim19}
\textcolor{\DELETE}{OpenSim20}
\textcolor{\DELETE}{OpenSim21}
\textcolor{\DELETE}{OpenSim22}
\textcolor{\DELETE}{OpenSim23}
\textcolor{\DELETE}{OpenSim23_1}
\textcolor{\DELETE}{OpenSim23_1_NB7}
\textcolor{\TOTAG}{OpenSim24}
\textcolor{\TOTAG}{OpenSim30}
\textcolor{\DELETE}{OpenSim30GUI}
\textcolor{\TOTAG}{OpenSim31}
\textcolor{\TOTAG}{OpenSim32}
\textcolor{\DELETE}{OpenSimGUIProto}
\textcolor{\DELETE}{OpenSimWW01}
\textcolor{\DELETE}{OpenSim_BuiltOn_SimTK_1_1}
\textcolor{\DELETE}{OpenSim_BuiltOn_SimTK_1_1@1683}
\textcolor{\DELETE}{OpenSim_BuiltOn_SimTK_1_1@1741}
\textcolor{\DELETE}{OpenSim_BuiltOn_SimTK_1_1@1755}
\textcolor{\DELETE}{OpenSim_BuiltOn_SimTK_1_1@4056}
\textcolor{\DELETE}{OpenSim_exhibit}
\textcolor{\DELETE}{Remove_Xerces}
\textcolor{\DELETE}{Restructure}
\textcolor{\DELETE}{UseSimTKLibs}
\textcolor{\PRESERVE}{Trunk} (master branch)
\textcolor{\DELETE}{migrate2NmbltkBr}
\end{Verbatim}
\end{multicols}
\end{frame}

\begin{frame}[fragile]{4/\NUMDECISIONS: SVN Tags: what happens to them in Git?}

\textcolor{\PRESERVE}{This SVN tag will be a tag in Git.}

\textcolor{\DELETE}{This SVN tag will not appear anywhere in Git.}

\hrule

\begin{multicols}{2}
\begin{Verbatim}
\textcolor{\DELETE}{Before_Directory_Restructure_2007-03-16}
\textcolor{\DELETE}{NMBLTK}
\textcolor{\DELETE}{NMBLTK@1095}
\textcolor{\DELETE}{Release0.1}
\textcolor{\DELETE}{Release0.1@1096}
\textcolor{\DELETE}{Release_00_00}
\textcolor{\DELETE}{Release_00_06_00}
\textcolor{\DELETE}{Release_00_07_08}
\textcolor{\DELETE}{Release_00_08_02}
\textcolor{\DELETE}{Release_01_00_00}
\textcolor{\DELETE}{Release_01_01_00}
\textcolor{\DELETE}{Release_01_05_05}
\textcolor{\DELETE}{Release_01_06_Jamboree}
\textcolor{\DELETE}{Release_01_07_00}
\textcolor{\DELETE}{Release_02_00}
\textcolor{\DELETE}{Release_02_00_01}
\textcolor{\DELETE}{Release_02_00_02}
\textcolor{\DELETE}{Release_02_00_Jamboree}
\textcolor{\DELETE}{Release_02_02_00}
\textcolor{\DELETE}{Release_02_02_01}
\textcolor{\DELETE}{Release_02_03_02}
\textcolor{\PRESERVE}{Release_02_04_00} (v2.4, or OpenSim-2.4)
\textcolor{\PRESERVE}{Release_03_00_00} (v3.0, or OpenSim-3.0)
\textcolor{\DELETE}{Release_03_00_Dev} TODO
\textcolor{\PRESERVE}{Release_03_01_00} (v3.1, or OpenSim-3.1)
\textcolor{\PRESERVE}{Release_03_02_00} (v3.2, or OpenSim-3.2)
\end{Verbatim}
\end{multicols}
\end{frame}

\begin{frame}[fragile]{4/\NUMDECISIONS: SVN Branches \& tags after r6665}
    If we only keep history after r6665, we only need to deal with
    the following branches/tags (selected from previous 2 slides):

    \vspace{1cm}
Branches:

\begin{Verbatim}
\textcolor{\PRESERVE}{CableWrapping}
\textcolor{\PRESERVE}{ModelBuilding} TODO
\textcolor{\TOTAG}{OpenSim30}
\textcolor{\DELETE}{OpenSimWW01}
\textcolor{\DELETE}{OpenSim30GUI}
\textcolor{\TOTAG}{OpenSim31}
\textcolor{\TOTAG}{OpenSim32}
\textcolor{\DELETE}{Remove_Xerces}
\end{Verbatim}

Tags:

\begin{Verbatim}
\textcolor{\PRESERVE}{Release_02_04_00} (v2.4, or OpenSim-2.4)
\textcolor{\PRESERVE}{Release_03_00_00} (v3.0, or OpenSim-3.0)
\textcolor{\DELETE}{Release_03_00_Dev} TODO
\textcolor{\PRESERVE}{Release_03_01_00} (v3.1, or OpenSim-3.1)
\textcolor{\PRESERVE}{Release_03_02_00} (v3.2, or OpenSim-3.2)
\end{Verbatim}

\end{frame}

\begin{frame}[fragile]{5/\NUMDECISIONS: Using CFSQP in OpenSim}{How does cfsqp
    interact with opensim-core?}
    \begin{itemize}
        \item OpenSim doesn't know about CFSQP, if we give CFSQP, they
            build it on their own and install it into the OpenSim/bin
            folder?
        \item Does OpenSim need to know about CFSQP in some way?
        \item We could create a CMake target in opensim-cfsqp
            \verb|install_to_opensim|, and a CMake variable that is
            \verb|$OPENSIM_HOME| that the target uses.
    \end{itemize}
\end{frame}

\begin{frame}{6/\NUMDECISIONS: When do we switch?}

\begin{itemize}
\item Over a weekend.
\item Key events and considerations:
\begin{itemize}
\item March workshop.
\item Start of ME 485.
\item DARPA Challenge deadlines.
\item Ajay's sweeping changes to Trunk.
\end{itemize}
\item Convert before we start the Challenge.
\item Should teach Git to team before The Conversion.
\end{itemize}

\end{frame}

\begin{frame}{7/\NUMDECISIONS: Name of the repository: opensim-core?}
The repository contains:
\begin{itemize}
    \item C++ API
    \item Java wrapping
    \item Python wrapping
    \item models
    \item command-line applications
    \item C++ API documentation
\end{itemize}

Other options: opensim, opensim-api.
\end{frame}

\begin{frame}[fragile]{Repository size (opensim-core) depending on decisions we make}
\begin{tabular}{lll}
    decisions & .git & .git + working copy \\ \hline
    The biggest repository possible & 1.2 GB &1.9 GB \\
    All revisions, with complete Models folder & 538 MB & 547 MB \\
    All revisions, without OutputRef. & 406 MB & 415 MB (error\ldots) \\
    r6665 and after, with complete Models folder & 240 MB & 918 MB \\
    r6665 and after, without OutputRef. & 86 MB & 252 MB \\
    r6665 and after, without Models folder & 81 MB & 215 MB \\
\end{tabular}

    %\begin{tabular}{l|l|l|l|l|l|p{2cm}}
    %  &  NMBLTK & Models & OutputRef. & r6665 & .git size & .git + working
    %  copy size \\ \hline
    %  1 & yes & yes & yes & before \& after & TODO & TODO \\
    %  2 & yes & yes & no & before \& after & 406 MB & 415 MB \\
    %  3 & yes & no & no & before \& after & TODO & TODO \\
    %  4 & N/A & yes & yes & only after & 240 MB & 918 MB \\
    %  5 & N/A & yes & no & only after & 86 MB & 252 MB \\
    %  6 & N/A & no & no & only after & 81 MB & 215 MB \\
    %\end{tabular}
      %3 & no & yes & no & before \& after & TODO & TODO \\

    \vspace{1cm}
    \vspace{1cm}

    (The .git folder is similar to .svn folders, except there is only one, in
    the root directory. It's where the history lives (all but working copy).)
\end{frame}

\begin{frame}{Remaining tasks}
\begin{itemize}
\item Merge history (EDIT: NON-ISSUE NOW).
    \begin{itemize}
            \item svn2git detects branch points, but not when a branch is
                merged back into another branch.
            \item Prevents branches from getting deleted (garbage
                collected).
            \item Helps when looking through the history.
    \end{itemize}
\item Teach Git to team.
    \begin{itemize}
        \item Sherm has collected a list of resources.
        \item Nabeel showed me a really neat and brief command-line tutorial.
        \item Most people will probably use TortoiseGit.
        \item (1) Basics of git, (2) How git works (internals).
    \end{itemize}
\item Continue finding large binary files to exclude from history.
\item Create git patches to prepare necessary post-conversion changes to CMake,
    etc.
\item Work with Ayman to set up the GUI to pick up the separate OpenSim
    installation properly.
\end{itemize}
\end{frame}

\end{document}