Menu
▾
▴
[Bacula-commits] SF.net SVN: bacula:[9156] trunk/docs/manuals/en
|
From: <ke...@us...> - 2009-08-09 16:00:11
|
Revision: 9156
http://bacula.svn.sourceforge.net/bacula/?rev=9156&view=rev
Author: kerns
Date: 2009-08-09 16:00:02 +0000 (Sun, 09 Aug 2009)
Log Message:
-----------
Update
Modified Paths:
--------------
trunk/docs/manuals/en/developers/developers.kilepr
trunk/docs/manuals/en/developers/generaldevel.tex
trunk/docs/manuals/en/developers/regression.tex
trunk/docs/manuals/en/install/dirdconf.tex
Modified: trunk/docs/manuals/en/developers/developers.kilepr
===================================================================
--- trunk/docs/manuals/en/developers/developers.kilepr 2009-08-04 02:06:40 UTC (rev 9155)
+++ trunk/docs/manuals/en/developers/developers.kilepr 2009-08-09 16:00:02 UTC (rev 9156)
@@ -3,7 +3,7 @@
img_extensions=.eps .jpg .jpeg .png .pdf .ps .fig .gif
kileprversion=2
kileversion=2.0
-lastDocument=regression.tex
+lastDocument=generaldevel.tex
masterDocument=
name=Developers
pkg_extIsRegExp=false
@@ -46,10 +46,10 @@
archive=true
column=0
encoding=
-highlight=
+highlight=LaTeX
line=0
-open=false
-order=-1
+open=true
+order=1
[item:director.tex]
archive=true
@@ -80,12 +80,12 @@
[item:generaldevel.tex]
archive=true
-column=120
+column=2
encoding=
-highlight=
+highlight=LaTeX
line=0
-open=false
-order=-1
+open=true
+order=2
[item:gui-interface.tex]
archive=true
Modified: trunk/docs/manuals/en/developers/generaldevel.tex
===================================================================
--- trunk/docs/manuals/en/developers/generaldevel.tex 2009-08-04 02:06:40 UTC (rev 9155)
+++ trunk/docs/manuals/en/developers/generaldevel.tex 2009-08-09 16:00:02 UTC (rev 9156)
@@ -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,19 +40,27 @@
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
\end{verbatim}
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 @@
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 @@
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 @@
\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 @@
\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 @@
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 @@
\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 @@
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 @@
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 @@
(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 @@
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,109 @@
\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}.
+We have split the previous SVN repository into two because GIT
+offers enormous advantages for ease of managing and integrating
+developer's changes. 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, this requires developers to 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 possibly get your commit privileges
+revoked.
+
+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 Bacula GIT repository with the
+following command:
+
+\begin{verbatim}
+git clone git://bacula.git.sourceforge.net/gitroot/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 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.
+
+
+
\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,16 +549,13 @@
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:
+If you only want the current Bacula source code, you should see
+the above section that describes the GIT repository.
-\begin{verbatim}
-svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula bacula
-\end{verbatim}
-
To view what is in the SVN, point your browser at the following URL:
http://bacula.svn.sourceforge.net/viewvc/bacula/
@@ -1434,5 +1538,3 @@
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.
-
-
Modified: trunk/docs/manuals/en/developers/regression.tex
===================================================================
--- trunk/docs/manuals/en/developers/regression.tex 2009-08-04 02:06:40 UTC (rev 9155)
+++ trunk/docs/manuals/en/developers/regression.tex 2009-08-09 16:00:02 UTC (rev 9156)
@@ -17,63 +17,59 @@
recommend them before putting your system into production, and before each
upgrade, especially if you build from source code. They are
simply shell scripts that drive Bacula through bconsole and then typically
-compare the input and output with diff.
+compare the input and output with {\bf diff}.
-You can find the existing regression script in the Bacula SVN on the
-SourceForge SVN in the project tree named {\bf regress}. I strongly
-recommend that you check it out of the SVN because afterwards, you can
-easily get updates made to them.
+You can find the existing regression scripts in the Bacula developer's
+{\bf git} repository on SourceForge. We strongly recommend that you {\bf
+clone} the repository because afterwards, you can easily get pull the
+updates that have been made.
To get started, we recommend that you create a directory named {\bf
bacula}, under which you will put the current source code and the current
-set of regression scripts. Below, we will describe how to set this up for
-the SVN trunk, but you can also set it up for any branch, such as the
-current Branch-2.4, where the currently released code resides.
+set of regression scripts. Below, we will describe how to set this up.
The top level directory that we call {\bf bacula} can be named anything you
want. Note, all the standard regression scripts run as non-root and can be
-run on the same machine as a production Bacula system (Kern runs it this
-way).
+run on the same machine as a production Bacula system (the developers run
+it this way).
-To create the directory structure for the current trunk code and to
-checkout the necessary files, do the following (note, we assume you
+To create the directory structure for the current trunk and to
+clone the repository, do the following (note, we assume you
are working in your home directory in a non-root account):
\footnotesize
\begin{verbatim}
cd
-mkdir bacula
-cd bacula
-svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula
-svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/regress
+git clone git://bacula.git.sourceforge.net/gitroot/bacula bacula
\end{verbatim}
\normalsize
-This will get the base files that you need. The above should be needed only
+This will create the directory {\bf bacula} and populate it with
+three directories: {\bf bacula}, {\bf gui}, and {\bf regress}.
+{\bf bacula} contains the Bacula source code; {\bf gui} contains
+certain gui programs that you will not need, and {\bf regress} contains
+all the regression scripts. The above should be needed only
once. Thereafter to update to the latest code, you do:
\footnotesize
\begin{verbatim}
-cd bacula/bacula
-svn update
-cd ../regress
-svn update
+cd bacula
+git pull
\end{verbatim}
\normalsize
If you want to test with SQLite and it is not installed on your system,
you will need to download the latest depkgs release from Source Forge and
-unpack it into {\bf bacula/depkgs}, then simply:
+unpack it into {\bf depkgs}, then simply:
\footnotesize
\begin{verbatim}
-cd bacula/depkgs
+cd depkgs
make
\end{verbatim}
\normalsize
-
There are two different aspects of regression testing that this document will
discuss: 1. Running the Regression Script, 2. Writing a Regression test.
@@ -130,8 +126,8 @@
SMTP_HOST="localhost"
# Full "default" path where to find sqlite (no quotes!)
-SQLITE3_DIR=${HOME}/bacula/depkgs/sqlite3
-SQLITE_DIR=${HOME}/bacula/depkgs/sqlite
+SQLITE3_DIR=${HOME}/depkgs/sqlite3
+SQLITE_DIR=${HOME}/depkgs/sqlite
TAPE_DRIVE="/dev/nst0"
# if you don't have an autochanger set AUTOCHANGER to /dev/null
@@ -515,10 +511,9 @@
or, if the source code has been updated, you would do:
\begin{verbatim}
-cd bacula/bacula
-svn update
-cd ../regress
-svn update
+cd bacula
+git pull
+cd regress
make setup
tests/backup-to-null
\end{verbatim}
Modified: trunk/docs/manuals/en/install/dirdconf.tex
===================================================================
--- trunk/docs/manuals/en/install/dirdconf.tex 2009-08-04 02:06:40 UTC (rev 9155)
+++ trunk/docs/manuals/en/install/dirdconf.tex 2009-08-09 16:00:02 UTC (rev 9156)
@@ -714,21 +714,24 @@
\item [Accurate = \lt{}yes|no\gt{}]
\index[dir]{Accurate}
- In accurate mode, FileDaemon known exactly which files were present
- after last backup. So it is able to handle deleted or renamed files.
+ In accurate mode, the File daemon knowns exactly which files were present
+ after the last backup. So it is able to handle deleted or renamed files.
- When restoring a fileset for a specified date (including "most
- recent"), Bacula is able to give you exactly the files and
+ When restoring a FileSet for a specified date (including "most
+ recent"), Bacula is able to restore exactly the files and
directories that existed at the time of the last backup prior to
- that date.
+ that date including ensuring that deleted files are actually deleted,
+ and renamed directories are restored properly.
- In this mode, FileDaemon have to keep all files in memory. So you have
- to check that your memory and swap are sufficent.
+ In this mode, the File daemon must keep data concerning all files in
+ memory. So you do not have sufficient memory, the restore may
+ either be terribly slow or fail.
- $$ memory = \sum_{i=1}^{n}(strlen(path_i + file_i) + sizeof(CurFile))$$
+%% $$ memory = \sum_{i=1}^{n}(strlen(path_i + file_i) + sizeof(CurFile))$$
- For 500.000 files (typical desktop linux system), it will take
- around 64MB of RAM on your FileDaemon.
+ For 500.000 files (a typical desktop linux system), it will require
+ approximately 64 Megabytes of RAM on your File daemon to hold the
+ required information.
\item [Verify Job = \lt{}Job-Resource-Name\gt{}]
\index[dir]{Verify Job}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|