contributing.tex

Dolfin provide a high-performance linear algebra library

% This chapter is common to the DOLFIN and FFC manuals.

\chapter{Contributing code}
\index{contributing}

If you have created a new module, fixed a bug somewhere, or have made
a small change which you want to contribute to \package{}, then the
best way to do so is to send us your contribution in the form of a
patch. A patch is a file which describes how to transform a file or
directory structure into another. The patch is built by comparing a
version which both parties have against the modified version which
only you have. Patches can be created with Mercurial
or \texttt{diff}.

%------------------------------------------------------------------------------
\section{Creating bundles/patches}
%------------------------------------------------------------------------------
\subsection{Creating a Mercurial (hg) bundle}
\index{hg}
\index{Mercurial}
\index{bundle}

Creating bundles is the preferred way of submitting patches. It has
several advantages over plain diffs. If you are a frequent
contributor, consider publishing your source tree so that the \ffc{}
maintainers (and other users) may pull your changes directly from your
tree.

A bundle contains your contribution to \package{} in the form of a 
binary patch file  generated by Mercurial~\cite{www:Mercurial},  
the revision control system used by \package{}. 
Follow the procedure described below to create your bundle.
\begin{enumerate}
\item
  Clone the \package{} repository:
  \begin{macrocode}
# hg clone http://www.fenics.org/hg/\packagett{}
  \end{macrocode}
\item \label{label:AddFilesHg} If your contribution consists of new files, 
  add them to the 
  correct location in the \package{} directory tree. Enter the \package{}
  directory and add these files to the local repository by typing:
  \begin{macrocode}
# hg add <files>
  \end{macrocode}
  where \texttt{<files>} is the list of new files.
  You do not have to take any action for previously existing files 
  which have been modified. Do not add temporary or binary files. 
\item Enter the \package{} directory and commit your contribution:
  \begin{macrocode}
# hg commit -m "<description>"
  \end{macrocode}
  where \texttt{<description>} is a short description of what 
  your patch accomplishes.
\item Create the bundle:
  \begin{macrocode}
# hg bundle \packagett{}-<identifier>-<date>.hg 
  http://www.fenics.org/hg/\packagett{}
  \end{macrocode}
  written as one line, where \texttt{<identifier>} is a keyword that
  can be used to identify the bundle as coming from you (your username,
  last name, first name, a nickname etc) and \texttt{<date>} is
  today's date in the format \texttt{yyyy-mm-dd}.\\
  The bundle now exists as \texttt{\packagett{}-<identifier>-<date>.hg}.
\end{enumerate}

When you add your contribution at point~\ref{label:AddFilesHg}, 
make sure that only the files 
that you want to share are present by typing:
\begin{macrocode}
# hg status 
\end{macrocode}
This will produce a list of files. Those marked with a question mark 
are not tracked by Mercurial. You can track them by using the
\texttt{add}  command as shown above. Once you have 
added these files, their status changes form  \texttt{?} to \texttt{A}.
  
  
%------------------------------------------------------------------------------
\subsection{Creating a standard (diff) patch file}
\index{diff}
\index{patch}

The tool used to create a patch is called \texttt{diff} and the tool
used to apply the patch is called \texttt{patch}.

Here's an example of how it works. Start from the latest release of
\package{}, which we here assume is release x.y.z. You then have a
directory structure under \texttt{\packagett{}-x.y.z} where you have made
modifications to some files which you think could be useful to
other users.

\begin{enumerate}
\item
  Clean up your modified directory structure to remove temporary and binary
  files which will be rebuilt anyway:
  \begin{code}
# make clean
  \end{code}
\item
  From the parent directory, rename the \package{} directory to something else:
  \begin{macrocode}
# mv \packagett{}-x.y.z \packagett{}-x.y.z-mod
  \end{macrocode}
\item
  Unpack the version of \package{} that you started from:
  \begin{macrocode}
# tar zxfv \packagett{}-x.y.z.tar.gz
  \end{macrocode}
\item
  You should now have two \package{} directory structures in your current directory:
  \begin{macrocode}
