From: Kern Sibbald Date: Thu, 5 Nov 2009 19:48:11 +0000 (+0100) Subject: Update X-Git-Tag: Release-5.0.0~46 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=5535feb618c890e795d70aa0a776a5c1dd6c2ce4;p=bacula%2Fdocs Update --- diff --git a/docs/autoconf/configure.in b/docs/autoconf/configure.in index 331edd29..30c799e1 100644 --- a/docs/autoconf/configure.in +++ b/docs/autoconf/configure.in @@ -100,12 +100,9 @@ AC_OUTPUT([ \ manuals/de/install/Makefile \ manuals/de/problems/Makefile \ manuals/de/utility/Makefile \ - manuals/en/catalog/Makefile \ - manuals/en/concepts/Makefile \ manuals/en/console/Makefile \ manuals/en/main/Makefile \ manuals/en/developers/Makefile \ - manuals/en/install/Makefile \ manuals/en/problems/Makefile \ manuals/en/utility/Makefile \ manuals/en/misc/Makefile \ diff --git a/docs/configure b/docs/configure index 09322b38..d5dadaa9 100755 --- a/docs/configure +++ b/docs/configure @@ -2189,7 +2189,7 @@ MCOMMON=./autoconf/Make.common -ac_config_files="$ac_config_files autoconf/Make.common Makefile manuals/update_version manuals/version.tex manuals/bacula.sty manuals/de/catalog/Makefile manuals/de/concepts/Makefile manuals/de/console/Makefile manuals/de/developers/Makefile manuals/de/install/Makefile manuals/de/problems/Makefile manuals/de/utility/Makefile manuals/en/catalog/Makefile manuals/en/concepts/Makefile manuals/en/console/Makefile manuals/en/main/Makefile manuals/en/developers/Makefile manuals/en/install/Makefile manuals/en/problems/Makefile manuals/en/utility/Makefile manuals/en/misc/Makefile manuals/es/catalog/Makefile manuals/es/concepts/Makefile manuals/es/console/Makefile manuals/es/developers/Makefile manuals/es/install/Makefile manuals/es/problems/Makefile manuals/es/utility/Makefile manuals/fr/catalog/Makefile manuals/fr/concepts/Makefile manuals/fr/console/Makefile manuals/fr/developers/Makefile manuals/fr/install/Makefile manuals/fr/problems/Makefile manuals/fr/utility/Makefile bacula-web/Makefile bacula-web/version.tex $PFILES" +ac_config_files="$ac_config_files autoconf/Make.common Makefile manuals/update_version manuals/version.tex manuals/bacula.sty manuals/de/catalog/Makefile manuals/de/concepts/Makefile manuals/de/console/Makefile manuals/de/developers/Makefile manuals/de/install/Makefile manuals/de/problems/Makefile manuals/de/utility/Makefile manuals/en/console/Makefile manuals/en/main/Makefile manuals/en/developers/Makefile manuals/en/problems/Makefile manuals/en/utility/Makefile manuals/en/misc/Makefile manuals/es/catalog/Makefile manuals/es/concepts/Makefile manuals/es/console/Makefile manuals/es/developers/Makefile manuals/es/install/Makefile manuals/es/problems/Makefile manuals/es/utility/Makefile manuals/fr/catalog/Makefile manuals/fr/concepts/Makefile manuals/fr/console/Makefile manuals/fr/developers/Makefile manuals/fr/install/Makefile manuals/fr/problems/Makefile manuals/fr/utility/Makefile bacula-web/Makefile bacula-web/version.tex $PFILES" ac_config_commands="$ac_config_commands default" @@ -2777,12 +2777,9 @@ do "manuals/de/install/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/de/install/Makefile" ;; "manuals/de/problems/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/de/problems/Makefile" ;; "manuals/de/utility/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/de/utility/Makefile" ;; - "manuals/en/catalog/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/catalog/Makefile" ;; - "manuals/en/concepts/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/concepts/Makefile" ;; "manuals/en/console/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/console/Makefile" ;; "manuals/en/main/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/main/Makefile" ;; "manuals/en/developers/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/developers/Makefile" ;; - "manuals/en/install/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/install/Makefile" ;; "manuals/en/problems/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/problems/Makefile" ;; "manuals/en/utility/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/utility/Makefile" ;; "manuals/en/misc/Makefile") CONFIG_FILES="$CONFIG_FILES manuals/en/misc/Makefile" ;; diff --git a/docs/manuals/en/developers/Makefile.in b/docs/manuals/en/developers/Makefile.in index 4548627a..947656bc 100644 --- a/docs/manuals/en/developers/Makefile.in +++ b/docs/manuals/en/developers/Makefile.in @@ -19,7 +19,7 @@ DOC=developers first_rule: all -all: tex web dvipdf mini-clean +all: tex web pdf mini-clean .SUFFIXES: .tex .html .PHONY: diff --git a/docs/manuals/en/developers/developers.kilepr b/docs/manuals/en/developers/developers.kilepr index cb84af37..04d798b1 100644 --- a/docs/manuals/en/developers/developers.kilepr +++ b/docs/manuals/en/developers/developers.kilepr @@ -49,7 +49,7 @@ encoding= highlight=LaTeX line=73 open=true -order=1 +order=0 [item:director.tex] archive=true @@ -80,13 +80,22 @@ order=-1 [item:generaldevel.tex] archive=true -column=71 +column=62 encoding= highlight=LaTeX line=553 -open=true +open=false order=2 +[item:git.tex] +archive=true +column=13 +encoding=UTF-8 +highlight=LaTeX +line=339 +open=false +order=-1 + [item:gui-interface.tex] archive=true column=7864421 @@ -165,7 +174,7 @@ column=0 encoding= highlight=LaTeX line=0 -open=true +open=false order=0 [item:smartall.tex] diff --git a/docs/manuals/en/developers/developers.tex b/docs/manuals/en/developers/developers.tex index 11b0fb22..902fa8c8 100644 --- a/docs/manuals/en/developers/developers.tex +++ b/docs/manuals/en/developers/developers.tex @@ -50,6 +50,7 @@ \markboth{Bacula Version \version}{Bacula Version \version} \pagenumbering{arabic} \include{generaldevel} +\include{git} \include{pluginAPI} \include{platformsupport} \include{daemonprotocol} diff --git a/docs/manuals/en/developers/generaldevel.tex b/docs/manuals/en/developers/generaldevel.tex index f29b0200..33312af4 100644 --- a/docs/manuals/en/developers/generaldevel.tex +++ b/docs/manuals/en/developers/generaldevel.tex @@ -380,301 +380,6 @@ So, end the end, the patch file is: \end{itemize} -\section{Bacula Git repositories} -\index{Git} -\addcontentsline{toc}{subsection}{Git repositories} -As of September 2009, the Bacula source code has been split into -three Git repositories. One is a repository that holds the -main Bacula source code with directories {\bf bacula}, {\bf gui}, -and {\bf regress}. The second repository contains -the directories {\bf docs} directory, and the third repository -contains the {\bf rescue} directory. All three repositories are -hosted on Source Forge. - -Previously everything was in a single SVN repository. -We have split the SVN repository into three 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 separted the docs and rescue into their own -repositories, and moved only the parts that are most actively -worked on by the developers (bacula, gui, and regress) to a the -Git Bacula repository. - -Bacula developers must now have a certain knowledege -of Git. - -\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 Bacula 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://@bacula.git.sourceforge.net/gitroot/bacula/bacula trunk -\end{verbatim} - -where you replace \verb++ 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 -\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/}. - -Some of the differences between Git and SVN are: -\begin{itemize} -\item Your main Git directory is a full Git repository to which you can - and must commit. -\item The Git database is kept in the directory {\bf .git} at the - top level of the directory. -\item all the important Git configuration information is kept in the - file {\bf .git/config} in ASCII format that is easy to manually edit. -\item When you do a {\bf commit} the changes are put in {\bf .git} - rather than in the external repository. -\item You can upload your changes to the external repository using - the command {\bf git push}. -\item You can download all the current changes in the external repository - and merge them into your {\bf master} branch using the command - {\bf gGit pull}. -\item The command {\bf git add} is used to add a new file to the - repository AND to tell Git that you want a file that has changed - to be in the next commit. This has lots of advantages, because - a {\bf git commit} only commits those files that have been - explicitly added. -\item You can add and commit all files modifed in one command - using {\bf git commit -a}. -\item This extra use of {\bf add} allows you to make a number - of changes then add only a few of the files and commit them, - then add more files and commit them until you have committed - everything. This has the advantage of allowing you to more - easily group small changes and commit them. -\item If you {\bf git pull} from the main repository and make - some changes, and before you do a {\bf git push}, someone - else pushes changes to the Git repository, you will probably - get an error message such as: - -\begin{verbatim} - git push - To git@github.com:bacula/bacula.git - ! [rejected] master -> master (non-fast forward) - error: failed to push some refs to 'git@github.com:bacula/bacula.git' -\end{verbatim} - - which is Git's way of telling you that the main repository has changed - and that if you push your changes, they will not be integrated properly. - As we have noted, you should never ask Git to force the push. - See below for an explanation of why. -\item To integrate (merge) your changes properly, you should always do - a {\bf git pull} just prior to doing a {\bf git push}. -\item If Git is unable to merge your changes or finds a conflict it - will tell you and you must do conflict resolution, which is much - easier in Git than in SVN. -\item Resolving conflicts is described below in the {\bf github} section. -\end{itemize} - -If you want to understand why it is not a good idea to force a -push to the repository, look at the following picture: - -\includegraphics[width=0.85\textwidth]{\idir git-edit-commit.eps} - -The above graphic has three lines of circles. Each circle represents -a commit, and time runs from the left to the right. The top line -shows the repository just before you are going to do a push. Note the -point at which you pulled is the circle on the left, your changes are -represented by the circle labeled {\bf Your mods}. It is shown below -to indicate that the changes are only in your local repository. Finally, -there are pushes A and B that came after the time at which you pulled. - -If you were to force your changes into the repository, Git would place them -immediately after the point at which you pulled them, so they would -go before the pushes A and B. However, doing so would rewrite the history -of the repository and make it very difficult for other users to synchronize -since they would have to somehow wedge their changes at some point before the -current HEAD of the repository. This situation is shown by the second line of -pushes. - -What you really want to do is to put your changes after Push B (the current HEAD). -This is shown in the third line of pushes. The best way to accomplish this is to -work in a branch, pull the repository so you have your master equal to HEAD (in first -line), then to rebase your branch on the current master and then commit it. The -exact commands to accomplish this are shown in the next couple of sections. - -\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 code, you create a login on -the Github website:\\ -\elink{http://github.com/}{http://github.com/}\\ -before you clone the repository. -You must also upload your public ssh key. Please see the instructions for -doing so at the above link. Then you notify one of the senior Bacula developers, -who will authorize your Github user name as a committer to the Bacula repository. Finally, -you clone the Bacula repository with: - -\begin{verbatim} - git clone git@github.com:bacula/bacula.git -\end{verbatim} - -where you replace \verb++ 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 /newbranch -git checkout /newbranch -(edit, ...) -git add -git commit -m "" -... -\end{verbatim} - -Note, we request you to create the branch name ({\bf \verb++/newbranch} 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 /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 -\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 /newbranch -\end{verbatim} - -If you wish to delete it later, you can use: - -\begin{verbatim} -git push origin :/newbranch -\end{verbatim} - - \section{Developing Bacula} \index{Developing Bacula} \index{Bacula!Developing}