% 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.

%------------------------------------------------------------------------------
\section{Creating a patch}
\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}. These tools are free
software and are standard on most Unix systems.

Here's an example of how it works. Start from the latest release of
\package{}, which we here assume is release 0.1.0. You then have a
directory structure under \texttt{\packagett{}-0.1.0} 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{}-0.1.0 \packagett{}-0.1.0-mod
  \end{macrocode}
\item
  Unpack the version of \package{} that you started from:
  \begin{macrocode}
# tar zxfv \packagett{}-0.1.0.tar.gz
  \end{macrocode}
\item
  You should now have two \package{} directory structures in your current directory:
  \begin{macrocode}
# ls
\packagett{}-0.1.0
\packagett{}-0.1.0-mod
  \end{macrocode}
\item
  Now use the \texttt{diff} tool to create the patch:
  \begin{macrocode}
# diff -u --new-file --recursive \packagett{}-0.1.0
 \packagett{}-0.1.0-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{}-0.1.0} 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 patches}
\index{patch}

Patch files should be sent to the \package{} mailing list at the address
\begin{macrocode}
\packagett{}-dev@fenics.org
\end{macrocode}
Include a short description of what your patch accomplishes. Small
patches 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 if possible.

%------------------------------------------------------------------------------
\section{Applying a patch (maintainers)}
\index{patch}

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

\begin{enumerate}
\item
  Unpack the version of \package{} which the patch is built relative to:
  \begin{macrocode}
# tar zxfv \packagett{}-0.1.0.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{}-0.1.0
\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{}-0.1.0
  \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{}-0.1.0}.
\end{enumerate}
