Author: bugman
Date: Wed Mar 29 09:24:56 2006
New Revision: 2429
URL: http://svn.gna.org/viewcvs/relax?rev=2429&view=rev
Log:
Rearranged the development chapter to create the 'Committers' section.
Modified:
1.2/docs/latex/develop.tex
1.2/docs/relax.pdf
Modified: 1.2/docs/latex/develop.tex
URL:
http://svn.gna.org/viewcvs/relax/1.2/docs/latex/develop.tex?rev=2429&r1=2428&r2=2429&view=diff
==============================================================================
--- 1.2/docs/latex/develop.tex (original)
+++ 1.2/docs/latex/develop.tex Wed Mar 29 09:24:56 2006
@@ -91,17 +91,64 @@
-% Committing conventions.
-%~~~~~~~~~~~~~~~~~~~~~~~~
-
-\section{Committing conventions}
-
-If you are a relax developer and you have commit access to the repository,
the following conventions should be followed.
+% Submitting changes to the relax project.
+%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+\section{Submitting changes to the relax project}
+
+
+% Submitting changes as a patch.
+\subsection{Submitting changes as a patch}
+
+The preferred method for submitting fixes and improvements to the relax
source code is by the creation of a patch. If your changes are a fix, make
sure you have submitted a bug report to the bug tracker located at
\href{https://gna.org/bugs/?group=relax}{https://gna.org/bugs/?group=relax}
first. See section~\ref{reporting bugs} on page~\pageref{reporting bugs} for
more details. Two methods can be used to generate the patch, either using
the Unix command \texttt{diff} or using the Subversion program. The
resultant file \texttt{patch} of either the \texttt{diff} or \texttt{svn}
command described below can be posted to the ``relax-devel at gna.org''
mailing list. Please label within your post which version of relax you
modified or which revision the patch is for. Also try to create a commit log
message according to the format described in section~\ref{commit log format}
on page~\pageref{commit log format} for one of the relax committers to use as
a template for committing the change.
+
+
+% Modification of official releases -- creating patchs with diff.
+\subsection{Modification of official releases -- creating patchs with diff}
+
+If your modifications have been made to the source code of one of the
official relax releases (for example 1.2.2), then the Unix command
\texttt{diff} can be used to create a patch. A patch file is simply the
output of the diff command used recursively and presented in the `unified'
format. Therefore two directories need to be compared. If the original
sources are located in the directory \texttt{relax\_orig} and the modified
sources in \texttt{relax\_mod}, then the patch can be created by typing
+
+\example{\$ diff -ur relax\_orig relax\_mod > patch}
+
+
+% Modification of the latest sources -- creating patchs with Subversion.
+\subsection{Modification of the latest sources -- creating patchs with
Subversion}
+
+If possible, changes to the latest sources is preferred. Using the most up
to date sources from the relax SVN repository will significantly aid the
relax developers to incorporate your changes back into the main development
line. To check out the current development line, see section~\ref{svn
repository} on page~\pageref{svn repository} for details. Prior to
submitting a patch to the mailing list, your sources should be updated to
include the most recent changes. To do this, type
+
+\example{\$ svn up}
+
+and note the revision number to include in your post. The update may cause
a conflict if changes added to the repository clash with your modifications.
If this occurs, see the Subversion book at
\href{http://svnbook.red-bean.com/}{http://svnbook.red-bean.com/} for details
on how to resolve the conflict or submit a message to the relax-devel list.
+
+Once the sources are up to date, your changes can be can be converted into
the patch text file. Using SVN, creating a patch is easy. Just type
+
+\example{\$ svn diff > patch}
+
+in the base relax directory.
+
+
+
+% Committers.
+%~~~~~~~~~~~~
+
+\section{Committers}
+
+
+% Becoming a committer.
+\subsection{Becoming a committer}
+
+After proving oneself, anyone can become a relax developer and obtain commit
access to the relax repository. The main criteria for selection by the relax
developers is to show good judgement, competence in producing good patches,
compliance with the coding and commit log conventions, comportment on the
mailing lists, not producing too many bugs, only taking on challenges which
can be handled, and the skill in judging your own abilities. You will also
need to have an understanding of the concepts of version control,
specifically those relating to Subversion. The SVN book at
\href{http://svnbook.red-bean.com/}{http://svnbook.red-bean.com/} contains
all the version control information you will need. After a number of patches
have been submitted and accepted, any of the relax developers can propose
that you receive commit access. If a number of developers agree while no one
says no, then commit access will be offered.
+
+One area where coding ability can be demonstrated is within the relax test
suite. The addition of tests, especially those where the relax internal data
structures of \texttt{self.relax.data} are scrutinised, can be a good
starting point for learning the structure of relax. The beauty of the tests
is that the introduction of bugs has no effect on normal program execution.
The relax test suite is an ideal proving ground.
+
+If skills in only certain areas of relax development, for example in
creation of the documentation, an understanding of C but not python, an
understanding of solely the code of the user interface, or an understanding
of the code specific to a certain type of data analysis methodology, then
partial commit access may be granted. Although you will have the ability to
make modifications to any part of the repository, please make modifications
only those areas for which you have permission.
% Format of the commit logs.
\subsection{Format of the commit logs}\label{commit log format}
+If you are a relax developer and you have commit access to the repository,
the following conventions should be followed.
+
The length of all lines in the commit log should never exceed 100
characters. This is so that the log message viewed in either emails or by
the command prompt command \mbox{\texttt{svn log}} is legible. The first
line of the commit log should be a short description or synopsis of the
changes. The second line should be blank.
If the commit is a bug fix reported by someone else or if the commit
originates from a patch posted by someone else, the next lines should be
reserved for crediting. The name of the person and their obfuscated email
address (for example edward at nmr-relax.com) should be included in the
message.
@@ -109,55 +156,6 @@
If the commit relates to an entry in the bug tracker or to a discussion on
the mailing lists, then the web address of either the bug report or the
mailing list archive message should be cited in the next section (separated
from the synopsis or credit section by a blank line). All relevant links
should be included to allow easy navigation between the repository, mailing
lists, bug tracker, etc. An example is bug \#5559 which is located at
\href{https://gna.org/bugs/?func=detailitem\&item\_id=5559}{https://gna.org/bugs/?func=detailitem\&item\_id=5559}
and the post to ``relax-devel at gna.org'' describing the fix to that bug
which is located at
\href{https://mail.gna.org/public/relax-devel/2006-03/msg00013.html}{https://mail.gna.org/public/relax-devel/2006-03/msg00013.html}.
A full description containing all the details can follow. This description
should follow a blank line, can itself be sectioned using blank lines, and
finally the log is terminated by one blank line at the end of the message.
-
-
-
-
-% Submitting changes to the relax project.
-%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-\section{Submitting changes to the relax project}
-
-
-% Submitting changes as a patch.
-\subsection{Submitting changes as a patch}
-
-The preferred method for submitting fixes and improvements to the relax
source code is by the creation of a patch. If your changes are a fix, make
sure you have submitted a bug report to the bug tracker located at
\href{https://gna.org/bugs/?group=relax}{https://gna.org/bugs/?group=relax}
first. See section~\ref{reporting bugs} on page~\pageref{reporting bugs} for
more details. Two methods can be used to generate the patch, either using
the Unix command \texttt{diff} or using the Subversion program. The
resultant file \texttt{patch} of either the \texttt{diff} or \texttt{svn}
command described below can be posted to the ``relax-devel at gna.org''
mailing list. Please label within your post which version of relax you
modified or which revision the patch is for. Also try to create a commit log
message according to the format described in section~\ref{commit log format}
on page~\pageref{commit log format} for one of the relax committers to use as
a template for committing the change.
-
-
-% Modifications of official releases -- creating patchs with diff.
-\subsection{Modifications of the latest sources -- creating patchs with diff}
-
-If your modifications have been made to the source code of one of the
official relax releases (for example 1.2.2), then the Unix command
\texttt{diff} can be used to create a patch. A patch file is simply the
output of the diff command used recursively and presented in the `unified'
format. Therefore two directories need to be compared. If the original
sources are located in the directory \texttt{relax\_orig} and the modified
sources in \texttt{relax\_mod}, then the patch can be created by typing
-
-\example{\$ diff -ur relax\_orig relax\_mod > patch}
-
-
-% Modifications of the latest sources -- creating patchs with Subversion.
-\subsection{Modifications of the latest sources -- creating patchs with
Subversion}
-
-If possible, changes to the latest sources is preferred. Using the most up
to date sources from the relax SVN repository will significantly aid the
relax developers to incorporate your changes back into the main development
line. To check out the current development line, see section~\ref{svn
repository} on page~\pageref{svn repository} for details. Prior to
submitting a patch to the mailing list, your sources should be updated to
include the most recent changes. To do this, type
-
-\example{\$ svn up}
-
-and note the revision number to include in your post. The update may cause
a conflict if changes added to the repository clash with your modifications.
If this occurs, see the Subversion book at
\href{http://svnbook.red-bean.com/}{http://svnbook.red-bean.com/} for details
on how to resolve the conflict or submit a message to the relax-devel list.
-
-Once the sources are up to date, your changes can be can be converted into
the patch text file. Using SVN, creating a patch is easy. Just type
-
-\example{\$ svn diff > patch}
-
-in the base relax directory.
-
-
-
-% Becoming a committer.
-\subsection{Becoming a committer}
-
-After proving oneself, anyone can become a relax developer and obtain commit
access to the relax repository. The main criteria for selection by the relax
developers is to show good judgement, competence in producing good patches,
compliance with the coding and commit log conventions, comportment on the
mailing lists, not producing too many bugs, only taking on challenges which
can be handled, and the skill in judging your own abilities. You will also
need to have an understanding of the concepts of version control,
specifically those relating to Subversion. The SVN book at
\href{http://svnbook.red-bean.com/}{http://svnbook.red-bean.com/} contains
all the version control information you will need. After a number of patches
have been submitted and accepted, any of the relax developers can propose
that you receive commit access. If a number of developers agree while no one
says no, then commit access will be offered.
-
-One area where coding ability can be demonstrated is within the relax test
suite. The addition of tests, especially those where the relax internal data
structures of \texttt{self.relax.data} are scrutinised, can be a good
starting point for learning the structure of relax. The beauty of the tests
is that the introduction of bugs has no effect on normal program execution.
The relax test suite is an ideal proving ground.
-
-If skills in only certain areas of relax development, for example in
creation of the documentation, an understanding of C but not python, an
understanding of solely the code of the user interface, or an understanding
of the code specific to a certain type of data analysis methodology, then
partial commit access may be granted. Although you will have the ability to
make modifications to any part of the repository, please make modifications
only those areas for which you have permission.
Modified: 1.2/docs/relax.pdf
URL:
http://svn.gna.org/viewcvs/relax/1.2/docs/relax.pdf?rev=2429&r1=2428&r2=2429&view=diff
==============================================================================
Binary files - no diff available.
r2429 - in /1.2/docs: latex/develop.tex relax.pdf