Author: bugman
Date: Wed Mar 29 09:10:43 2006
New Revision: 2428
URL: http://svn.gna.org/viewcvs/relax?rev=2428&view=rev
Log:
Significant improvements to the patching section of the development chapter.
Modified:
1.2/docs/latex/develop.tex
1.2/docs/latex/infrastruct.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=2428&r1=2427&r2=2428&view=diff
==============================================================================
--- 1.2/docs/latex/develop.tex (original)
+++ 1.2/docs/latex/develop.tex Wed Mar 29 09:10:43 2006
@@ -10,7 +10,7 @@
% Version control using Subversion.
%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-\section{Version control using Subversion}
+\section{Version control using Subversion}\label{svn repository}
The development of relax requires the use of the Subversion (SVN) version
control software
\href{http://subversion.tigris.org/}{http://subversion.tigris.org/}. The
source code to relax is stored in an SVN repository located at
\href{http://svn.gna.org/svn/relax/}{http://svn.gna.org/svn/relax/}. Every
single change ever made to the program is recorded in this repository, for
more information see the open source infrastructure chapter.
@@ -24,7 +24,7 @@
\example{\$ svn co svn+ssh://user\_name@xxxxxxxxxxx/svn/relax/1.2 relax}
-replacing \texttt{user\_name} with your Gna! login name. If your version is
out of data, it can be updated to the latest revision by typing
+replacing \texttt{user\_name} with your Gna! login name. If your version is
out of date, it can be updated to the latest revision by typing
\example{\$ svn up}
@@ -100,39 +100,54 @@
% Format of the commit logs.
-\subsection{Format of the commit logs}
+\subsection{Format of the commit logs}\label{commit log format}
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.
-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.
+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.
-% Making changes.
-%~~~~~~~~~~~~~~~~
-
-\section{Making changes}
-
-
-% Patching.
-\subsection{Patching}
-
-Fixes and improvements to the relax source code can be posted to the
relax-devel mailing list in the form of a patch. The modified sources need
be a checked out version of the one of the directories in the relax
repository. Prior to submitting a patch to the mailing list, your sources
should be updated to include the most recent changes. To do this, type
+% 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. 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.
-
-Once the sources are up to date, your changes can be can be converted into a
text file called a patch. Using SVN, creating a patch is easy. Just type
+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 and then send the file `patch' to the
``relax-devel at gna.org'' mailing list. The patch is simply the output of
the Unix diff command in the unified format. Make sure you label in your
post which revision the patch is for. Also try to create a commit log
message according to the format described above for one of the relax
committers to copy and possibly modify.
+in the base relax directory.
+
% Becoming a committer.
Modified: 1.2/docs/latex/infrastruct.tex
URL:
http://svn.gna.org/viewcvs/relax/1.2/docs/latex/infrastruct.tex?rev=2428&r1=2427&r2=2428&view=diff
==============================================================================
--- 1.2/docs/latex/infrastruct.tex (original)
+++ 1.2/docs/latex/infrastruct.tex Wed Mar 29 09:10:43 2006
@@ -39,7 +39,7 @@
% Reporting bugs.
%~~~~~~~~~~~~~~~~
-\section{Reporting bugs}
+\section{Reporting bugs}\label{reporting bugs}
\index{bugs}
One of the philosophies in the construction of relax is that if there is
something which is not immediately obvious, then that is considered a design
bug. If any flaws in relax are uncovered, including general design flaws,
bugs in the code, or documentation issues, these can be reported within
relax's bug tracker system. The link to submit a bug is
\href{https://gna.org/bugs/?group=relax\&func=additem}{https://gna.org/bugs/?group=relax\&func=additem}
while the main page for browsing, submitting, viewing the statistics, or
searching through the data base is at
\href{https://gna.org/bugs/?group=relax}{https://gna.org/bugs/?group=relax}.
Please do not report bugs to personal email addresses or to the mailing lists.
Modified: 1.2/docs/relax.pdf
URL:
http://svn.gna.org/viewcvs/relax/1.2/docs/relax.pdf?rev=2428&r1=2427&r2=2428&view=diff
==============================================================================
Binary files - no diff available.
r2428 - in /1.2/docs: latex/develop.tex latex/infrastruct.tex relax.pdf