From: Kern Sibbald Date: Thu, 17 May 2007 13:28:01 +0000 (+0000) Subject: Update X-Git-Tag: Release-2.2.0~469 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=16b388b6b22c98b4bf22f773e342f44854a929bb;p=bacula%2Fdocs Update --- diff --git a/docs/developers/generaldevel.tex b/docs/developers/generaldevel.tex index f0be0e88..9773ee7f 100644 --- a/docs/developers/generaldevel.tex +++ b/docs/developers/generaldevel.tex @@ -42,6 +42,7 @@ 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: \begin{verbatim} +svn update svn diff > change.patch \end{verbatim} @@ -184,7 +185,8 @@ 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 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. @@ -212,15 +214,16 @@ Once an Feature Request is accepted, it needs to be implemented. If you 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. @@ -272,6 +275,44 @@ Item 1: Implement a Migration job type that will move the job \end{verbatim} +\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. + + \subsection*{SVN Usage} \index{SVN Usage} \addcontentsline{toc}{subsection}{SVN Usage} @@ -941,8 +982,8 @@ so be conservative in your use of C++ features. \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} @@ -956,6 +997,7 @@ so be conservative in your use of C++ features. 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 they allocate depends on the compiler and the system. Instead use @@ -964,19 +1006,22 @@ so be conservative in your use of C++ features. 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} @@ -985,9 +1030,17 @@ so be conservative in your use of C++ features. \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} diff --git a/docs/developers/imagename_translations b/docs/developers/imagename_translations index 8cfd734f..186c14f0 100644 --- a/docs/developers/imagename_translations +++ b/docs/developers/imagename_translations @@ -1,2 +1,2 @@ -img1.png./bacula-logo.eps img2.png./smartall.eps +img1.png./bacula-logo.eps diff --git a/docs/manual/install.tex b/docs/manual/install.tex index 870c19ff..ac3716e4 100644 --- a/docs/manual/install.tex +++ b/docs/manual/install.tex @@ -177,7 +177,8 @@ if you always run all the components on the same minor version number (i.e. all either 1.38.x or 1.40.x but not mixed). -\section{Beta Releases} +\label{BetaReleases} +\section*{Beta Releases} \index[general]{Beta Releases} Towards the end of the development cycle, which typically runs one year from a major release to another, there will be several beta @@ -188,21 +189,28 @@ The purpose of the beta releases is to allow early adopter users to test the new code. Beta releases are made with the following considerations: \begin{itemize} -\item The code passes the regression testing on Linux, - FreeBSD, and Solaris machines. Including tape drive testing - on Linux and FreeBSD (not currently on Solaris). +\item The code passes the regression testing on Linux and + FreeBSD machines. Including tape drive testing + on Linux and FreeBSD. + \item There are no known major bugs, or on the rare occasion that - there are, they will be documented. + there are, they will be documented or already in the bugs database. + \item Some of the new code/features may not yet be tested. + \item Bugs are expected to be found, especially in the new code before the final production release. + \item The code will have been run in production in at least one small site (mine). + \item The Win32 client will have been run in production at least one night at that small site. + \item The documentation in the manual is unlikely to be complete especially for the new features, and the Release Notes may not be fully organized. + \item Beta code is not generally recommended for everyone, but rather for early adopters. \end{itemize}