If you have checked out the source with SVN, you can get a diff using:
\begin{verbatim}
+svn update
svn diff > change.patch
\end{verbatim}
properly fill out a Feature Request form, you probably should check on the email list
first.
-Once I receive the Feature Request, I will either accept it, send it back
+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.
can find a developer for it, or one signs up for implementing it, then the
Feature Request becomes top priority (at least for that developer).
-Between releases of Bacula, I will generally solicit Feature Request input
-for the next version, and by way of this email, I suggest that you send
+Between releases of Bacula, we will generally solicit Feature Request input
+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, I will
+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 -- I am hoping that the Bacula
+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.
\end{verbatim}
-\subsubsection*{SVN Usage}
+\subsection*{Bacula Code Submissions and Projects}
+\index{Submissions and Projects}
+\addcontentsline{toc}{subsection}{Code Submissions and Projects}
+
+Getting code implemented in Bacula works roughly as follows:
+
+\begin{itemize}
+
+\item Kern is the project manager, but prefers not to be a "gate keeper".
+
+\item There are growing numbers of contributions (very good).
+
+\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
+ review it as time permits, integrating it at an appropriate time,
+ responding to my 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 :-)
+
+ 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
+ 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.
+\end{itemize}
+
+
+\subsection*{SVN Usage}
\index{SVN Usage}
-\addcontentsline{toc}{subsubsection}{SVN Usage}
+\addcontentsline{toc}{subsection}{SVN Usage}
Please note that if you are familar with CVS, SVN is very
similar (and better), but there can be a few surprising
rescue/
\end{verbatim}
-If you only want the current source code, you could use:
+Note, you should NEVER commit code to any checkout that you have
+done of a tag. All tags (e.g. Release-1.1, ... Release-2.0.2)
+should be considered read-only.
+
+You may commit code to the most recent item in
+branches (in the above the most recent one is Branch-2.0). If
+you want to commit code to an older branch, then please contact
+Kern first.
+
+You may create your own tags and/or branches, but they should
+have a name clearly distinctive from Branch-, Release-, or Beta-,
+which are official names used by the project. If you create a
+tag, then you should NEVER commit code to it, for the same
+reason noted above -- it should serve as a marker for something
+you released. If you create a branch, then you are free to
+commit to it as you wish.
+
+You may, of course, commit to the trunk.
+
+In summary:
\begin{verbatim}
-svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula bacula
+branches
+ Branch-nnn
+tags
+ Release-nnn
+ Beta-nnn
\end{verbatim}
+are reserved names to be created only by the project manager (or
+with his OK), where the nnn is any sequence of numbers and
+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.
+
+
+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}
-To view what is in the svn, point your browser at the following URL:
+To view what is in the SVN, point your browser at the following URL:
http://bacula.svn.sourceforge.net/viewvc/bacula/
Many of the Subversion (svn) commands are almost identical to those that
you have little to worry about.
\subsection*{Subversion Resources}
-\link{Subversion (svn) Resources}
+\index{Subversion (svn) Resources}
\addcontentsline{toc}{subsection}{Subversion Resources}
\begin{verbatim}
\end{verbatim}
-Main Subversion Page
+Main Subversion Web Page
\elink{http://subversion.tigris.org}{http://subversion.tigris.org}
Subversion Book
\elink{http://svnbook.red-bean.com}{http://svnbook.red-bean.com}
Subversion Clients
-\elink{http://subversion.tigris.org/project_packages.html}{http://subversion.tigris.org/project_packages.html}
+\elink{http://subversion.tigris.org/project\_packages.html}{http://subversion.tigris.org/project\_packages.html}
(For Windows users the TortoiseSVN package is awesome)
GUI UNIX client link
\elink{http://rapidsvn.tigris.org/}{http://rapidsvn.tigris.org/}
+A nice KDE GUI client:
+kdesvn
+
\subsection*{Developing Bacula}
\addcontentsline{toc}{subsubsection}{Do Not Use}
\begin{itemize}
-\item STL -- it is totally incomprehensible.
- \end{itemize}
+ \item STL -- it is totally incomprehensible.
+\end{itemize}
\subsubsection*{Avoid if Possible}
\index{Possible!Avoid if}
to the routines accepting the packet (typically callback routines).
However, declaring "void *buf" is a bad idea. Please use the
correct types whenever possible.
+
\item Using undefined storage specifications such as (short, int, long,
- long long, size_t ...). The problem with all these is that the number of bytes
+ long long, size\_t ...). The problem with all these is that the number of bytes
they allocate depends on the compiler and the system. Instead use
- Bacula's types (int8_t, uint8_t, int32_t, uint32_t, int64_t, and
- uint64_t). This guarantees that the variables are given exactly the
- size you want. Please try at all possible to avoid using size_t ssize_t
+ Bacula's types (int8\_t, uint8\_t, int32\_t, uint32\_t, int64\_t, and
+ uint64\_t). This guarantees that the variables are given exactly the
+ size you want. Please try at all possible to avoid using size\_t ssize\_t
and the such. They are very system dependent. However, some system
routines may need them, so their use is often unavoidable.
+
\item Returning a malloc'ed buffer from a subroutine -- someone will forget
to release it.
-\item Using reference variables -- it allows subroutines to create side
- effects. Reference variables are OK, if you are sure the variable
- *always* exists, and you are sure you can handle the side effects of
- a subroutine changing the "pointer".
-\item Heap allocation (malloc) unless needed -- it is expensive.
+
+\item Heap allocation (malloc) unless needed -- it is expensive. Use
+ POOL\_MEM instead.
+
\item Templates -- they can create portability problems.
+
\item Fancy or tricky C or C++ code, unless you give a good explanation of
why you used it.
+
\item Too much inheritance -- it can complicate the code, and make reading it
difficult (unless you are in love with colons)
- \end{itemize}
+
+\end{itemize}
\subsubsection*{Do Use Whenever Possible}
\index{Possible!Do Use Whenever}
\begin{itemize}
\item Locking and unlocking within a single subroutine.
+
+\item A single point of exit from all subroutines. A goto is
+ perfectly OK to use to get out early, but only to a label
+ named bail\_out, and possibly an ok\_out. See current code
+ examples.
+
\item Malloc and free within a single subroutine.
+
\item Comments and global explanations on what your code or algorithm does.
- \end{itemize}
+
+\end{itemize}
\subsubsection*{Indenting Standards}
\index{Standards!Indenting}