]> git.sur5r.net Git - bacula/docs/commitdiff
Update git pointers
authorKern Sibbald <kern@sibbald.com>
Thu, 20 Aug 2009 10:56:11 +0000 (10:56 +0000)
committerKern Sibbald <kern@sibbald.com>
Thu, 20 Aug 2009 10:56:11 +0000 (10:56 +0000)
15 files changed:
docs/home-page/de/pages/home.php
docs/home-page/en/pages/home.php
docs/home-page/es/pages/home.php
docs/home-page/fr/pages/home.php
docs/manuals/de/developers/generaldevel.tex
docs/manuals/en/developers/generaldevel.tex
docs/manuals/es/catalog/version.tex
docs/manuals/es/concepts/version.tex
docs/manuals/es/console/version.tex
docs/manuals/es/developers/generaldevel.tex
docs/manuals/es/developers/version.tex
docs/manuals/es/install/version.tex
docs/manuals/es/problems/version.tex
docs/manuals/es/utility/version.tex
docs/manuals/fr/developers/generaldevel.tex

index 3077b7d8218fb7baada5bb3b24652481f6153ab6..3a9b06a18f452c65d2a5cf6591581f9b9ddc2d4f 100644 (file)
@@ -32,7 +32,7 @@
 
         &Uuml;ber dem Link "Dokumentation" haben Sie Zugriff auf alle zur Verf&uuml;gung stehenden Beschreibungen
         (HTML und PDF-Format) der offiziell freigegebenen Bacula-Version, sowie der Dokumentation des aktuellen
-        Entwicklungszweigs im SourceForge SVN.
+        Entwicklungszweigs im SourceForge GIT.
         Die Entwicklungs-Version des Handbuchs enth&auml;lt typischerweise mehr an Informationen,
         dokumentiert aber auch neue Funktionen, die die freigegebene Version noch nicht unterst&uuml;tzt.
         Das Entwickler-Handbuch enth&auml;lt wichtige Informationen f&uuml;r alle die aktiv am
index be53ff0dd26d41a360f0f1b0858d5ab7f0fa1df3..426501e105a22ceae034dbfd85636067097dc77f 100644 (file)
      can access all the available Bacula documentation (HTML,
      PDF, and TGZ) both for the officially released version 
      and for the current code under development in the Source
-     Forge SVN. The development version of the manual typically has
+     Forge GIT. The development version of the manual typically has
      more documentation, but may also document new features that are
      not in the released version.  The <b>Developer's Guide</b>
      presents important information for users who want to
index 75a54e6d1d6b9e9357888925184840fa3610809d..d760494896b8647c704b79523cb7a940dbc50a05 100644 (file)
      can access all the available Bacula documentation (HTML,
      PDF, and TGZ) both for the officially released version 
      and for the current code under development in the Source
-     Forge SVN. The development version of the manual typically has
+     Forge GIT. The development version of the manual typically has
      more documentation, but may also document new features that are
      not in the released version.  The <b>Developer's Guide</b>
      presents important information for users who want to
index 65596589000c264909f12cf6bc8bb42c964b1529..ff377c5bd96e7d00279d1c18fa5b7bb34f77671e 100644 (file)
      <br>Le lien Documentation pointe sur une page qui permet d'acc&eacute;der &aacute;
      toutes les documentations de Bacula disponibles (HTML, PDF et TGZ) que ce
      soit pour la derni&egrave;re version officielle ou bien pour le code
-     actuellement en cours de d&eacute;veloppement dans le CVS SourceForge.
+     actuellement en cours de d&eacute;veloppement dans le GIT SourceForge.
      La version de d&eacute;veloppement du manuel contient plus de documentation, mais
      aussi la documentation des derni&egrave;res fonctionnalit&eacute;s qui ne sont pas
      encore incluses dans la derni&egrave;re version publi&eacute;e.
index 9404e57e9e72b42b5e627f2cd858be188dc5d244..74a8a2a46f2879d9c99a05409a8c5dddf8900c8b 100644 (file)
@@ -7,29 +7,32 @@
 \index{Notes!Bacula Developer}
 \addcontentsline{toc}{section}{Bacula Developer Notes}
 
-\section{General}
-\index{General}
-\addcontentsline{toc}{subsection}{General}
-
-This document is intended mostly for developers and describes the the general
-framework of making Bacula source changes. 
+This document is intended mostly for developers and describes how you can
+contribute to the Bacula project and the the general framework of making
+Bacula source changes.
 
 \subsection{Contributions}
 \index{Contributions}
 \addcontentsline{toc}{subsubsection}{Contributions}
 
-Contributions from programmers are broken into two groups. The first are
-contributions that are aids and not essential to Bacula. In general, these
-will be scripts or will go into and examples or contributions directory. 
-For these kinds of non-essential contributions there is no obligation to do
-a copyright assignment as described below. However, a copyright assignment
-would still be appreciated.
+Contributions to the Bacula project come in many forms: ideas,
+participation in helping people on the bacula-users email list, packaging
+Bacula binaries for the community, helping improve the documentation, and
+submitting code.
+
+Contributions in the form of submissions for inclusion in the project are
+broken into two groups.  The first are contributions that are aids and not
+essential to Bacula.  In general, these will be scripts or will go into the
+{\bf bacula/examples} directory.  For these kinds of non-essential
+contributions there is no obligation to do a copyright assignment as
+described below.  However, a copyright assignment would still be
+appreciated.
 
 The second class of contributions are those which will be integrated with
-Bacula and become an essential part. Within this class of contributions, there
-are two hurdles to surmount. One is getting your patch accepted, and two is
-dealing with copyright issues. The following text describes some of the
-requirements for such code. 
+Bacula and become an essential part (code, scripts, documentation, ...)
+Within this class of contributions, there are two hurdles to surmount.  One
+is getting your patch accepted, and two is dealing with copyright issues.
+The following text describes some of the requirements for such code.
 
 \subsection{Patches}
 \index{Patches}
@@ -37,10 +40,18 @@ requirements for such code.
 
 Subject to the copyright assignment described below, your patches should be
 sent in {\bf diff -u} format relative to the current contents of the Source
-Forge SVN, which is the easiest to understand and integrate.
-Please be sure to use the Bacula indenting standard (see below).
-If you have checked out the source with SVN, you can get a diff using:
+Forge GIT repository or SVN repository.  The diff -u format is the easiest
+for us to understand and integrate.  Please be sure to use the Bacula
+indenting standard (see below) for source code.  If you have checked out
+the source with GIT or SVN, you can get a diff using.
+
+For the bacula, gui, and regress directories:
+\begin{verbatim}
+git pull
+git diff >change.patch
+\end{verbatim}
 
+For the docs or rescue directories:
 \begin{verbatim}
 svn update 
 svn diff > change.patch
@@ -48,8 +59,8 @@ svn diff > change.patch
      
 If you plan on doing significant development work over a period of time,
 after having your first patch reviewed and approved, you will be eligible
-for having developer SVN access so that you can commit your changes
-directly to the SVN repository.  To do so, you will need a userid on Source
+for having developer GIT or SVN write access so that you can commit your changes
+directly to the GIT or SVN repository.  To do so, you will need a userid on Source
 Forge.
 
 \subsection{Copyrights}
@@ -60,28 +71,31 @@ To avoid future problems concerning changing licensing or
 copyrights, all code contributions more than a hand full of lines
 must be in the Public Domain or have the copyright transferred to
 the Free Software Foundation Europe e.V. with a Fiduciary License
-Agreement (FLA) as in the current code.  Note, prior to
-November 2004, the code was copyrighted by Kern Sibbald and John
-Walker.  After November 2004, the code was copyrighted by Kern
-Sibbald, then on the 15th of November 2006, the copyright was
-transferred to the Free Software Foundation Europe e.V.
+Agreement (FLA) as the case for all the current code.  
+
+Prior to November 2004, all the code was copyrighted by Kern Sibbald and
+John Walker.  After November 2004, the code was copyrighted by Kern
+Sibbald, then on the 15th of November 2006, Kern transferred the copyright
+to the Free Software Foundation Europe e.V. In signing the FLA and
+transferring the copyright, you retain the right to use the code you have
+submitted as you want, and you ensure that Bacula will always remain Free
+and Open Source.
 
 Your name should be clearly indicated as the author of the code, and you
