<p><b>dwj07@fsu.edu</b> 2013-03-21 11:13:59 -0600 (Thu, 21 Mar 2013)</p><p><br>
-- DOCUMENT COMMIT --<br>
<br>
Adding a starter developers guide.<br>
</p><hr noshade><pre><font color="gray">Added: trunk/documents/developers_guide/MPAS-DevelopersGuide.pdf
===================================================================
(Binary files differ)
Index: trunk/documents/developers_guide/MPAS-DevelopersGuide.pdf
===================================================================
--- trunk/documents/developers_guide/MPAS-DevelopersGuide.pdf 2013-03-21 16:41:03 UTC (rev 2644)
+++ trunk/documents/developers_guide/MPAS-DevelopersGuide.pdf 2013-03-21 17:13:59 UTC (rev 2645)
Property changes on: trunk/documents/developers_guide/MPAS-DevelopersGuide.pdf
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/octet-stream
\ No newline at end of property
Added: trunk/documents/developers_guide/MPAS-DevelopersGuide.tex
===================================================================
--- trunk/documents/developers_guide/MPAS-DevelopersGuide.tex (rev 0)
+++ trunk/documents/developers_guide/MPAS-DevelopersGuide.tex 2013-03-21 17:13:59 UTC (rev 2645)
@@ -0,0 +1,120 @@
+\documentclass[11pt]{report}
+
+\usepackage{epsf,amsmath,amsfonts}
+\usepackage{graphicx}
+\usepackage{listings}
+
+\begin{document}
+
+\title{MPAS-Developers Guide}
+\author{MPAS Development Team}
+
+\maketitle
+\tableofcontents
+
+%-----------------------------------------------------------------------
+
+\chapter{Summary}
+
+This document is intended to provide developers with a better understanding of
+the MPAS framework, and the requirements for adding code to MPAS. It contains a
+description of the MPAS framework, a general overview of how code is laid out,
+and guidelines/expectations for additions of code to any part of MPAS.
+
+%-----------------------------------------------------------------------
+
+\chapter{MPAS-Description}
+MPAS is a collaborative effort to produce a shared framework which model
+components can be built upon. It allows model developers to make use of shared
+funcionality in order to focus on developing new science within a particular
+MPAS dynamical core, rather than having to develop new infrastructure. In the
+event that new funcionality is added to any of the shared parts of MPAS, all
+developers can immediately make use of it.
+
+\chapter{MPAS Code Layout}
+After checking out the repository, the MPAS code is laid out in the following directory structure.
+\begin{lstlisting}
+repo
+|-Makefile
+\-src
+ |-driver
+ |-registry
+ |-framework
+ |-operators
+ |-external
+ |-inc
+ |-core_sw
+ \-Makefile
+\end{lstlisting}
+
+Although there are more files/directories than are listed these are the
+relevant directories for source code modifications.
+
+The src directory contains all source code related to MPAS, wheter it is shared
+or not.
+
+Shared parts of MPAS belong in either the driver, external, framework,
+operators, or registry directories.
+
+registry contains the parsing code for Registry. Registry is used for easy
+modification of variables within a specifc MPAS core. Each core has it's own
+Registry.xml file which defines a list of dimensions, namelist options,
+variables, and other information specific to that core. On compile time, the
+registry parser (parse) is built. This parser then parses the Registry.xml file
+and generates some Fortran code, which is stored in src/inc. It is then
+included at various places within framework to define all of the necessary
+things.
+
+driver contains general code for building the MPAS executable, and the general
+structure of how an MPAS executable looks.
+
+external contains external code to MPAS that is used within MPAS, i.e. ESMF
+time keeping routines.
+
+framework contains shared code related to the framework of MPAS. This includes
+the I/O layer, communication routines, and definitions of the data types.
+
+operators contains shared code used for computing specific quantities on an
+MPAS grid. This includes radial basis function interpolation.
+
+Non-shared parts of MPAS belong under the remaining directories. As an example,
+the core\_sw directory represents the shallow water dynamic core within the
+MPAS framework. Other directories named core\_ are either dynamical cores, or
+parts of other dynamical cores.
+
+Most developers will only work under their specific core directory, and should
+not modify code in another core without permission.
+
+\chapter{Development guidelines}
+As developers of MPAS, we attempt to make the code look as uniform as we can
+across the entire codebase. In order to enforce this, there are a set of
+guidelines developers should follow.
+
+\begin{itemize}
+ \item Each core has a name, and an abbreviation. For example, the shallow water core is called sw and it's abbreviation is sw, but the ocean core is called ocean and it's abbreviation is ocn.
+ \item All public subroutines should be named in a manner which prevents namespace conflicts. \\
+ Shared functions/subroutines are simply named mpas\_subroutine\_name.\\
+ Core specific functions/subroutines are named mpas\_abbrev\_subroutine\_name (where abbrev is replaced with the cores abbreviation).
+ e.g. mpas\_nhyd\_atmos\_time\_integration
+ \item Subroutine names should all be lower case, with underscores in place of spaces.
+ \item Variable names should be mixed case.
+ \item In general, variable names should be as descriptive as possible.
+ \item Subroutines should be appropriately documented. Shared portions of MPAS code use doxygen comments, but core developers are free to decide what method of documenting they prefer.
+ \item Development within a core should be approved by other core developers before being merged into that core.
+ \item Development within a core should also follow the practices of that core's developer group.
+ \item ....more guidelines?
+\end{itemize}
+
+As modifications to MPAS are made, they must be approved by other developers
+before they are committed to the repository trunk. Within a core, developers
+are free to modify code as required and commit changes to the trunk. However,
+within shared parts of MPAS, the larger developer base needs to approve the
+change. In general this means describing the changes to the developers group,
+along with why they are important/required. Each commit check should include a
+requested time line, and other developers should attempt to follow the time
+line.
+
+If the timeline is not followed by other developers, the committer should send
+out a reminder email. 24 hours after the reminder email is sent out, if no
+developer responds the commit can be pushed onto the trunk.
+\end{document}
</font>
</pre>