# ls
\packagett{}-x.y.z
\packagett{}-x.y.z-mod
  \end{macrocode}
\item
  Now use the \texttt{diff} tool to create the patch:
  \begin{macrocode}
# diff -u --new-file --recursive \packagett{}-x.y.z
  \packagett{}-x.y.z-mod > \packagett{}-<identifier>-<date>.patch
  \end{macrocode}
  written as one line, where \texttt{<identifier>} is a keyword that
  can be used to identify the patch as coming from you (your username,
  last name, first name, a nickname etc) and \texttt{<date>} is
  today's date in the format \texttt{yyyy-mm-dd}.
\item
  The patch now exists as \texttt{\packagett{}-<identifier>-<date>.patch}
  and can be distributed to other people who already have
  \texttt{\packagett{}-x.y.z} to easily create your modified version. If the
  patch is large, compressing it with for example \texttt{gzip} is
  advisable:
  \begin{macrocode}
# gzip \packagett{}-<identifier>-<date>.patch
  \end{macrocode}
\end{enumerate}

%------------------------------------------------------------------------------
\section{Sending bundles/patches}
\index{patch}
\index{bundle}

Patch and bundle files should be sent to the \package{} mailing list at the address
\begin{macrocode}
\packagett{}[e-mail]
\end{macrocode}
Include a short description of what your patch/bundle accomplishes. Small
patches/bundles have a better chance of being accepted, so if you are making a
major contribution, please consider breaking your changes up into
several small self-contained patches/bundles if possible.

%------------------------------------------------------------------------------
\section{Applying changes}
%------------------------------------------------------------------------------
\subsection{Applying a Mercurial bundle}
\index{bundle}
\index{hg}
\index{Mercurial}

You have received a patch in the form of a Mercurial bundle. The following
procedure shows how to apply the patch to your version of \package{}.
\begin{enumerate}
\item Before applying the patch, you can check
  its content by entering the \package{} directory and typing:
  \begin{macrocode}
# hg incoming -p 
  bundle://<path>/\packagett{}-<identifier>-<date>.hg
  \end{macrocode}
  written as one line, where \texttt{<path>} is the path to the
  bundle. \texttt{<path>} can be omitted if the bundle is in the
  \package{} directory.  The option \texttt{-p} can be omitted if you
  are only interested in a short summary of the changesets found in
  the bundle.
\item To apply the patch to your version of \package{} type:
  \begin{macrocode}
# hg unbundle <path>/\packagett{}-<identifier>-<date>.hg
  \end{macrocode}
  followed by:
  \begin{macrocode}
  # hg update
  \end{macrocode}
\end{enumerate}

%------------------------------------------------------------------------------
\subsection{Applying a standard patch file}
\index{patch}

Let's say that a patch has been built relative to \package{} release x.y.z.
The following description then shows how to apply the patch to a clean
version of release x.y.z.

\begin{enumerate}
\item
  Unpack the version of \package{} which the patch is built relative to:
  \begin{macrocode}
# tar zxfv \packagett{}-x.y.z.tar.gz
  \end{macrocode}
\item
  Check that you have the patch \texttt{\packagett{}-<identifier>-<date>.patch} and the \package{}
  directory structure in the current directory:
  \begin{macrocode}
# ls
\packagett{}-x.y.z
\packagett{}-<identifier>-<date>.patch
  \end{macrocode}
  Unpack the patch file using \texttt{gunzip} if necessary.
\item
  Enter the \package{} directory structure:
  \begin{macrocode}
# cd \packagett{}-x.y.z
  \end{macrocode}
\item
  Apply the patch:
  \begin{macrocode}
# patch -p1 < ../\packagett{}-<identifier>-<date>.patch
  \end{macrocode}
  The option \texttt{-p1} strips the leading directory from the filename
  references in the patch, to match the fact that we are applying the
  patch from inside the directory. Another useful option to
  \texttt{patch} is \texttt{--dry-run} which can be used to test the
  patch without actually applying it.
\item
  The modified version now exists as \texttt{\packagett{}-x.y.z}.
\end{enumerate}