-must be extremely careful not to violate any copyrights or use other
-people's code without acknowledging it.  The purpose of this requirement is
-to avoid future copyright, patent, or intellectual property problems.  
-Please read the LICENSE agreement in the main source code
-directory.  When you sign the Fiduciary License Agreement (FLA)
-and send it in, you are argeeing to the terms of that LICENSE
-file.
-
-To understand the possible source of future problems, please
-examine the difficulties Mozilla is (was?) having finding
+must be extremely careful not to violate any copyrights or patents or use
+other people's code without acknowledging it.  The purpose of this
+requirement is to avoid future copyright, patent, or intellectual property
+problems.  Please read the LICENSE agreement in the main Bacula source code
+directory.  When you sign the Fiduciary License Agreement (FLA) and send it
+in, you are agreeing to the terms of that LICENSE file.
+
+If you don't understand what we mean by future problems, please
+examine the difficulties Mozilla was having finding
 previous contributors at \elink{
 http://www.mozilla.org/MPL/missing.html}
 {http://www.mozilla.org/MPL/missing.html}. The other important issue is to
-avoid copyright, patent, or intellectual property violations as are currently
-(May 2003) being claimed by SCO against IBM. 
+avoid copyright, patent, or intellectual property violations as was
+(May 2003) claimed by SCO against IBM. 
 
 Although the copyright will be held by the Free Software
 Foundation Europe e.V., each developer is expected to indicate
@@ -91,7 +105,7 @@ unusual, but in reality, it is not.  Most large projects require
 this.
 
 If you have any doubts about this, please don't hesitate to ask.  The
-objective is to assure the long term servival of the Bacula project. 
+objective is to assure the long term survival of the Bacula project. 
 
 Items not needing a copyright assignment are: most small changes,
 enhancements, or bug fixes of 5-10 lines of code, which amount to    
@@ -108,24 +122,23 @@ explicitly acknowledging that they do so in their first submission.  This
 was sufficient if the developer is independent, or an employee of a
 not-for-profit organization or a university.  However, in an effort to
 ensure that the Bacula code is really clean, beginning in August 2006, all
-previous and future developers with SVN access will be asked to submit a
+previous and future developers with SVN write access will be asked to submit a
 copyright assignment (or Fiduciary License Agreement -- FLA),
 which means you agree to the LICENSE in the main source
 directory. It also means that you receive back the right to use
 the code that you have submitted.
 
 Any developer who wants to contribute and is employed by a company should
-either list the employer as the owner of the code, or get
-explicit permission from him to sign the copyright assignment.
-This is because in many
-countries, all work that an employee does whether on company time or in the
-employee's free time is considered to be Intellectual Property of the
-company.  Obtaining official approval or an FLA from the company will avoid
-misunderstandings between the employee, the company, and the Bacula
+either list the employer as the owner of the code, or get explicit
+permission from him to sign the copyright assignment.  This is because in
+many countries, all work that an employee does whether on company time or
+in the employee's free time is considered to be Intellectual Property of
+the company.  Obtaining official approval or an FLA from the company will
+avoid misunderstandings between the employee, the company, and the Bacula
 project.  A good number of companies have already followed this procedure.
 
 The Fiduciary License Agreement is posted on the Bacula web site at:
-\elink{http://www.bacula.org/FLA-bacula.en.pdf}{http://www.bacula.org/FLA-bacula.en.pdf}
+\elink{http://www.bacula.org/en/FLA-bacula.en.pdf}{http://www.bacula.org/en/FLA-bacula.en.pdf}
 
 The instructions for filling out this agreement are also at:
 \elink{http://www.bacula.org/?page=fsfe}{http://www.bacula.org/?page=fsfe}
@@ -133,17 +146,17 @@ The instructions for filling out this agreement are also at:
 It should be filled out, then sent to:
 
 \begin{verbatim}
-     Free Software Foundation Europe
-     Freedom Task Force
-     Sumatrastrasse 25
-     8006 Zürich
+     Kern Sibbald
+     Cotes-de-Montmoiret 9
+     1012 Lausanne
      Switzerland
 \end{verbatim}
 
 Please note that the above address is different from the officially
 registered office mentioned in the document.  When you send in such a
-complete document, please notify me: kern at sibbald dot com.
-
+complete document, please notify me: kern at sibbald dot com, and 
+please add your email address to the FLA so that I can contact you
+to confirm reception of the signed FLA.
 
 
 \section{The Development Cycle}
@@ -151,44 +164,48 @@ complete document, please notify me: kern at sibbald dot com.
 \index{Cycle!Developement}
 \addcontentsline{toc}{subsubsection}{Development Cycle}
 
-As I noted in the 1.38 ReleaseNotes, version 1.38 was different from prior
-versions because it had a lot more contributions.  I expect that this trend
-will continue.  As a consequence, I am going to modify how I normally do
-development, and instead of making a list of all the features that I will
-implement in the next version, I will personally sign up for one (maybe
-two) projects at a time, and when they are complete, I will release a new
-version.
-
-The difference is that I will have more time to review the new code that is
-being contributed, and will be able to devote more time to a smaller number
-of projects (1.38 had too many new features for me to handle correctly).
-
-I expect that future release schedules will be much the same, and the
+As I noted in previous emails the number of contributions are
+increasing significantly.  We expect this positive trend
+will continue.  As a consequence, we have modified how we do
+development, and instead of making a list of all the features that we will
+implement in the next version, each developer signs up for one (maybe
+two) projects at a time, and when they are complete, and the code
+is stable, we will release a new version.  The release cycle will probably
+be roughly six months.
+
+The difference is that with a shorter release cycle and fewer released
+feature, we will have more time to review the new code that is being
+contributed, and will be able to devote more time to a smaller number of
+projects (some prior versions had too many new features for us to handle
+correctly).
+
+Future release schedules will be much the same, and the
 number of new features will also be much the same providing that the
 contributions continue to come -- and they show no signs of let up :-)
 
 \index{Feature Requests}
 {\bf Feature Requests:} \\
-In addition, I would like to "formalize" the feature requests a bit.
+In addition, we have "formalizee" the feature requests a bit.
 
 Instead of me maintaining an informal list of everything I run into 
-(kernstodo), I would like to maintain a "formal" list of projects.  This 
+(kernstodo), we now maintain a "formal" list of projects.  This 
 means that all new feature requests, including those recently discussed on 
 the email lists, must be formally submitted and approved. 
 
 Formal submission of feature requests will take two forms: \\
 1. non-mandatory, but highly recommended is to discuss proposed new features
 on the mailing list.\\
-2.  Formal submission of an Feature Request in a special format.
-I'll give an example of this below, but you can also find it on the web
-site under "Support -\gt{} Feature Requests".  Since it takes a bit of time to
-properly fill out a Feature Request form, you probably should check on the email list
-first.
+2.  Formal submission of an Feature Request in a special format.  We'll
+give an example of this below, but you can also find it on the web site
+under "Support -\gt{} Feature Requests".  Since it takes a bit of time to
+properly fill out a Feature Request form, you probably should check on the
+email list first.
 
 Once the Feature Request is received by the keeper of the projects list, it
-will be sent to me, and  I will either accept it, send it back
-asking for clarification, send it to the email list asking for opinions, or
-reject it.
+will be sent to the Bacula project manager (Kern), and he will either
+accept it (90% of the time), send it back asking for clarification (10% of
+the time), send it to the email list asking for opinions, or reject it
+(very few cases).
 
 If it is accepted, it will go in the "projects" file (a simple ASCII file) 
 maintained in the main Bacula source directory.
@@ -203,11 +220,12 @@ Acceptance of Feature Requests depends on several things: \\
 1.  feedback from users.  If it is negative, the Feature Request will probably not be
 accepted.  \\
 2.  the difficulty of the project.  A project that is so
-difficult that I cannot imagine finding someone to implement probably won't
-be accepted. \\
- 3.  whether or not the Feature Request fits within the
-current stategy of Bacula (for example an Feature Request that requests changing the
-tape to tar format would not be accepted, ...)
+difficult that we cannot imagine finding someone to implement probably won't
+be accepted. Obviously if you know how to implement it, don't hesitate
+to put it in your Feature Request  \\
+ 3.  whether or not the Feature Request fits within the current strategy of
+Bacula (for example an Feature Request that requests changing the tape to
+tar format probably would not be accepted, ...).
 
 {\bf How Feature Requests are prioritized:}\\
 Once an Feature Request is accepted, it needs to be implemented.  If you
@@ -219,13 +237,12 @@ for the next version, and by way of this email, we suggest that you send
 discuss and send in your Feature Requests for the next release.  Please
 verify that the Feature Request is not in the current list (attached to this email).
 
-Once users have had several weeks to submit Feature Requests, the keeper of the
-projects list will
-organize them, and request users to vote on them.  This will allow fixing
-prioritizing the Feature Requests.  Having a priority is one thing, but
-getting it implement is another thing -- we are hoping that the Bacula
-community will take more responsibility for assuring the implementation of
-accepted Feature Requests.
+Once users have had several weeks to submit Feature Requests, the keeper of
+the projects list will organize them, and request users to vote on them.
+This will allow fixing prioritizing the Feature Requests.  Having a
+priority is one thing, but getting it implement is another thing -- we are
+hoping that the Bacula community will take more responsibility for assuring
+the implementation of accepted Feature Requests.
 
 Feature Request format:
 \begin{verbatim}
@@ -285,37 +302,39 @@ Getting code implemented in Bacula works roughly as follows:
 
 \item Kern is the project manager, but prefers not to be a "gate keeper".
       This means that the developers are expected to be self-motivated,
-      and once they have experience submit directly to the SVN.  However,
+      and once they have experience submit directly to the GIT or SVN
+      repositories. However,
       it is a good idea to have your patches reviewed prior to submitting,
       and it is a bad idea to submit monster patches because no one will
       be able to properly review them. See below for more details on this.
 
 \item  There are growing numbers of contributions (very good).
 
-\item Some contributions come in  the form of relatively small patches,
+\item Some contributions come in the form of relatively small patches,
      which Kern reviews, integrates, documents, tests, and maintains.
 
 \item All Bacula developers take full
-   responsibility for writing the code, posting as patches so that I can
+   responsibility for writing the code, posting as patches so that we can
    review it as time permits, integrating it at an appropriate time,
-   responding to my requests for tweaking it (name changes, ...),
+   responding to our requests for tweaking it (name changes, ...),
    document it in the code, document it in the manual (even though
    their mother tongue is not English), test it, develop and commit
    regression scripts, and answer in a timely fashion all bug reports --
-   even occassionally accepting additional bugs :-)
+   even occasionally accepting additional bugs :-)
 
    This is a sustainable way of going forward with Bacula, and the
    direction that the project will be taking more and more.  For
    example, in the past, we have had some very dedicated programmers
-   who did major projects. However, these
+   who did major projects. However, some of these
    programmers due to outside obligations (job responsibilities change of
    job, school duties, ...) could not continue to maintain the code.  In
-   those cases, the code suffers from lack of maintenance, sometimes I
-   patch it, sometimes not.  In the end, the code gets dropped from the
-   project (there are two such contributions that are heading in that
-   direction).  When ever possible, we would like to avoid this, and 
-   ensure a continuation of the code and a sharing of the development,
-   debugging, documentation, and maintenance responsibilities.
+   those cases, the code suffers from lack of maintenance, sometimes we
+   patch it, sometimes not.  In the end, if the code is not maintained, the
+   code gets dropped from the project (there are two such contributions
+   that are heading in that direction).  When ever possible, we would like
+   to avoid this, and ensure a continuation of the code and a sharing of
+   the development, debugging, documentation, and maintenance
+   responsibilities.
 \end{itemize}
 
 \section{Patches for Released Versions}
@@ -340,7 +359,7 @@ follows:
   (input description)
   (end edit)
 
-   svn diff >>2.2.4-restore.patch
+   git diff >>2.2.4-restore.patch
 \end{verbatim}
 
 check to make sure no extra junk got put into the patch file (i.e.
@@ -349,7 +368,7 @@ it should have the patch for that bug only).
 If there is not a bug report on the problem, create one, then add the
 patch to the bug report. 
 
-Uthen upload it to the 2.2.x release of bacula-patches.
+Then upload it to the 2.2.x release of bacula-patches.
 
 So, end the end, the patch file is:
 \begin{itemize}
@@ -365,17 +384,241 @@ So, end the end, the patch file is:
 \end{itemize}
 
 
+\section{Bacula GIT and SVN repositories}
+\index{GIT and SVN}
+\addcontentsline{toc}{subsection}{GIT and SVN repositories}
+As of August 2009, the Bacula source code has been split into
+two repositories.  One is a GIT repository that holds the
+main Bacula source code with directories {\bf bacula}, {\bf gui},
+and {\bf regress}.  The second repository (SVN) contains
+the directories {\bf rescue} and {\bf docs}. Both repositories are 
+hosted on Source Forge.
+
+Previously everything was in a single SVN repository.
+We have split the SVN repository into two because GIT
+offers significant advantages for ease of managing and integrating
+developer's changes.  However, one of the disadvantages of GIT is that you
+must work with the full repository, while SVN allows you to checkout
+individual directories.  If we put everything into a single GIT
+repository it would be far bigger than most developers would want
+to checkout, so we have left the docs and rescue in the old SVN
+repository, and moved only the parts that are most actively 
+worked on by the developers (bacula, gui, and regress) to a GIT
+repository.  
+
+Unfortunately, Bacula developers must now have a certain knowledege
+of both GIT and SVN, and if you are a core Bacula developer knowledge of
+GIT is particularly important.
+
+\section{GIT Usage}
+\index{GIT Usage}
+\addcontentsline{toc}{subsection}{GIT Usage}
+
+Please note that if you are familiar with SVN, GIT is similar,
+(and better), but there can be a few surprising differences that
+can lead to damaging the history of the repository (repo) if
+you attempt to force pushing data into the GIT repo.
+
+The GIT repo contains the subdirectories {\bf bacula}, {\bf gui},
+and {\bf regress}. With GIT it is not possible to pull only a
+single directory, because of the hash code nature of git, you
+must take all or nothing.
+
+For developers, the most important thing to remember about GIT and
+the Source Forge repository is not to "force" a {\bf push} to the
+repository, and not to use the {\bf rebase} command on the {\bf
+master} branch of the repository.  Doing so, will possibly rewrite
+the GIT repository history and cause a lot of problems for the 
+project.
+
+You may and should use {\bf rebase} on your own branches that you
+want to synchronize with the {\bf master} branch, but please
+do not use {\bf rebase} on the {\bf master} branch.  The proper
+way of merging changes will be discussed below.
+
+You can get a full copy of the Source Forge Bacula GIT repository with the
+following command:
+
+\begin{verbatim}
+git clone git://bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
+\end{verbatim}
+
+This will put a read-only copy into the directory {\bf trunk} 
+in your current directory, and {\bf trunk} will contain
+the subdirectories: {\bf bacula}, {\bf gui}, and {\bf regress}.
+
+If you have write permission, you can get a copy of the GIT
+repo with:
+
+\begin{verbatim}
+git clone ssh://<userid>@bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
+\end{verbatim}
+
+where you replace \verb+<userid>+ with your Source Forge login 
+userid, and you must have previously uploaded your public ssh key
+to Source Forge.
+
+The above command needs to be done only once. Thereafter, you can:
+
+\begin{verbatim}
+cd trunk
+git pull origin
+\end{verbatim}
+
+As of August 2009, the size of the repository ({\bf trunk} in the above
+example) will be approximately 55 Megabytes.  However, if you build
+from source in this directory and do a lot of updates and regression
+testing, the directory could become several hundred megabytes.
+
+\subsection{Learning GIT}
+\index{Learning GIT}
+If you want to learn more about GIT, we recommend that you visit:\\
+\elink{http://book.git-scm.com/}{http://book.git-scm.com/}.
+
+
+\subsection{Publishing your changes}
+\index{Publishing}
+Since GIT is more complex than SVN, it takes a bit of time to learn how
+to use it properly, and if you are not careful, you can potentially create
+a new history in the repository. In addition, since GIT is a distributed 
+version control system, we prefer to receive a full branch submission rather
+than simply a patch.  To accomplish this, you must create your changes in
+a branch, then {\bf push} them to some public repository -- it can be your
+own repository that you publish or another.  To simplify this phase for you, we
+have created a publich Bacula GIT repository on {\bf github} where you can
+push your branch containing changes you would like integrated into the Bacula
+source code.
+
+Once you have pushed your branch to {\bf github} or told us where we can pull
+from your public repository, one of the senior Bacula devlopers will fetch your 
+changes, examine them, possibly make comments for changes they would like to
+see, and as the final step, the senior developer will commit it to the
+Bacula Source Forge GIT repository.
+
+\subsection{Github}
+\index{github}
+If you are going to submit before cloning the Bacula Github database, you must create a login on
+the Github website:\\
+\elink{http://github.com/}{http://github.com/}\\
+You must also upload your public ssh key. Please see the instructions
+at the above link.  Then you notify one of the senior Bacula developers,
+who will add your Github user name to the Bacula repository. Finally,
+you clone the Bacula repository with:
+
+\begin{verbatim}
+ git clone git@github.com:<username>/bacula.git <xxx>
+\end{verbatim}
+
+where you replace \verb+<username>+ with the User Name that you created
+when you created your Github login, and you replace \verb+<xxx>+ with the name
+of a directory that you want git to create to hold your local Bacula git
+repository.
+
+Normally, you will work by creating a branch of the master branch of your
+repository, make your modifications, then make sure it is up to date, and finally
+push it to Github. Assuming you call the Bacula repository {\bf bacula}, you might
+use the following commands:
+
+\begin{verbatim}
+cd bacula
+git checkout master
+git pull 
+git branch <your-name>/newbranch
+git checkout <your-name>/newbranch
+(edit, ...)
+git add <file-edited>
+git commit -m "<comment about commit>"
+...
+\end{verbatim}
+
+Note, we request you to create the branch name with your github
+login name. This guarantees that the branch name will be unique and
+easily identified as well.
+
+When you have completed working on your branch, you will do:
+
+\begin{verbatim}
+cd bacula
+git checkout <your-name>/newbranch
+git pull
+git rebase master
+\end{verbatim}
+
+If you have completed your edits before anyone has modified the repository,
+the {\bf git rebase master} will report that there was nothing to do. Otherwise,
+it will merge the changes that were made in the repository before your changes.
+If there are any conflicts, git will tell you. Typically resolving conflicts with
+git is relatively easy.  You simply make a diff:
+
+\begin{verbatim}
+git diff
+\end{verbatim}
+
+Then edit each file that was listed in the {\bf git diff} to remove the
+conflict, which will be indicated by lines of:
+
+\begin{verbatim}
+<<<<<<< HEAD
+text
+>>>>>>>>
+other text
+=====
+\end{verbatim}
+
+where {\bf text} is what is in the Bacula repository, and {\bf other text}
+is what you have changed.
+
+Once you have eliminated the conflict, the {\bf git diff} will show nothing,
+and you must do a:
+
+\begin{verbatim}
+git add <file-with-conflicts-fixed>
+\end{verbatim}
+
+Once you have fixed all the files with conflicts in the above manner, you enter:
+
+\begin{verbatim}
+git rebase --continue
+\end{verbatim}
+
+and your rebase will be complete.
+
+If for some reason, before doing the --continue, you want to abort the rebase and return to what you had, you enter:
+
+\begin{verbatim}
+git rebase --abort
+\end{verbatim}
+
+Finally to upload your branch, you do:
+
+\begin{verbatim}
+git push origin <your-name>/newbranch
+\end{verbatim}
+
+If you wish to delete it later, you can use:
+
+\begin{verbatim}
+git push origin :<your-name>/newbranch
+\end{verbatim}
+
+
 
 \section{SVN Usage}
 \index{SVN Usage}
 \addcontentsline{toc}{subsection}{SVN Usage}
 
-Please note that if you are familar with CVS, SVN is very
+Note: this section is somewhat out of date, since the SVN now
+contains only the docs and rescue subdirectories.  The bacula,
+gui, and regress directories are now maintained in a GIT
+repository.
+
+Please note that if you are familiar with CVS, SVN is very
 similar (and better), but there can be a few surprising
 differences.
 
-The *entire* Bacula  SourceForge.net Subversion repository can be
-checked out through SVN with the following command:
+The Bacula  SourceForge.net Subversion repository that contains
+the documentation and the rescue scripts checked out through SVN with the
+following command:
 
 \begin{verbatim}
 svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula bacula
@@ -438,15 +681,12 @@ periods (e.g. 2.0, 2.0.1, ...).
 
 In addition all tags even those that you create are read-only
 forever. Typically tags represent release points either in the
-trunc or in a branch.
+trunk or in a branch.
 
 
 Coming back to getting source code. 
-If you only want the current Bacula source code, you could use:
-
-\begin{verbatim}
-svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula bacula
-\end{verbatim}
+If you only want the current Bacula source code, you should see
+the above section that describes the GIT repository.
 
 To view what is in the SVN, point your browser at the following URL:
 http://bacula.svn.sourceforge.net/viewvc/bacula/  
@@ -455,8 +695,8 @@ Many of the Subversion (svn) commands are almost identical to those that
 you have used for cvs, but some (such as a checkout) can have surprising
 results, so you should take a careful look at the documentation. 
 
-Robert has kindly provided the following documentation on the new
-svn repository and how to use it:
+The following documentation on the new
+svn repository will help you know how to use it:
 
 Here is the list of branches:
 \begin{verbatim}
@@ -725,34 +965,6 @@ you have little to worry about.
 \index{Subversion (svn) Resources}
 \addcontentsline{toc}{subsection}{Subversion Resources}
 
-\begin{verbatim}
-cvs2svn Statistics:
-------------------
-Total CVS Files:              3286
-Total CVS Revisions:         28924
-Total Unique Tags:              63
-Total Unique Branches:          11
-CVS Repos Size in KB:       232421
-Total SVN Commits:            4116
-First Revision Date:    Tue Apr 23 12:42:57 2002
-Last Revision Date:     Tue Feb  6 06:37:57 2007
-\end{verbatim}
-
-The new Subversion repository size on Robert's machine:
-
-\begin{verbatim}
-4.0K    bacula-tst/dav
-12K     bacula-tst/locks
-40K     bacula-tst/hooks
-16K     bacula-tst/conf
-190M    bacula-tst/db/revs
-17M     bacula-tst/db/revprops
-4.0K    bacula-tst/db/transactions
-206M    bacula-tst/db
-206M    bacula-tst
-\end{verbatim}
-
-
 Main Subversion Web Page
 \elink{http://subversion.tigris.org}{http://subversion.tigris.org}
 
@@ -1022,7 +1234,7 @@ Code should have some documentation -- not a lot, but enough so that I can
 understand it. Look at the current code, and you will see that I document more
 than most, but am definitely not a fanatic. 
 
-I prefer simple linear code where possible. Gotos are strongly discouraged
+We prefer simple linear code where possible. Gotos are strongly discouraged
 except for handling an error to either bail out or to retry some code, and
 such use of gotos can vastly simplify the program. 
 
@@ -1100,8 +1312,8 @@ so be conservative in your use of C++ features.
 \index{Indenting Standards}
 \addcontentsline{toc}{subsubsection}{Indenting Standards}
 
-I cannot stand code indented 8 columns at a time. This makes the code
-unreadable. Even 4 at a time uses a lot of space, so I have adopted indenting
+We find it very hard to read code indented 8 columns at a time. 
+Even 4 at a time uses a lot of space, so we have adopted indenting
 3 spaces at every level. Note, indention is the visual appearance of the
 source on the page, while tabbing is replacing a series of up to 8 spaces from
 a tab character. 
@@ -1133,8 +1345,7 @@ avoid generating too many lines, the first brace appears on the first line
 \end{verbatim}
 \normalsize
 
-Just follow the convention in the code. Originally I indented case clauses
-under a switch(), but now I prefer non-indented cases. 
+Just follow the convention in the code. For example we I prefer non-indented cases. 
 
 \footnotesize
 \begin{verbatim}
@@ -1270,6 +1481,11 @@ edit\_uint64()}. For example:
 \end{verbatim}
 \normalsize
 
+Note: {\bf \%lld} is now permitted in Bacula code -- we have our
+own printf routines which handle it correctly. The edit\_uint64() subroutine
+can still be used if you wish, but over time, most of that old style will
+be removed.
+
 The edit buffer {\bf ed1} must be at least 27 bytes long to avoid overflow.
 See src/lib/edit.c for more details. If you look at the code, don't start
 screaming that I use {\bf lld}. I actually use subtle trick taught to me by
@@ -1401,3 +1617,56 @@ they are used in low level routines such as the low level device file dev.c in
 the Storage daemon or in the low level Catalog routines. These routines do not
 generally have access to the Job Control Record and so they return error
 essages reformatted in a memory buffer. Mmsg() is the way to do this. 
+
+\subsection{Bugs Database}
+\index{Database!Bugs}
+\index{Bugs Database}
+\addcontentsline{toc}{subsubsection}{Bugs Database}
+We have a bugs database which is at:
+\elink{http://bugs.bacula.org}{http://bugs.bacula.org}, and as
+a developer you will need to respond to bugs, perhaps bugs in general 
+if you have time, otherwise just bugs that correspond to code that
+you wrote.
+
+If you need to answer bugs, please be sure to ask the Project Manager
+(currently Kern) to give you Developer access to the bugs database. This
+allows you to modify statuses and close bugs.
+
+The first thing is if you want to take over a bug, rather than just make a
+note, you should assign the bug to yourself. This helps other developers
+know that you are the principal person to deal with the bug.  You can do so
+by going into the bug and clicking on the {\bf Update Issue} button. Then
+you simply go to the {\bf Assigned To} box and select your name from the
+drop down box.  To actually update it you must click on the {\bf Update
+Information} button a bit further down on the screen, but if you have other
+things to do such as add a Note, you might wait before clicking on the {\bf
+Update Information} button.
+
+Generally, we set the {\bf Status} field to either acknowledged, confirmed,
+or feedback when we first start working on the bug.  Feedback is set when
+we expect that the user should give us more information.
+
+Normally, once you are reasonably sure that the bug is fixed, and a patch
+is made and attached to the bug report, and/or in the SVN, you can close
+the bug.  If you want the user to test the patch, then leave the bug open,
+otherwise close it and set {\bf Resolution} to {\bf Fixed}.  We generally
+close bug reports rather quickly, even without confirmation, especially if
+we have run tests and can see that for us the problem is fixed.  However,
+in doing so, it avoids misunderstandings if you leave a note while you are
+closing the bug that says something to the following effect:
+We are closing this bug because ...   If for some reason, it does not fix
+your problem, please feel free to reopen it, or to open a new bug report
+describing the problem".
+
+We do not recommend that you attempt to edit any of the bug notes that have
+been submitted, nor to delete them or make them private.  In fact, if
+someone accidentally makes a bug note private, you should ask the reason
+and if at all possible (with his agreement) make the bug note public.  
+
+If the user has not properly filled in most of the important fields
+(platorm, OS, Product Version, ...) please do not hesitate to politely ask
+him.  Also, if the bug report is a request for a new feature, please
+politely send the user to the Feature Request menu item on www.bacula.org.
+The same applies to a support request (we answer only bugs), you might give
+the user a tip, but please politely refer him to the manual and the
+Getting Support page of www.bacula.org.
index 9407ad1058805396ce3124459c82a234c7c9af34..74a8a2a46f2879d9c99a05409a8c5dddf8900c8b 100644 (file)
@@ -440,7 +440,7 @@ You can get a full copy of the Source Forge Bacula GIT repository with the
 following command:
 
 \begin{verbatim}
-git clone git://bacula.git.sourceforge.net/gitroot/bacula trunk
+git clone git://bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
 \end{verbatim}
 
 This will put a read-only copy into the directory {\bf trunk} 
@@ -451,7 +451,7 @@ If you have write permission, you can get a copy of the GIT
 repo with:
 
 \begin{verbatim}
-git clone ssh://<userid>@bacula.git.sourceforge.net/gitroot/bacula trunk
+git clone ssh://<userid>@bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
 \end{verbatim}
 
 where you replace \verb+<userid>+ with your Source Forge login 
index f6bbdf67a6378689ad59c7e913b5b02fee8c5db1..b45e38c147d988203e8d2cef7108ef90efa36811 100644 (file)
@@ -1 +1 @@
-3.0.3 (30 July 2009)
+3.0.3 (15 August 2009)
index f6bbdf67a6378689ad59c7e913b5b02fee8c5db1..b45e38c147d988203e8d2cef7108ef90efa36811 100644 (file)
@@ -1 +1 @@
-3.0.3 (30 July 2009)
+3.0.3 (15 August 2009)
index f6bbdf67a6378689ad59c7e913b5b02fee8c5db1..b45e38c147d988203e8d2cef7108ef90efa36811 100644 (file)
@@ -1 +1 @@
-3.0.3 (30 July 2009)
+3.0.3 (15 August 2009)
index 098ec143c67817dc596df6bd58d2817bd241a41b..74a8a2a46f2879d9c99a05409a8c5dddf8900c8b 100644 (file)
@@ -8,22 +8,22 @@
 \addcontentsline{toc}{section}{Bacula Developer Notes}
 
 This document is intended mostly for developers and describes how you can
-contribute to the Bacula project and the the general
-framework of making Bacula source changes. 
+contribute to the Bacula project and the the general framework of making
+Bacula source changes.
 
 \subsection{Contributions}
 \index{Contributions}
 \addcontentsline{toc}{subsubsection}{Contributions}
 
 Contributions to the Bacula project come in many forms: ideas,
-participation in helping people on the bacula-users email list, 
-packaging Bacula binaries for the community, helping improve
-the documentation, and submitting code.
+participation in helping people on the bacula-users email list, packaging
+Bacula binaries for the community, helping improve the documentation, and
+submitting code.
 
 Contributions in the form of submissions for inclusion in the project are
 broken into two groups.  The first are contributions that are aids and not
-essential to Bacula.  In general, these will be scripts or will go into and
-examples or contributions directory.  For these kinds of non-essential
+essential to Bacula.  In general, these will be scripts or will go into the
+{\bf bacula/examples} directory.  For these kinds of non-essential
 contributions there is no obligation to do a copyright assignment as
 described below.  However, a copyright assignment would still be
 appreciated.
@@ -40,10 +40,18 @@ The following text describes some of the requirements for such code.
 
 Subject to the copyright assignment described below, your patches should be
 sent in {\bf diff -u} format relative to the current contents of the Source
-Forge SVN.  The diff -u format is the easiest for us to understand and integrate.
-Please be sure to use the Bacula indenting standard (see below) for source code.
-If you have checked out the source with SVN, you can get a diff using:
+Forge GIT repository or SVN repository.  The diff -u format is the easiest
+for us to understand and integrate.  Please be sure to use the Bacula
+indenting standard (see below) for source code.  If you have checked out
+the source with GIT or SVN, you can get a diff using.
 
+For the bacula, gui, and regress directories:
+\begin{verbatim}
+git pull
+git diff >change.patch
+\end{verbatim}
+
+For the docs or rescue directories:
 \begin{verbatim}
 svn update 
 svn diff > change.patch
@@ -51,8 +59,8 @@ svn diff > change.patch
      
 If you plan on doing significant development work over a period of time,
 after having your first patch reviewed and approved, you will be eligible
-for having developer SVN write access so that you can commit your changes
-directly to the SVN repository.  To do so, you will need a userid on Source
+for having developer GIT or SVN write access so that you can commit your changes
+directly to the GIT or SVN repository.  To do so, you will need a userid on Source
 Forge.
 
 \subsection{Copyrights}
@@ -63,22 +71,23 @@ To avoid future problems concerning changing licensing or
 copyrights, all code contributions more than a hand full of lines
 must be in the Public Domain or have the copyright transferred to
 the Free Software Foundation Europe e.V. with a Fiduciary License
-Agreement (FLA) as in the current code.  Note, prior to
-November 2004, the code was copyrighted by Kern Sibbald and John
-Walker.  After November 2004, the code was copyrighted by Kern
-Sibbald, then on the 15th of November 2006, the copyright was
-transferred to the Free Software Foundation Europe e.V.
-In signing the FLA and transferring the copyright, you retain the
-right to use the code you have submitted as you want.
+Agreement (FLA) as the case for all the current code.  
+
+Prior to November 2004, all the code was copyrighted by Kern Sibbald and
+John Walker.  After November 2004, the code was copyrighted by Kern
+Sibbald, then on the 15th of November 2006, Kern transferred the copyright
+to the Free Software Foundation Europe e.V. In signing the FLA and
+transferring the copyright, you retain the right to use the code you have
+submitted as you want, and you ensure that Bacula will always remain Free
+and Open Source.
 
 Your name should be clearly indicated as the author of the code, and you
-must be extremely careful not to violate any copyrights or patents or use other
-people's code without acknowledging it.  The purpose of this requirement is
-to avoid future copyright, patent, or intellectual property problems.  
-Please read the LICENSE agreement in the main Bacula source code
-directory.  When you sign the Fiduciary License Agreement (FLA)
-and send it in, you are argeeing to the terms of that LICENSE
-file.
+must be extremely careful not to violate any copyrights or patents or use
+other people's code without acknowledging it.  The purpose of this
+requirement is to avoid future copyright, patent, or intellectual property
+problems.  Please read the LICENSE agreement in the main Bacula source code
+directory.  When you sign the Fiduciary License Agreement (FLA) and send it
+in, you are agreeing to the terms of that LICENSE file.
 
 If you don't understand what we mean by future problems, please
 examine the difficulties Mozilla was having finding
@@ -96,7 +105,7 @@ unusual, but in reality, it is not.  Most large projects require
 this.
 
 If you have any doubts about this, please don't hesitate to ask.  The
-objective is to assure the long term servival of the Bacula project. 
+objective is to assure the long term survival of the Bacula project. 
 
 Items not needing a copyright assignment are: most small changes,
 enhancements, or bug fixes of 5-10 lines of code, which amount to    
@@ -155,17 +164,20 @@ to confirm reception of the signed FLA.
 \index{Cycle!Developement}
 \addcontentsline{toc}{subsubsection}{Development Cycle}
 
-As I noted in the 1.38 ReleaseNotes, version 1.38 was different from prior
-versions because it had a lot more contributions.  We expect that this trend
+As I noted in previous emails the number of contributions are
+increasing significantly.  We expect this positive trend
 will continue.  As a consequence, we have modified how we do
 development, and instead of making a list of all the features that we will
-implement in the next version, each developer will sign up for one (maybe
-two) projects at a time, and when they are complete, we will release a new
-version.
+implement in the next version, each developer signs up for one (maybe
+two) projects at a time, and when they are complete, and the code
+is stable, we will release a new version.  The release cycle will probably
+be roughly six months.
 
-The difference is that we will have more time to review the new code that is
-being contributed, and will be able to devote more time to a smaller number
-of projects (1.38 had too many new features for us to handle correctly).
+The difference is that with a shorter release cycle and fewer released
+feature, we will have more time to review the new code that is being
+contributed, and will be able to devote more time to a smaller number of
+projects (some prior versions had too many new features for us to handle
+correctly).
 
 Future release schedules will be much the same, and the
 number of new features will also be much the same providing that the
@@ -173,26 +185,27 @@ contributions continue to come -- and they show no signs of let up :-)
 
 \index{Feature Requests}
 {\bf Feature Requests:} \\
-In addition, we would like to "formalize" the feature requests a bit.
+In addition, we have "formalizee" the feature requests a bit.
 
 Instead of me maintaining an informal list of everything I run into 
-(kernstodo), we would like to maintain a "formal" list of projects.  This 
+(kernstodo), we now maintain a "formal" list of projects.  This 
 means that all new feature requests, including those recently discussed on 
 the email lists, must be formally submitted and approved. 
 
 Formal submission of feature requests will take two forms: \\
 1. non-mandatory, but highly recommended is to discuss proposed new features
 on the mailing list.\\
-2.  Formal submission of an Feature Request in a special format.
-We'll give an example of this below, but you can also find it on the web
-site under "Support -\gt{} Feature Requests".  Since it takes a bit of time to
-properly fill out a Feature Request form, you probably should check on the email list
-first.
+2.  Formal submission of an Feature Request in a special format.  We'll
+give an example of this below, but you can also find it on the web site
+under "Support -\gt{} Feature Requests".  Since it takes a bit of time to
+properly fill out a Feature Request form, you probably should check on the
+email list first.
 
 Once the Feature Request is received by the keeper of the projects list, it
 will be sent to the Bacula project manager (Kern), and he will either
-accept it, send it back asking for clarification, send it to the email list
-asking for opinions, or reject it.
+accept it (90% of the time), send it back asking for clarification (10% of
+the time), send it to the email list asking for opinions, or reject it
+(very few cases).
 
 If it is accepted, it will go in the "projects" file (a simple ASCII file) 
 maintained in the main Bacula source directory.
@@ -210,9 +223,9 @@ accepted.  \\
 difficult that we cannot imagine finding someone to implement probably won't
 be accepted. Obviously if you know how to implement it, don't hesitate
 to put it in your Feature Request  \\
- 3.  whether or not the Feature Request fits within the
-current stategy of Bacula (for example an Feature Request that requests changing the
-tape to tar format probably would not be accepted, ...).
+ 3.  whether or not the Feature Request fits within the current strategy of
+Bacula (for example an Feature Request that requests changing the tape to
+tar format probably would not be accepted, ...).
 
 {\bf How Feature Requests are prioritized:}\\
 Once an Feature Request is accepted, it needs to be implemented.  If you
@@ -289,7 +302,8 @@ Getting code implemented in Bacula works roughly as follows:
 
 \item Kern is the project manager, but prefers not to be a "gate keeper".
       This means that the developers are expected to be self-motivated,
-      and once they have experience submit directly to the SVN.  However,
+      and once they have experience submit directly to the GIT or SVN
+      repositories. However,
       it is a good idea to have your patches reviewed prior to submitting,
       and it is a bad idea to submit monster patches because no one will
       be able to properly review them. See below for more details on this.
@@ -306,7 +320,7 @@ Getting code implemented in Bacula works roughly as follows:
    document it in the code, document it in the manual (even though
    their mother tongue is not English), test it, develop and commit
    regression scripts, and answer in a timely fashion all bug reports --
-   even occassionally accepting additional bugs :-)
+   even occasionally accepting additional bugs :-)
 
    This is a sustainable way of going forward with Bacula, and the
    direction that the project will be taking more and more.  For
@@ -315,11 +329,12 @@ Getting code implemented in Bacula works roughly as follows:
    programmers due to outside obligations (job responsibilities change of
    job, school duties, ...) could not continue to maintain the code.  In
    those cases, the code suffers from lack of maintenance, sometimes we
-   patch it, sometimes not.  In the end, the code gets dropped from the
-   project (there are two such contributions that are heading in that
-   direction).  When ever possible, we would like to avoid this, and 
-   ensure a continuation of the code and a sharing of the development,
-   debugging, documentation, and maintenance responsibilities.
+   patch it, sometimes not.  In the end, if the code is not maintained, the
+   code gets dropped from the project (there are two such contributions
+   that are heading in that direction).  When ever possible, we would like
+   to avoid this, and ensure a continuation of the code and a sharing of
+   the development, debugging, documentation, and maintenance
+   responsibilities.
 \end{itemize}
 
 \section{Patches for Released Versions}
@@ -344,7 +359,7 @@ follows:
   (input description)
   (end edit)
 
-   svn diff >>2.2.4-restore.patch
+   git diff >>2.2.4-restore.patch
 \end{verbatim}
 
 check to make sure no extra junk got put into the patch file (i.e.
@@ -353,7 +368,7 @@ it should have the patch for that bug only).
 If there is not a bug report on the problem, create one, then add the
 patch to the bug report. 
 
-Uthen upload it to the 2.2.x release of bacula-patches.
+Then upload it to the 2.2.x release of bacula-patches.
 
 So, end the end, the patch file is:
 \begin{itemize}
@@ -369,17 +384,241 @@ So, end the end, the patch file is:
 \end{itemize}
 
 
+\section{Bacula GIT and SVN repositories}
+\index{GIT and SVN}
+\addcontentsline{toc}{subsection}{GIT and SVN repositories}
+As of August 2009, the Bacula source code has been split into
+two repositories.  One is a GIT repository that holds the
+main Bacula source code with directories {\bf bacula}, {\bf gui},
+and {\bf regress}.  The second repository (SVN) contains
+the directories {\bf rescue} and {\bf docs}. Both repositories are 
+hosted on Source Forge.
+
+Previously everything was in a single SVN repository.
+We have split the SVN repository into two because GIT
+offers significant advantages for ease of managing and integrating
+developer's changes.  However, one of the disadvantages of GIT is that you
+must work with the full repository, while SVN allows you to checkout
+individual directories.  If we put everything into a single GIT
+repository it would be far bigger than most developers would want
+to checkout, so we have left the docs and rescue in the old SVN
+repository, and moved only the parts that are most actively 
+worked on by the developers (bacula, gui, and regress) to a GIT
+repository.  
+
+Unfortunately, Bacula developers must now have a certain knowledege
+of both GIT and SVN, and if you are a core Bacula developer knowledge of
+GIT is particularly important.
+
+\section{GIT Usage}
+\index{GIT Usage}
+\addcontentsline{toc}{subsection}{GIT Usage}
+
+Please note that if you are familiar with SVN, GIT is similar,
+(and better), but there can be a few surprising differences that
+can lead to damaging the history of the repository (repo) if
+you attempt to force pushing data into the GIT repo.
+
+The GIT repo contains the subdirectories {\bf bacula}, {\bf gui},
+and {\bf regress}. With GIT it is not possible to pull only a
+single directory, because of the hash code nature of git, you
+must take all or nothing.
+
+For developers, the most important thing to remember about GIT and
+the Source Forge repository is not to "force" a {\bf push} to the
+repository, and not to use the {\bf rebase} command on the {\bf
+master} branch of the repository.  Doing so, will possibly rewrite
+the GIT repository history and cause a lot of problems for the 
+project.
+
+You may and should use {\bf rebase} on your own branches that you
+want to synchronize with the {\bf master} branch, but please
+do not use {\bf rebase} on the {\bf master} branch.  The proper
+way of merging changes will be discussed below.
+
+You can get a full copy of the Source Forge Bacula GIT repository with the
+following command:
+
+\begin{verbatim}
+git clone git://bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
+\end{verbatim}
+
+This will put a read-only copy into the directory {\bf trunk} 
+in your current directory, and {\bf trunk} will contain
+the subdirectories: {\bf bacula}, {\bf gui}, and {\bf regress}.
+
+If you have write permission, you can get a copy of the GIT
+repo with:
+
+\begin{verbatim}
+git clone ssh://<userid>@bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
+\end{verbatim}
+
+where you replace \verb+<userid>+ with your Source Forge login 
+userid, and you must have previously uploaded your public ssh key
+to Source Forge.
+
+The above command needs to be done only once. Thereafter, you can:
+
+\begin{verbatim}
+cd trunk
+git pull origin
+\end{verbatim}
+
+As of August 2009, the size of the repository ({\bf trunk} in the above
+example) will be approximately 55 Megabytes.  However, if you build
+from source in this directory and do a lot of updates and regression
+testing, the directory could become several hundred megabytes.
+
+\subsection{Learning GIT}
+\index{Learning GIT}
+If you want to learn more about GIT, we recommend that you visit:\\
+\elink{http://book.git-scm.com/}{http://book.git-scm.com/}.
+
+
+\subsection{Publishing your changes}
+\index{Publishing}
+Since GIT is more complex than SVN, it takes a bit of time to learn how
+to use it properly, and if you are not careful, you can potentially create
+a new history in the repository. In addition, since GIT is a distributed 
+version control system, we prefer to receive a full branch submission rather
+than simply a patch.  To accomplish this, you must create your changes in
+a branch, then {\bf push} them to some public repository -- it can be your
+own repository that you publish or another.  To simplify this phase for you, we
+have created a publich Bacula GIT repository on {\bf github} where you can
+push your branch containing changes you would like integrated into the Bacula
+source code.
+
+Once you have pushed your branch to {\bf github} or told us where we can pull
+from your public repository, one of the senior Bacula devlopers will fetch your 
+changes, examine them, possibly make comments for changes they would like to
+see, and as the final step, the senior developer will commit it to the
+Bacula Source Forge GIT repository.
+
+\subsection{Github}
+\index{github}
+If you are going to submit before cloning the Bacula Github database, you must create a login on
+the Github website:\\
+\elink{http://github.com/}{http://github.com/}\\
+You must also upload your public ssh key. Please see the instructions
+at the above link.  Then you notify one of the senior Bacula developers,
+who will add your Github user name to the Bacula repository. Finally,
+you clone the Bacula repository with:
+
+\begin{verbatim}
+ git clone git@github.com:<username>/bacula.git <xxx>
+\end{verbatim}
+
+where you replace \verb+<username>+ with the User Name that you created
+when you created your Github login, and you replace \verb+<xxx>+ with the name
+of a directory that you want git to create to hold your local Bacula git
+repository.
+
+Normally, you will work by creating a branch of the master branch of your
+repository, make your modifications, then make sure it is up to date, and finally
+push it to Github. Assuming you call the Bacula repository {\bf bacula}, you might
+use the following commands:
+
+\begin{verbatim}
+cd bacula
+git checkout master
+git pull 
+git branch <your-name>/newbranch
+git checkout <your-name>/newbranch
+(edit, ...)
+git add <file-edited>
+git commit -m "<comment about commit>"
+...
+\end{verbatim}
+
+Note, we request you to create the branch name with your github
+login name. This guarantees that the branch name will be unique and
+easily identified as well.
+
+When you have completed working on your branch, you will do:
+
+\begin{verbatim}
+cd bacula
+git checkout <your-name>/newbranch
+git pull
+git rebase master
+\end{verbatim}
+
+If you have completed your edits before anyone has modified the repository,
+the {\bf git rebase master} will report that there was nothing to do. Otherwise,
+it will merge the changes that were made in the repository before your changes.
+If there are any conflicts, git will tell you. Typically resolving conflicts with
+git is relatively easy.  You simply make a diff:
+
+\begin{verbatim}
+git diff
+\end{verbatim}
+
+Then edit each file that was listed in the {\bf git diff} to remove the
+conflict, which will be indicated by lines of:
+
+\begin{verbatim}
+<<<<<<< HEAD
+text
+>>>>>>>>
+other text
+=====
+\end{verbatim}
+
+where {\bf text} is what is in the Bacula repository, and {\bf other text}
+is what you have changed.
+
+Once you have eliminated the conflict, the {\bf git diff} will show nothing,
+and you must do a:
+
+\begin{verbatim}
+git add <file-with-conflicts-fixed>
+\end{verbatim}
+
+Once you have fixed all the files with conflicts in the above manner, you enter:
+
+\begin{verbatim}
+git rebase --continue
+\end{verbatim}
+
+and your rebase will be complete.
+
+If for some reason, before doing the --continue, you want to abort the rebase and return to what you had, you enter:
+
+\begin{verbatim}
+git rebase --abort
+\end{verbatim}
+
+Finally to upload your branch, you do:
+
+\begin{verbatim}
+git push origin <your-name>/newbranch
+\end{verbatim}
+
+If you wish to delete it later, you can use:
+
+\begin{verbatim}
+git push origin :<your-name>/newbranch
+\end{verbatim}
+
+
 
 \section{SVN Usage}
 \index{SVN Usage}
 \addcontentsline{toc}{subsection}{SVN Usage}
 
-Please note that if you are familar with CVS, SVN is very
+Note: this section is somewhat out of date, since the SVN now
+contains only the docs and rescue subdirectories.  The bacula,
+gui, and regress directories are now maintained in a GIT
+repository.
+
+Please note that if you are familiar with CVS, SVN is very
 similar (and better), but there can be a few surprising
 differences.
 
-The *entire* Bacula  SourceForge.net Subversion repository can be
-checked out through SVN with the following command:
+The Bacula  SourceForge.net Subversion repository that contains
+the documentation and the rescue scripts checked out through SVN with the
+following command:
 
 \begin{verbatim}
 svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula bacula
@@ -442,15 +681,12 @@ periods (e.g. 2.0, 2.0.1, ...).
 
 In addition all tags even those that you create are read-only
 forever. Typically tags represent release points either in the
-trunc or in a branch.
+trunk or in a branch.
 
 
 Coming back to getting source code. 
-If you only want the current Bacula source code, you could use:
-
-\begin{verbatim}
-svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula bacula
-\end{verbatim}
+If you only want the current Bacula source code, you should see
+the above section that describes the GIT repository.
 
 To view what is in the SVN, point your browser at the following URL:
 http://bacula.svn.sourceforge.net/viewvc/bacula/  
@@ -1434,5 +1670,3 @@ politely send the user to the Feature Request menu item on www.bacula.org.
 The same applies to a support request (we answer only bugs), you might give
 the user a tip, but please politely refer him to the manual and the
 Getting Support page of www.bacula.org.
-
-
index f6bbdf67a6378689ad59c7e913b5b02fee8c5db1..b45e38c147d988203e8d2cef7108ef90efa36811 100644 (file)
@@ -1 +1 @@
-3.0.3 (30 July 2009)
+3.0.3 (15 August 2009)
index f6bbdf67a6378689ad59c7e913b5b02fee8c5db1..b45e38c147d988203e8d2cef7108ef90efa36811 100644 (file)
@@ -1 +1 @@
-3.0.3 (30 July 2009)
+3.0.3 (15 August 2009)
index f6bbdf67a6378689ad59c7e913b5b02fee8c5db1..b45e38c147d988203e8d2cef7108ef90efa36811 100644 (file)
@@ -1 +1 @@
-3.0.3 (30 July 2009)
+3.0.3 (15 August 2009)
index f6bbdf67a6378689ad59c7e913b5b02fee8c5db1..b45e38c147d988203e8d2cef7108ef90efa36811 100644 (file)
@@ -1 +1 @@
-3.0.3 (30 July 2009)
+3.0.3 (15 August 2009)
index 7c153da2b91a1b3504288f7d949415cec67cb189..74a8a2a46f2879d9c99a05409a8c5dddf8900c8b 100644 (file)
@@ -7,29 +7,32 @@
 \index{Notes!Bacula Developer}
 \addcontentsline{toc}{section}{Bacula Developer Notes}
 
-\section{General}
-\index{General}
-\addcontentsline{toc}{subsection}{General}
-
-This document is intended mostly for developers and describes the the general
-framework of making Bacula source changes. 
+This document is intended mostly for developers and describes how you can
+contribute to the Bacula project and the the general framework of making
+Bacula source changes.
 
 \subsection{Contributions}
 \index{Contributions}
 \addcontentsline{toc}{subsubsection}{Contributions}
 
-Contributions from programmers are broken into two groups. The first are
-contributions that are aids and not essential to Bacula. In general, these
-will be scripts or will go into and examples or contributions directory. 
-For these kinds of non-essential contributions there is no obligation to do
-a copyright assignment as described below. However, a copyright assignment
-would still be appreciated.
+Contributions to the Bacula project come in many forms: ideas,
+participation in helping people on the bacula-users email list, packaging
+Bacula binaries for the community, helping improve the documentation, and
+submitting code.
+
+Contributions in the form of submissions for inclusion in the project are
+broken into two groups.  The first are contributions that are aids and not
+essential to Bacula.  In general, these will be scripts or will go into the
+{\bf bacula/examples} directory.  For these kinds of non-essential
+contributions there is no obligation to do a copyright assignment as
+described below.  However, a copyright assignment would still be
+appreciated.
 
 The second class of contributions are those which will be integrated with
-Bacula and become an essential part. Within this class of contributions, there
-are two hurdles to surmount. One is getting your patch accepted, and two is
-dealing with copyright issues. The following text describes some of the
-requirements for such code. 
+Bacula and become an essential part (code, scripts, documentation, ...)
+Within this class of contributions, there are two hurdles to surmount.  One
+is getting your patch accepted, and two is dealing with copyright issues.
+The following text describes some of the requirements for such code.
 
 \subsection{Patches}
 \index{Patches}
@@ -37,10 +40,18 @@ requirements for such code.
 
 Subject to the copyright assignment described below, your patches should be
 sent in {\bf diff -u} format relative to the current contents of the Source
-Forge SVN, which is the easiest to understand and integrate.
-Please be sure to use the Bacula indenting standard (see below).
-If you have checked out the source with SVN, you can get a diff using:
+Forge GIT repository or SVN repository.  The diff -u format is the easiest
+for us to understand and integrate.  Please be sure to use the Bacula
+indenting standard (see below) for source code.  If you have checked out
+the source with GIT or SVN, you can get a diff using.
+
+For the bacula, gui, and regress directories:
+\begin{verbatim}
+git pull
+git diff >change.patch
+\end{verbatim}
 
+For the docs or rescue directories:
 \begin{verbatim}
 svn update 
 svn diff > change.patch
@@ -48,8 +59,8 @@ svn diff > change.patch
      
 If you plan on doing significant development work over a period of time,
 after having your first patch reviewed and approved, you will be eligible
-for having developer SVN access so that you can commit your changes
-directly to the SVN repository.  To do so, you will need a userid on Source
+for having developer GIT or SVN write access so that you can commit your changes
+directly to the GIT or SVN repository.  To do so, you will need a userid on Source
 Forge.
 
 \subsection{Copyrights}
@@ -60,28 +71,31 @@ To avoid future problems concerning changing licensing or
 copyrights, all code contributions more than a hand full of lines
 must be in the Public Domain or have the copyright transferred to
 the Free Software Foundation Europe e.V. with a Fiduciary License
-Agreement (FLA) as in the current code.  Note, prior to
-November 2004, the code was copyrighted by Kern Sibbald and John
-Walker.  After November 2004, the code was copyrighted by Kern
-Sibbald, then on the 15th of November 2006, the copyright was
-transferred to the Free Software Foundation Europe e.V.
+Agreement (FLA) as the case for all the current code.  
+
+Prior to November 2004, all the code was copyrighted by Kern Sibbald and
+John Walker.  After November 2004, the code was copyrighted by Kern
+Sibbald, then on the 15th of November 2006, Kern transferred the copyright
+to the Free Software Foundation Europe e.V. In signing the FLA and
+transferring the copyright, you retain the right to use the code you have
+submitted as you want, and you ensure that Bacula will always remain Free
+and Open Source.
 
 Your name should be clearly indicated as the author of the code, and you
-must be extremely careful not to violate any copyrights or use other
-people's code without acknowledging it.  The purpose of this requirement is
-to avoid future copyright, patent, or intellectual property problems.  
-Please read the LICENSE agreement in the main source code
-directory.  When you sign the Fiduciary License Agreement (FLA)
-and send it in, you are argeeing to the terms of that LICENSE
-file.
-
-To understand the possible source of future problems, please
-examine the difficulties Mozilla is (was?) having finding
+must be extremely careful not to violate any copyrights or patents or use
+other people's code without acknowledging it.  The purpose of this
+requirement is to avoid future copyright, patent, or intellectual property
+problems.  Please read the LICENSE agreement in the main Bacula source code
+directory.  When you sign the Fiduciary License Agreement (FLA) and send it
+in, you are agreeing to the terms of that LICENSE file.
+
+If you don't understand what we mean by future problems, please
+examine the difficulties Mozilla was having finding
 previous contributors at \elink{
 http://www.mozilla.org/MPL/missing.html}
 {http://www.mozilla.org/MPL/missing.html}. The other important issue is to
-avoid copyright, patent, or intellectual property violations as are currently
-(May 2003) being claimed by SCO against IBM. 
+avoid copyright, patent, or intellectual property violations as was
+(May 2003) claimed by SCO against IBM. 
 
 Although the copyright will be held by the Free Software
 Foundation Europe e.V., each developer is expected to indicate
@@ -91,7 +105,7 @@ unusual, but in reality, it is not.  Most large projects require
 this.
 
 If you have any doubts about this, please don't hesitate to ask.  The
-objective is to assure the long term servival of the Bacula project. 
+objective is to assure the long term survival of the Bacula project. 
 
 Items not needing a copyright assignment are: most small changes,
 enhancements, or bug fixes of 5-10 lines of code, which amount to    
@@ -108,24 +122,23 @@ explicitly acknowledging that they do so in their first submission.  This
 was sufficient if the developer is independent, or an employee of a
 not-for-profit organization or a university.  However, in an effort to
 ensure that the Bacula code is really clean, beginning in August 2006, all
-previous and future developers with SVN access will be asked to submit a
+previous and future developers with SVN write access will be asked to submit a
 copyright assignment (or Fiduciary License Agreement -- FLA),
 which means you agree to the LICENSE in the main source
 directory. It also means that you receive back the right to use
 the code that you have submitted.
 
 Any developer who wants to contribute and is employed by a company should
-either list the employer as the owner of the code, or get
-explicit permission from him to sign the copyright assignment.
-This is because in many
-countries, all work that an employee does whether on company time or in the
-employee's free time is considered to be Intellectual Property of the
-company.  Obtaining official approval or an FLA from the company will avoid
-misunderstandings between the employee, the company, and the Bacula
+either list the employer as the owner of the code, or get explicit
+permission from him to sign the copyright assignment.  This is because in
+many countries, all work that an employee does whether on company time or
+in the employee's free time is considered to be Intellectual Property of
+the company.  Obtaining official approval or an FLA from the company will
+avoid misunderstandings between the employee, the company, and the Bacula
 project.  A good number of companies have already followed this procedure.
 
 The Fiduciary License Agreement is posted on the Bacula web site at:
-\elink{http://www.bacula.org/fr/FLA-bacula.en.pdf}{http://www.bacula.org/fr/FLA-bacula.en.pdf}
+\elink{http://www.bacula.org/en/FLA-bacula.en.pdf}{http://www.bacula.org/en/FLA-bacula.en.pdf}
 
 The instructions for filling out this agreement are also at:
 \elink{http://www.bacula.org/?page=fsfe}{http://www.bacula.org/?page=fsfe}
@@ -133,17 +146,17 @@ The instructions for filling out this agreement are also at:
 It should be filled out, then sent to:
 
 \begin{verbatim}
-     Free Software Foundation Europe
-     Freedom Task Force
-     Sumatrastrasse 25
-     8006 Zürich
+     Kern Sibbald
+     Cotes-de-Montmoiret 9
+     1012 Lausanne
      Switzerland
 \end{verbatim}
 
 Please note that the above address is different from the officially
 registered office mentioned in the document.  When you send in such a
-complete document, please notify me: kern at sibbald dot com.
-
+complete document, please notify me: kern at sibbald dot com, and 
+please add your email address to the FLA so that I can contact you
+to confirm reception of the signed FLA.
 
 
 \section{The Development Cycle}
@@ -151,44 +164,48 @@ complete document, please notify me: kern at sibbald dot com.
 \index{Cycle!Developement}
 \addcontentsline{toc}{subsubsection}{Development Cycle}
 
-As I noted in the 1.38 ReleaseNotes, version 1.38 was different from prior
-versions because it had a lot more contributions.  I expect that this trend
-will continue.  As a consequence, I am going to modify how I normally do
-development, and instead of making a list of all the features that I will
-implement in the next version, I will personally sign up for one (maybe
-two) projects at a time, and when they are complete, I will release a new
-version.
-
-The difference is that I will have more time to review the new code that is
-being contributed, and will be able to devote more time to a smaller number
-of projects (1.38 had too many new features for me to handle correctly).
-
-I expect that future release schedules will be much the same, and the
+As I noted in previous emails the number of contributions are
+increasing significantly.  We expect this positive trend
+will continue.  As a consequence, we have modified how we do
+development, and instead of making a list of all the features that we will
+implement in the next version, each developer signs up for one (maybe
+two) projects at a time, and when they are complete, and the code
+is stable, we will release a new version.  The release cycle will probably
+be roughly six months.
+
+The difference is that with a shorter release cycle and fewer released
+feature, we will have more time to review the new code that is being
+contributed, and will be able to devote more time to a smaller number of
+projects (some prior versions had too many new features for us to handle
+correctly).
+
+Future release schedules will be much the same, and the
 number of new features will also be much the same providing that the
 contributions continue to come -- and they show no signs of let up :-)
 
 \index{Feature Requests}
 {\bf Feature Requests:} \\
-In addition, I would like to "formalize" the feature requests a bit.
+In addition, we have "formalizee" the feature requests a bit.
 
 Instead of me maintaining an informal list of everything I run into 
-(kernstodo), I would like to maintain a "formal" list of projects.  This 
+(kernstodo), we now maintain a "formal" list of projects.  This 
 means that all new feature requests, including those recently discussed on 
 the email lists, must be formally submitted and approved. 
 
 Formal submission of feature requests will take two forms: \\
 1. non-mandatory, but highly recommended is to discuss proposed new features
 on the mailing list.\\
-2.  Formal submission of an Feature Request in a special format.
-I'll give an example of this below, but you can also find it on the web
-site under "Support -\gt{} Feature Requests".  Since it takes a bit of time to
-properly fill out a Feature Request form, you probably should check on the email list
-first.
+2.  Formal submission of an Feature Request in a special format.  We'll
+give an example of this below, but you can also find it on the web site
+under "Support -\gt{} Feature Requests".  Since it takes a bit of time to
+properly fill out a Feature Request form, you probably should check on the
+email list first.
 
 Once the Feature Request is received by the keeper of the projects list, it
-will be sent to me, and  I will either accept it, send it back
-asking for clarification, send it to the email list asking for opinions, or
-reject it.
+will be sent to the Bacula project manager (Kern), and he will either
+accept it (90% of the time), send it back asking for clarification (10% of
+the time), send it to the email list asking for opinions, or reject it
+(very few cases).
 
 If it is accepted, it will go in the "projects" file (a simple ASCII file) 
 maintained in the main Bacula source directory.
@@ -203,11 +220,12 @@ Acceptance of Feature Requests depends on several things: \\
 1.  feedback from users.  If it is negative, the Feature Request will probably not be
 accepted.  \\
 2.  the difficulty of the project.  A project that is so
-difficult that I cannot imagine finding someone to implement probably won't
-be accepted. \\
- 3.  whether or not the Feature Request fits within the
-current stategy of Bacula (for example an Feature Request that requests changing the
-tape to tar format would not be accepted, ...)
+difficult that we cannot imagine finding someone to implement probably won't
+be accepted. Obviously if you know how to implement it, don't hesitate
+to put it in your Feature Request  \\
+ 3.  whether or not the Feature Request fits within the current strategy of
+Bacula (for example an Feature Request that requests changing the tape to
+tar format probably would not be accepted, ...).
 
 {\bf How Feature Requests are prioritized:}\\
 Once an Feature Request is accepted, it needs to be implemented.  If you
@@ -219,13 +237,12 @@ for the next version, and by way of this email, we suggest that you send
 discuss and send in your Feature Requests for the next release.  Please
 verify that the Feature Request is not in the current list (attached to this email).
 
-Once users have had several weeks to submit Feature Requests, the keeper of the
-projects list will
-organize them, and request users to vote on them.  This will allow fixing
-prioritizing the Feature Requests.  Having a priority is one thing, but
-getting it implement is another thing -- we are hoping that the Bacula
-community will take more responsibility for assuring the implementation of
-accepted Feature Requests.
+Once users have had several weeks to submit Feature Requests, the keeper of
+the projects list will organize them, and request users to vote on them.
+This will allow fixing prioritizing the Feature Requests.  Having a
+priority is one thing, but getting it implement is another thing -- we are
+hoping that the Bacula community will take more responsibility for assuring
+the implementation of accepted Feature Requests.
 
 Feature Request format:
 \begin{verbatim}
@@ -285,37 +302,39 @@ Getting code implemented in Bacula works roughly as follows:
 
 \item Kern is the project manager, but prefers not to be a "gate keeper".
       This means that the developers are expected to be self-motivated,
-      and once they have experience submit directly to the SVN.  However,
+      and once they have experience submit directly to the GIT or SVN
+      repositories. However,
       it is a good idea to have your patches reviewed prior to submitting,
       and it is a bad idea to submit monster patches because no one will
       be able to properly review them. See below for more details on this.
 
 \item  There are growing numbers of contributions (very good).
 
-\item Some contributions come in  the form of relatively small patches,
+\item Some contributions come in the form of relatively small patches,
      which Kern reviews, integrates, documents, tests, and maintains.
 
 \item All Bacula developers take full
-   responsibility for writing the code, posting as patches so that I can
+   responsibility for writing the code, posting as patches so that we can
    review it as time permits, integrating it at an appropriate time,
-   responding to my requests for tweaking it (name changes, ...),
+   responding to our requests for tweaking it (name changes, ...),
    document it in the code, document it in the manual (even though
    their mother tongue is not English), test it, develop and commit
    regression scripts, and answer in a timely fashion all bug reports --
-   even occassionally accepting additional bugs :-)
+   even occasionally accepting additional bugs :-)
 
    This is a sustainable way of going forward with Bacula, and the
    direction that the project will be taking more and more.  For
    example, in the past, we have had some very dedicated programmers
-   who did major projects. However, these
+   who did major projects. However, some of these
    programmers due to outside obligations (job responsibilities change of
    job, school duties, ...) could not continue to maintain the code.  In
-   those cases, the code suffers from lack of maintenance, sometimes I
-   patch it, sometimes not.  In the end, the code gets dropped from the
-   project (there are two such contributions that are heading in that
-   direction).  When ever possible, we would like to avoid this, and 
-   ensure a continuation of the code and a sharing of the development,
-   debugging, documentation, and maintenance responsibilities.
+   those cases, the code suffers from lack of maintenance, sometimes we
+   patch it, sometimes not.  In the end, if the code is not maintained, the
+   code gets dropped from the project (there are two such contributions
+   that are heading in that direction).  When ever possible, we would like
+   to avoid this, and ensure a continuation of the code and a sharing of
+   the development, debugging, documentation, and maintenance
+   responsibilities.
 \end{itemize}
 
 \section{Patches for Released Versions}
@@ -340,7 +359,7 @@ follows:
   (input description)
   (end edit)
 
-   svn diff >>2.2.4-restore.patch
+   git diff >>2.2.4-restore.patch
 \end{verbatim}
 
 check to make sure no extra junk got put into the patch file (i.e.
@@ -349,7 +368,7 @@ it should have the patch for that bug only).
 If there is not a bug report on the problem, create one, then add the
 patch to the bug report. 
 
-Uthen upload it to the 2.2.x release of bacula-patches.
+Then upload it to the 2.2.x release of bacula-patches.
 
 So, end the end, the patch file is:
 \begin{itemize}
@@ -365,17 +384,241 @@ So, end the end, the patch file is:
 \end{itemize}
 
 
+\section{Bacula GIT and SVN repositories}
+\index{GIT and SVN}
+\addcontentsline{toc}{subsection}{GIT and SVN repositories}
+As of August 2009, the Bacula source code has been split into
+two repositories.  One is a GIT repository that holds the
+main Bacula source code with directories {\bf bacula}, {\bf gui},
+and {\bf regress}.  The second repository (SVN) contains
+the directories {\bf rescue} and {\bf docs}. Both repositories are 
+hosted on Source Forge.
+
+Previously everything was in a single SVN repository.
+We have split the SVN repository into two because GIT
+offers significant advantages for ease of managing and integrating
+developer's changes.  However, one of the disadvantages of GIT is that you
+must work with the full repository, while SVN allows you to checkout
+individual directories.  If we put everything into a single GIT
+repository it would be far bigger than most developers would want
+to checkout, so we have left the docs and rescue in the old SVN
+repository, and moved only the parts that are most actively 
+worked on by the developers (bacula, gui, and regress) to a GIT
+repository.  
+
+Unfortunately, Bacula developers must now have a certain knowledege
+of both GIT and SVN, and if you are a core Bacula developer knowledge of
+GIT is particularly important.
+
+\section{GIT Usage}
+\index{GIT Usage}
+\addcontentsline{toc}{subsection}{GIT Usage}
+
+Please note that if you are familiar with SVN, GIT is similar,
+(and better), but there can be a few surprising differences that
+can lead to damaging the history of the repository (repo) if
+you attempt to force pushing data into the GIT repo.
+
+The GIT repo contains the subdirectories {\bf bacula}, {\bf gui},
+and {\bf regress}. With GIT it is not possible to pull only a
+single directory, because of the hash code nature of git, you
+must take all or nothing.
+
+For developers, the most important thing to remember about GIT and
+the Source Forge repository is not to "force" a {\bf push} to the
+repository, and not to use the {\bf rebase} command on the {\bf
+master} branch of the repository.  Doing so, will possibly rewrite
+the GIT repository history and cause a lot of problems for the 
+project.
+
+You may and should use {\bf rebase} on your own branches that you
+want to synchronize with the {\bf master} branch, but please
+do not use {\bf rebase} on the {\bf master} branch.  The proper
+way of merging changes will be discussed below.
+
+You can get a full copy of the Source Forge Bacula GIT repository with the
+following command:
+
+\begin{verbatim}
+git clone git://bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
+\end{verbatim}
+
+This will put a read-only copy into the directory {\bf trunk} 
+in your current directory, and {\bf trunk} will contain
+the subdirectories: {\bf bacula}, {\bf gui}, and {\bf regress}.
+
+If you have write permission, you can get a copy of the GIT
+repo with:
+
+\begin{verbatim}
+git clone ssh://<userid>@bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
+\end{verbatim}
+
+where you replace \verb+<userid>+ with your Source Forge login 
+userid, and you must have previously uploaded your public ssh key
+to Source Forge.
+
+The above command needs to be done only once. Thereafter, you can:
+
+\begin{verbatim}
+cd trunk
+git pull origin
+\end{verbatim}
+
+As of August 2009, the size of the repository ({\bf trunk} in the above
+example) will be approximately 55 Megabytes.  However, if you build
+from source in this directory and do a lot of updates and regression
+testing, the directory could become several hundred megabytes.
+
+\subsection{Learning GIT}
+\index{Learning GIT}
+If you want to learn more about GIT, we recommend that you visit:\\
+\elink{http://book.git-scm.com/}{http://book.git-scm.com/}.
+
+
+\subsection{Publishing your changes}
+\index{Publishing}
+Since GIT is more complex than SVN, it takes a bit of time to learn how
+to use it properly, and if you are not careful, you can potentially create
+a new history in the repository. In addition, since GIT is a distributed 
+version control system, we prefer to receive a full branch submission rather
+than simply a patch.  To accomplish this, you must create your changes in
+a branch, then {\bf push} them to some public repository -- it can be your
+own repository that you publish or another.  To simplify this phase for you, we
+have created a publich Bacula GIT repository on {\bf github} where you can
+push your branch containing changes you would like integrated into the Bacula
+source code.
+
+Once you have pushed your branch to {\bf github} or told us where we can pull
+from your public repository, one of the senior Bacula devlopers will fetch your 
+changes, examine them, possibly make comments for changes they would like to
+see, and as the final step, the senior developer will commit it to the
+Bacula Source Forge GIT repository.
+
+\subsection{Github}
+\index{github}
+If you are going to submit before cloning the Bacula Github database, you must create a login on
+the Github website:\\
+\elink{http://github.com/}{http://github.com/}\\
+You must also upload your public ssh key. Please see the instructions
+at the above link.  Then you notify one of the senior Bacula developers,
+who will add your Github user name to the Bacula repository. Finally,
+you clone the Bacula repository with:
+
+\begin{verbatim}
+ git clone git@github.com:<username>/bacula.git <xxx>
+\end{verbatim}
+
+where you replace \verb+<username>+ with the User Name that you created
+when you created your Github login, and you replace \verb+<xxx>+ with the name
+of a directory that you want git to create to hold your local Bacula git
+repository.
+
+Normally, you will work by creating a branch of the master branch of your
+repository, make your modifications, then make sure it is up to date, and finally
+push it to Github. Assuming you call the Bacula repository {\bf bacula}, you might
+use the following commands:
+
+\begin{verbatim}
+cd bacula
+git checkout master
+git pull 
+git branch <your-name>/newbranch
+git checkout <your-name>/newbranch
+(edit, ...)
+git add <file-edited>
+git commit -m "<comment about commit>"
+...
+\end{verbatim}
+
+Note, we request you to create the branch name with your github
+login name. This guarantees that the branch name will be unique and
+easily identified as well.
+
+When you have completed working on your branch, you will do:
+
+\begin{verbatim}
+cd bacula
+git checkout <your-name>/newbranch
+git pull
+git rebase master
+\end{verbatim}
+
+If you have completed your edits before anyone has modified the repository,
+the {\bf git rebase master} will report that there was nothing to do. Otherwise,
+it will merge the changes that were made in the repository before your changes.
+If there are any conflicts, git will tell you. Typically resolving conflicts with
+git is relatively easy.  You simply make a diff:
+
+\begin{verbatim}
+git diff
+\end{verbatim}
+
+Then edit each file that was listed in the {\bf git diff} to remove the
+conflict, which will be indicated by lines of:
+
+\begin{verbatim}
+<<<<<<< HEAD
+text
+>>>>>>>>
+other text
+=====
+\end{verbatim}
+
+where {\bf text} is what is in the Bacula repository, and {\bf other text}
+is what you have changed.
+
+Once you have eliminated the conflict, the {\bf git diff} will show nothing,
+and you must do a:
+
+\begin{verbatim}
+git add <file-with-conflicts-fixed>
+\end{verbatim}
+
+Once you have fixed all the files with conflicts in the above manner, you enter:
+
+\begin{verbatim}
+git rebase --continue
+\end{verbatim}
+
+and your rebase will be complete.
+
+If for some reason, before doing the --continue, you want to abort the rebase and return to what you had, you enter:
+
+\begin{verbatim}
+git rebase --abort
+\end{verbatim}
+
+Finally to upload your branch, you do:
+
+\begin{verbatim}
+git push origin <your-name>/newbranch
+\end{verbatim}
+
+If you wish to delete it later, you can use:
+
+\begin{verbatim}
+git push origin :<your-name>/newbranch
+\end{verbatim}
+
+
 
 \section{SVN Usage}
 \index{SVN Usage}
 \addcontentsline{toc}{subsection}{SVN Usage}
 
-Please note that if you are familar with CVS, SVN is very
+Note: this section is somewhat out of date, since the SVN now
+contains only the docs and rescue subdirectories.  The bacula,
+gui, and regress directories are now maintained in a GIT
+repository.
+
+Please note that if you are familiar with CVS, SVN is very
 similar (and better), but there can be a few surprising
 differences.
 
-The *entire* Bacula  SourceForge.net Subversion repository can be
-checked out through SVN with the following command:
+The Bacula  SourceForge.net Subversion repository that contains
+the documentation and the rescue scripts checked out through SVN with the
+following command:
 
 \begin{verbatim}
 svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula bacula
@@ -438,15 +681,12 @@ periods (e.g. 2.0, 2.0.1, ...).
 
 In addition all tags even those that you create are read-only
 forever. Typically tags represent release points either in the
-trunc or in a branch.
+trunk or in a branch.
 
 
 Coming back to getting source code. 
-If you only want the current Bacula source code, you could use:
-
-\begin{verbatim}
-svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula bacula
-\end{verbatim}
+If you only want the current Bacula source code, you should see
+the above section that describes the GIT repository.
 
 To view what is in the SVN, point your browser at the following URL:
 http://bacula.svn.sourceforge.net/viewvc/bacula/  
@@ -455,8 +695,8 @@ Many of the Subversion (svn) commands are almost identical to those that
 you have used for cvs, but some (such as a checkout) can have surprising
 results, so you should take a careful look at the documentation. 
 
-Robert has kindly provided the following documentation on the new
-svn repository and how to use it:
+The following documentation on the new
+svn repository will help you know how to use it:
 
 Here is the list of branches:
 \begin{verbatim}
@@ -725,34 +965,6 @@ you have little to worry about.
 \index{Subversion (svn) Resources}
 \addcontentsline{toc}{subsection}{Subversion Resources}
 
-\begin{verbatim}
-cvs2svn Statistics:
-------------------
-Total CVS Files:              3286
-Total CVS Revisions:         28924
-Total Unique Tags:              63
-Total Unique Branches:          11
-CVS Repos Size in KB:       232421
-Total SVN Commits:            4116
-First Revision Date:    Tue Apr 23 12:42:57 2002
-Last Revision Date:     Tue Feb  6 06:37:57 2007
-\end{verbatim}
-
-The new Subversion repository size on Robert's machine:
-
-\begin{verbatim}
-4.0K    bacula-tst/dav
-12K     bacula-tst/locks
-40K     bacula-tst/hooks
-16K     bacula-tst/conf
-190M    bacula-tst/db/revs
-17M     bacula-tst/db/revprops
-4.0K    bacula-tst/db/transactions
-206M    bacula-tst/db
-206M    bacula-tst
-\end{verbatim}
-
-
 Main Subversion Web Page
 \elink{http://subversion.tigris.org}{http://subversion.tigris.org}
 
@@ -1022,7 +1234,7 @@ Code should have some documentation -- not a lot, but enough so that I can
 understand it. Look at the current code, and you will see that I document more
 than most, but am definitely not a fanatic. 
 
-I prefer simple linear code where possible. Gotos are strongly discouraged
+We prefer simple linear code where possible. Gotos are strongly discouraged
 except for handling an error to either bail out or to retry some code, and
 such use of gotos can vastly simplify the program. 
 
@@ -1100,8 +1312,8 @@ so be conservative in your use of C++ features.
 \index{Indenting Standards}
 \addcontentsline{toc}{subsubsection}{Indenting Standards}
 
-I cannot stand code indented 8 columns at a time. This makes the code
-unreadable. Even 4 at a time uses a lot of space, so I have adopted indenting
+We find it very hard to read code indented 8 columns at a time. 
+Even 4 at a time uses a lot of space, so we have adopted indenting
 3 spaces at every level. Note, indention is the visual appearance of the
 source on the page, while tabbing is replacing a series of up to 8 spaces from
 a tab character. 
@@ -1133,8 +1345,7 @@ avoid generating too many lines, the first brace appears on the first line
 \end{verbatim}
 \normalsize
 
-Just follow the convention in the code. Originally I indented case clauses
-under a switch(), but now I prefer non-indented cases. 
+Just follow the convention in the code. For example we I prefer non-indented cases. 
 
 \footnotesize
 \begin{verbatim}
@@ -1270,6 +1481,11 @@ edit\_uint64()}. For example:
 \end{verbatim}
 \normalsize
 
+Note: {\bf \%lld} is now permitted in Bacula code -- we have our
+own printf routines which handle it correctly. The edit\_uint64() subroutine
+can still be used if you wish, but over time, most of that old style will
+be removed.
+
 The edit buffer {\bf ed1} must be at least 27 bytes long to avoid overflow.
 See src/lib/edit.c for more details. If you look at the code, don't start
 screaming that I use {\bf lld}. I actually use subtle trick taught to me by
@@ -1401,3 +1617,56 @@ they are used in low level routines such as the low level device file dev.c in
 the Storage daemon or in the low level Catalog routines. These routines do not
 generally have access to the Job Control Record and so they return error
 essages reformatted in a memory buffer. Mmsg() is the way to do this. 
+
+\subsection{Bugs Database}
+\index{Database!Bugs}
+\index{Bugs Database}
+\addcontentsline{toc}{subsubsection}{Bugs Database}
+We have a bugs database which is at:
+\elink{http://bugs.bacula.org}{http://bugs.bacula.org}, and as
+a developer you will need to respond to bugs, perhaps bugs in general 
+if you have time, otherwise just bugs that correspond to code that
+you wrote.
+
+If you need to answer bugs, please be sure to ask the Project Manager
+(currently Kern) to give you Developer access to the bugs database. This
+allows you to modify statuses and close bugs.
+
+The first thing is if you want to take over a bug, rather than just make a
+note, you should assign the bug to yourself. This helps other developers
+know that you are the principal person to deal with the bug.  You can do so
+by going into the bug and clicking on the {\bf Update Issue} button. Then
+you simply go to the {\bf Assigned To} box and select your name from the
+drop down box.  To actually update it you must click on the {\bf Update
+Information} button a bit further down on the screen, but if you have other
+things to do such as add a Note, you might wait before clicking on the {\bf
+Update Information} button.
+
+Generally, we set the {\bf Status} field to either acknowledged, confirmed,
+or feedback when we first start working on the bug.  Feedback is set when
+we expect that the user should give us more information.
+
+Normally, once you are reasonably sure that the bug is fixed, and a patch
+is made and attached to the bug report, and/or in the SVN, you can close
+the bug.  If you want the user to test the patch, then leave the bug open,
+otherwise close it and set {\bf Resolution} to {\bf Fixed}.  We generally
+close bug reports rather quickly, even without confirmation, especially if
+we have run tests and can see that for us the problem is fixed.  However,
+in doing so, it avoids misunderstandings if you leave a note while you are
+closing the bug that says something to the following effect:
+We are closing this bug because ...   If for some reason, it does not fix
+your problem, please feel free to reopen it, or to open a new bug report
+describing the problem".
+
+We do not recommend that you attempt to edit any of the bug notes that have
+been submitted, nor to delete them or make them private.  In fact, if
+someone accidentally makes a bug note private, you should ask the reason
+and if at all possible (with his agreement) make the bug note public.  
+
+If the user has not properly filled in most of the important fields
+(platorm, OS, Product Version, ...) please do not hesitate to politely ask
+him.  Also, if the bug report is a request for a new feature, please
+politely send the user to the Feature Request menu item on www.bacula.org.
+The same applies to a support request (we answer only bugs), you might give
+the user a tip, but please politely refer him to the manual and the
+Getting Support page of www.bacula.org.