<p><b>dwj07@fsu.edu</b> 2013-04-18 15:26:31 -0600 (Thu, 18 Apr 2013)</p><p><br>
-- DOCUMENT COMMIT --<br>
<br>
Updating developers guide.<br>
</p><hr noshade><pre><font color="gray">Modified: trunk/documents/developers_guide/MPAS-DevelopersGuide.pdf
===================================================================
(Binary files differ)
Modified: trunk/documents/developers_guide/MPAS-DevelopersGuide.tex
===================================================================
--- trunk/documents/developers_guide/MPAS-DevelopersGuide.tex 2013-04-18 21:24:18 UTC (rev 2774)
+++ trunk/documents/developers_guide/MPAS-DevelopersGuide.tex 2013-04-18 21:26:31 UTC (rev 2775)
@@ -8,7 +8,7 @@
\begin{document}
-\title{MPAS Developer's Guide}
+\title{MPAS Developers Guide}
\author{MPAS Development Team}
\maketitle
@@ -17,13 +17,27 @@
%-----------------------------------------------------------------------
\chapter{Summary}
-
This document is intended to describe general development practices within the
MPAS project. The information contained should be read prior to starting a
project within the MPAS framework. Instructions can be used by MPAS core
developers, or external developers. Notes specific to external developers are
made where relevant.
+\section{Becoming a MPAS Developer}
+The preferred approach to contributing source code to the MPAS-Dev repositories
+is via a fork of the release repository. If the preferred approach is not
+workable, developer access to the MPAS-Dev GitHub project needs to be approved
+by core maintainers. Prospective developers should send the following
+information to the relevant core maintainers.
+\begin{itemize}
+ \item What is your GitHub user name? \\
+ (can be acquired at \href{http://www.github.com}{github})
+ \item Can your work be completed in a fork of the release repository?
+ \item If no, please explain the reason.
+ \item What core do you intend to develop?
+ \item What work do you intend to contribute to MPAS?
+\end{itemize}
+
\chapter{Repository Descriptions}
The MPAS project contains several repositories. Some of the repositories are
private for development efforts while some are public for users and releases.
@@ -131,7 +145,7 @@
MPAS-Testing
|--sw (Test Cases for Shallow water core)
|--ocean (Test Cases for Ocean core)
-|--nhyd_atmos (Test Cases for Non-Hydrostatic Atmospheric core)
+|--atmosphere (Test Cases for Non-Hydrostatic Atmospheric core)
\--shared (Test Cases for shared parts of MPAS)
\end{lstlisting}
@@ -149,12 +163,12 @@
| |--shared (Design documents for project in shared directory)
| |--sw (Design documents for shallow water core)
| |--ocean (Design documents for ocean core)
-| |--nhyd_atm (Design documents for Non-hydrostatic atmosphere core)
+| |--atmosphere (Design documents for Non-hydrostatic atmosphere core)
|--users_guide
| |--shared (Shared parts of users guide)
| |--sw (Shallow water specific parts of users guide)
| |--ocean (Ocean specific parts of users guide)
-| |--nhyd_atm (Non-hydrostatic Atmosphere specific parts of users guide)
+| |--atmosphere (Non-hydrostatic Atmosphere specific parts of users guide)
\--developers_guide (This document)
\end{lstlisting}
@@ -195,6 +209,8 @@
\chapter{Development}
The repositories are all hosted on github. The typical life-cycle of a project is as follows:
\begin{enumerate}
+ \item Create a design document for the project. \\
+ (e.g. section \ref{sec:design_documents})
\item Visit appropriate repository website. \\
(e.g. \href{https://github.com/MPAS-Dev/MPAS-Release}{Release Repository})
\item Create a fork of the repository. \\
@@ -217,6 +233,21 @@
Code level requirements are described in chapter \ref{chap:code-guidelines}.
+\section{Design Documents}
+\label{sec:design_documents}
+Design documents are recommended for projects that contribute significant
+changes to either a core or to MPAS in general. They should clearly describe
+the justification for the project, and the changes and impacts of the project.
+Core maintainers reserve the right to deny a pull request that lacks a design
+document.
+
+Developers can refer to
+\href{http://mpas-dev.github.com/files/documents/mpas\_ddt\_redesign.pdf}{DDT
+Redesign} and
+\href{http://mpas-dev.github.com/files/documents/implicit\_vert\_diff\_design.pdf}{Implicit
+Vertical Mixing (MPAS-Ocean)} for examples of design documents that have been
+previously completed.
+
\section{Forks}
\label{sec:forks}
A fork is a user specific copy of another repository. Forks can only be made
@@ -266,7 +297,7 @@
\item All 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
+ e.g. mpas\_atm\_time\_integration
\item Subroutine names should all be lower case, with underscores in place of spaces (e.g. see above).
\item Variable names should be mixed case (e.g. cellsOnCell rather than cells\_on\_cell).
\item In general, variable names should be self-descriptive (e.g. nCells rather than n).
@@ -275,7 +306,7 @@
\item Development within a core should be approved by other core developers before being merged into that core.
\item Development within a core should follow the practices of that core's developer group, for documentation etc.
\item Core related testing is the responsibility of that core's maintainers/developers.
- \item ....more guidelines?
+% \item ....more guidelines?
\end{itemize}
Core maintainers need to approve changes before the changes appear on the
@@ -426,7 +457,7 @@
starting from the block that was passed in. Because of this, a developer should
always pass in the first block's field (i.e. domain \% blocklist \% struct \%
field) to these routines, and should never put a halo exchange within a block
-loop. A halo exchange within a blockloop will only work properly if there is
+loop. A halo exchange within a block loop will only work properly if there is
only a single block per processor.
A generic interface for halo exchanges of all fields is provided as follows:
@@ -467,14 +498,14 @@
\begin{itemize}
\item Non-Hydrostatic Atmosphere:
\begin{itemize}
- \item Michael Duda (duda@ucar.edu)
- \item Bill Skamarock (skamaroc@ucar.edu)
+ \item Michael Duda
+ \item Bill Skamarock
\end{itemize}
\item Ocean
\begin{itemize}
- \item Doug Jacobsen (jacobsen.douglas@gmail.com)
- \item Mark Petersen (mpetersen@lanl.gov)
- \item Todd Ringler (todd.ringler@mac.com)
+ \item Doug Jacobsen
+ \item Mark Petersen
+ \item Todd Ringler
\end{itemize}
\item Shallow Water
\begin{itemize}
@@ -486,7 +517,7 @@
\chapter{Migrating work from old SVN repository}
As the history of the previous MPAS developer repository is not present in the
new MPAS developer repository, migrating work takes a little bit of effort. The
-workflow for the process is pretty simple, and is detailed below. This example
+work flow for the process is pretty simple, and is detailed below. This example
assumes the branch in both repositories is called feature, and the majority of
it's contributions apply to framework.
@@ -509,7 +540,7 @@
\end{enumerate}
\chapter{Configuring "Push" Notifications}
-By default, fork's on github do not preserve service hooks. This is becuase
+By default, fork's on github do not preserve service hooks. This is because
service hooks might contain private authentication keys for particular
services. Because of this, commit messages on a fork will not (by default)
notify the larger developers mailing list.
</font>
</pre>