Author: bugman
Date: Thu Apr 24 14:23:40 2008
New Revision: 5971
URL: http://svn.gna.org/viewcvs/relax?rev=5971&view=rev
Log:
Rewrote the branches section of the development chapter to describe the use
of svnmerge.py.
Modified:
1.3/docs/latex/develop.tex
Modified: 1.3/docs/latex/develop.tex
URL:
http://svn.gna.org/viewcvs/relax/1.3/docs/latex/develop.tex?rev=5971&r1=5970&r2=5971&view=diff
==============================================================================
--- 1.3/docs/latex/develop.tex (original)
+++ 1.3/docs/latex/develop.tex Thu Apr 24 14:23:40 2008
@@ -365,10 +365,14 @@
\index{branches|textbf}
\index{repository!branches|textbf}
-If a change is likely to be disruptive or cause breakages in the program the
use of your own temporary branch is recommended. This private branch is a
complete copy of one of the main development lines wherein you can make
changes without disrupting the other developers. Although called a private
branch every change is visible to all other developers and each commit will
result in an automatic email to the relax-commits mailing list\index{mailing
list!relax-commits}. Other developers are even able to check out your branch
and make modifications to it. Private branches can also be used for testing
ideas. If the idea does not work the branch can be deleted from the
repository (in reality the branch will always exist between the revision
numbers of its creation and deletion and can always be resurrected). For
example to create a branch from the main 1.2 development line called
\texttt{molmol\_macros} whereby new Molmol macros are to be written, type
+
+\subsubsection{Branch creation}
+\index{repository!branch creation}
+
+If a change is likely to be disruptive or cause breakages in the program,
the use of your own temporary branch is recommended. This private branch is
a complete copy of one of the main development lines wherein you can make
changes without disrupting the other developers. Although called a private
branch every change is visible to all other developers and each commit will
result in an automatic email to the relax-commits mailing list\index{mailing
list!relax-commits}. Other developers are even able to check out your branch
and make modifications to it. Private branches can also be used for testing
ideas. If the idea does not work the branch can be deleted from the
repository (in reality the branch will always exist between the revision
numbers of its creation and deletion and can always be resurrected). For
example to create a branch from the main 1.2 development line called
\texttt{molmol\_macros} whereby new Molmol macros are to be written, type
\begin{exampleenv}
-\$ svn cp svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/1.2 $\backslash$ \\
+\$ svn cp svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/1.3 $\backslash$ \\
svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/branches/molmol\_macros
\end{exampleenv}
@@ -376,24 +380,42 @@
\example{\$ svn co
svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/branches/molmol\_macros}
-which will create a directory called \texttt{molmol\_macros} containing all
the relax source files. To have the files dumped into a different directory
type the name of that directory at the end of the last command.
Modifications can be made to this copy while normal development continues on
the main line. Once the desired changes have been made and reviewed the
changes which have occurred on the main line can be merged into your
branch\index{merge}\index{repository!merge}. If development is taking a long
time then merging should occur on a regular basis to avoid large incompatible
changes forming between the two branches. For example to merge the changes
which have occurred between the initial branch, say r2351 (revision number
2351), and r2378 of the main development line type in the base directory of
your branch
-
-\example{\$ svn merge -r2351:2378 svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/1.2
.}
-\index{Subversion!merge}
-
-The differences will have been merged into your checked out copy. If
conflicts\index{Subversion!conflict} have occurred see the Subversion book at
\href{http://svnbook.red-bean.com/}{http://svnbook.red-bean.com/} for
information on how to resolve the problem. Otherwise the changes to your
branch can be committed:
-
-\example{\$ svn ci}
+which will create a directory called \texttt{molmol\_macros} containing all
the relax source files. To have the files placed into a different directory,
type the name of that directory at the end of the last command.
Modifications can be made to this copy while normal development continues on
the main line.
+
+
+\subsubsection{Keeping the branch up to date using \texttt{svnmerge.py}}
+\index{svnmerge.py}
+\index{repository!keeping up to date}
+\index{repository!svnmerge.py}
+
+As you develop your branch, changes will be occurring simultaneously within
the main line. These changes should be merged into your branch on a regular
basis to avoid large incompatible changes from forming between the two
branches. To simplify this process, the \texttt{svnmerge.py} script located
at
\href{http://www.orcaware.com/svn/wiki/Svnmerge.py}{http://www.orcaware.com/svn/wiki/Svnmerge.py}
can be used. It is best to download the trunk version from that page,
unless that version is non-functional. Once you have this script, the
merging from the main line to your private branch must be initialised by
typing, from within the checked out copy of your branch,
+
+\example{\$ svnmerge.py init}
+\index{Subversion!svnmerge.py init}
+
+This then needs to be committed using the automatically generated log
+
+\example{\$ svn ci -F svnmerge-commit-message.txt}
\index{Subversion!commit}
-Make sure to include in your commit message the revision numbers which have
been merged (cutting and pasting the command would be useful). This is
important because if new changes need to be merged again, for example up to
r2401, then you will need to type
-
-\example{\$ svn merge -r2378:2401 svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/1.2
.}
-\index{Subversion!merge}
-
-Note that the changes from r2351 to r2378 have not been merged for a second
time. This is important and is the reason that the revision numbers need to
be noted in the commit logs. Once you have completed your modifications, you
have merged all changes which have occurred in the main line, and the changes
have been approved for merging back into the main line then your branch can
be merged. First check out a copy of the main line,
-
-\example{\$ svn co svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/1.2 relax}
+To keep up to date, simply type
+
+\example{\$ svnmerge.py merge}
+\index{Subversion!svnmerge.py merge}
+
+
+If conflicts\index{Subversion!conflict} have occurred please refer to the
Subversion book at
\href{http://svnbook.red-bean.com/}{http://svnbook.red-bean.com/} for
information on how to resolve the problem. Otherwise, or once fixed, the
main line revisions merged into your branch can be committed using the
automatically generated log file:
+
+\example{\$ svn ci -F svnmerge-commit-message.txt}
+\index{Subversion!commit}
+
+
+\subsubsection{Merging the branch back into the main line}
+\index{repository!merging branch back}
+
+Once you have completed the modifications desired for your branch, all
changes which have occurred in the main line have been merged using
\texttt{svnmerge.py}, and the changes have been approved for merging back
into the main line -- then your branch can be merged. First check out a copy
of the main line,
+
+\example{\$ svn co svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/1.3 relax-1.3}
\index{Subversion!check out}
or update a previously checked out version,
@@ -401,12 +423,31 @@
\example{\$ svn up}
\index{Subversion!update}
-Assuming the initial branch occurred at r2351 and the final modification
occurred at r2430 then in the base directory of the checked out main line type
-
-\example{\$ svn merge -r2351:2430
svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/branches/molmol\_macros .}
+Then \texttt{svnmerge.py} can be utilised again. First initialise the
merging process by typing, from within the checked out copy of the main line,
+
+\example{\$ svnmerge.py init
svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/branches/molmol\_macros}
+\index{Subversion!svnmerge.py init}
+
+Then commit the change
+
+\example{\$ svn ci -F svnmerge-commit-message.txt}
+\index{Subversion!commit}
+
+To merge the branch and commit the changes, type
+
+\example{\$ svnmerge.py merge --bidirectional}
+\index{Subversion!svnmerge.py merge}
+
+\example{\$ svn ci -F svnmerge-commit-message.txt}
+\index{Subversion!commit}
+
+Finally the merge properties need to be removed
+
+\example{\$ svnmerge.py uninit -S
svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/branches/molmol\_macros}
+\index{Subversion!svnmerge.py uninit}
\index{Subversion!merge}
-and then check in the modifications. Your changes will now be present in
the main line. The last step is to delete your private branch
+and your private branch deleted
\example{\$ svn rm
svn+ssh://xxxxx@xxxxxxxxxxx/svn/relax/branches/molmol\_macros}
\index{Subversion!remove}
r5971 - /1.3/docs/latex/develop.tex