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.
_______________________________________________
relax (http://nmr-relax.com)
This is the relax-commits mailing list
relax-commits@gna.org
To unsubscribe from this list, get a password
reminder, or change your subscription options,
visit the list information page at
https://mail.gna.org/listinfo/relax-commits
