Yannick opened the meeting with the following agenda. The objective of the meeting was to introduce everyone to tools and methodologies that we will be using for code development. The presentations were informal and open to discussion as they were being presented.
Meeting Agenda
Overview of Doxygen (Steve & Mark, JCSDA)
- How it works
- Please use it (this means you)
Brief overview of Git-LFS (Mark)
- How it works
- Please use it (this means you)
Brief overview of Git-Flow (Yannick)
- Workflow/philosophy and application
- How it works
- Please use it (this means you)
Overview of Doxygen
Introduction to Doxygen
Mark (JCSDA) presented this section using the following slides
Discussion:
Yannick commented that for diagrams that are generated using Doxygen, such as inheritance diagrams and call trees, you can control how many levels of depth are displayed. This will help keep the diagrams from getting too cluttered.
Xin asked if we need to insert copyright information into all of the source files. This is needed, but it is not necessarily a doxygen construct (we might just cut and paste the statement into all of the source files).
Chris asked how are we going to standardize doxygen contents, style etc. Start using doxygen and over time we should get a feel for what is useful and what is not. Hopefully, we will converge on a practice that yields a good balance between documenting useful information and effort.
Check out the ReadTheDocs page on Doxygen. The link is in Mark's slides.
Introduction to Doxywizard (GUI), and thoughts about how to distribute work and responsibilities
Steve (JCSDA) presented this section using the following slides
Discussion
Mark commented that in order to get the LaTex formulas working, as shown in his example, you need to go into the Expert settings on Doxywizard, select the HTML category, and make sure that the USE_MATHJAX setting is enabled (box is checked).
Several people commented that the Doxywizard configuration is rather complicated. This can be dealt with by having the JEDI core team supply doxygen config files.
Guillaume pointed out that when you have both C++ and Fortran together in a repository, doxygen has trouble connecting across the C++, Fortran boundary. This issue will need to be addressed with help from the JEDI core team.
Overview of Git-LFS
Mark (JCSDA) presented this section using the following slides
Mark cautioned everyone to use git-lfs from the start, since it is difficult to migrate existing files (that are checked into git) to git-lfs.
Chris asked how are we to avoid a build-up of large files. This will have detrimental impacts such as slowing the clone operation.
This question came about due to the following issue. Let's say you are developing a test and go through several versions of a large test data file. If you commit several of these versions of the test data file, then each of those versions will be in the repository history. And if you ultimately decide to delete the large test file, then you still have the prior versions of it stored in the repo history. It's possible to remove a file from all of the repo history, but if that is done then the earlier commits will be broken (since they rely on having the test file there). There is no easy solution to this problem. We need to be able to develop tests, but we don't want to waste our allocated space on git-lfs.
It may be possible to use permissions to prevent an accidental commit of large files into the repo, but this is not confirmed at this point. The problem is that once the large file gets comitted, the damage has already been done. We will have to find a balance between enabling test development and minimizing our git-lfs space usage.
Overview of Git-Flow
Unfortunately, we ran out of time to cover this topic, so it has been deferred until next week's meeting (4/26/18).
Q & A
Steve, Marek (UKMO) asked, in the context of test, how to deal with new convariances. I'm not certain that I captured this correctly, but I heard several options being expressed. You can link to NICAS and use that, or use an identity operator to copy the input to the output, or if you don't have a covariance shut off the test.