# FossilBook

Check-in [297d7e98bd]

Overview
Comment: Edits in Chapter 1, and changes to the book format family | ancestors | descendants | both | 2ndEdition files | file ages | folders 297d7e98bdaab880849e5d9db765725a390a5239 frans 2012-11-29 16:10:17
Context
 2013-02-25 15:52 check-in: 9b184145bb user: frans tags: 2ndEdition 2012-11-29 16:10 Edits in Chapter 1, and changes to the book format check-in: 297d7e98bd user: frans tags: 2ndEdition 2012-11-28 21:37 Minor corrections in document layout check-in: 7530de7b06 user: frans tags: 2ndEdition
Changes

Changes to Chapters/foreword.tex.

 1 2 3 4 5 6 7 8  \chapter*{Foreword} \medskip{} Pandora Products has carefully checked the information in this document and believes it to be accurate. However, Pandora Products assumes no responsibility for any inaccuracies that this document may contain. In no event will Pandora Products be liable for direct, indirect, special, exemplary, incidental, or consequential damages resulting from any defect or omission in this document, even if advised of the possibility of such damages. In the interest of product development, Pandora Products reserves the right to make improvements to the information in this document and the products that it describes at any time, without notice or obligation. Additional Contributors  |  1 2 3 4 5 6 7 8  \chapter*{Disclaimer} \medskip{} Pandora Products has carefully checked the information in this document and believes it to be accurate. However, Pandora Products assumes no responsibility for any inaccuracies that this document may contain. In no event will Pandora Products be liable for direct, indirect, special, exemplary, incidental, or consequential damages resulting from any defect or omission in this document, even if advised of the possibility of such damages. In the interest of product development, Pandora Products reserves the right to make improvements to the information in this document and the products that it describes at any time, without notice or obligation. Additional Contributors 

Changes to Chapters/introduction.tex.

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72  \chapter{Source Control \& Why you need it} \section{What is it} A source control system is software that manages the files in a project. A project (like this book or a software application) usually has a number of files. You then put all these files in a directory and at times subdivide even that with subdirectories. At any particular time this set of files in their present edited state make up a working version of the project. If other people are using the project you give them this and as is usually the case, they find problems and you fix them. This results in another version of the project slightly changed which goes through the cycle again. (This is why books have editions and software has versions...) Software developers on large projects with multiple developers could see this cycle and realized they needed a tool to control the changes. With multiple developers sometimes the same file would be edited by two different people changing it in different ways or records of what got changed would be lost. It was hard to bring out a new release of the software and be sure that all the bugs were fixed and enhancements made. A tool called Source Code Control System \cite{SCCS} was developed at Bell Labs in 1972 to track changes in files. It would remember each of the changes made to a file and store comments about why this was done. It also limited who could edit the file so conflicting edits would not be done. \cite{USE-SCCS} \label{versioning}This was important but developers could see more was needed. They needed to be able to save the state of all the files in a project and give it a name (i.e., Release 3.14). As software projects mature you will have a released version of the software being used as well as bug reports written against it, while the next release of the software is being developed adding new features. The source control system would have to handle what are now called branches. One branch has say Version 1 which is released but continues to have fixes added to create Version 1.1, 1.2, etc. At the same time you also have another branch which contains Version 2 with new features added under construction. In 1986 the open source Concurrent Version Control system CVS \cite{CVS} was developed. This system could label groups of files and allow multiple branches (i.e. versions) simultaneously. There have been many other systems developed since them some open source and some proprietary. Fossil which was originally released in 2006 \cite{FOSSIL-HOME} is a easy to install version control system that also includes a trouble ticketing system ( Figure\vref{fig:viewticket}), a wiki ( Figure \vref{sub:Wiki-Use}) and self hosted web server ( Figure\vref{fig:Starting-Webserver}). It's home page is here \url{http://www.fossil-scm.org/}. \section{Why do it ?} Why do you want to use a source control system? To use one restricts your freedom, you won't be able to create files, delete files or, move files between directories at random. Making changes in your code becomes a check list of steps that must be followed carefully. With all those hassles why do it? The biggest answer is freedom (huh ?). By following the procedures of a source control system you gain the freedom to modify your code any way you want. How does that follow ? One of the most horrible feelings as a developer is the It worked yesterday'' syndrome. That is, you had code that worked just fine and now it doesn't. You have a very helpless feeling of how do you get back to working code. With a source control system and careful adherence to procedures you can just go back in time and get yesterday's code. Then, starting from known good code you can figure out what happened. Having a source control system also gives you the freedom to experiment, let's try that radical new technique'', and if it doesn't work it's easy to just go back to the previous state. The rest of this book is a user manual for the Fossil version control system that does code management and much much more. It runs on multiple OS's and is FREE. It is simple to install as it has only one executable and the repositories it creates are a single file that is easy to back up and are usually only 50\% the size of the original source. \subsection{How to get it} If this has interested you then you can get a copy of the Fossil executable here \url{http://www.fossil-scm.org/download.html}. There are Linux, Mac, and Windows executable links on this page. Also there is a source Tarball from which you can compile from source. This web site is self-hosted by Fossil itself (see Section\vref{sec:Multiple-Users}). \section{Source control description} This next section is useful if you have not used source control systems before. I will define some of the vocabulary and explain the basic ideas of source control. \subsection{Check out systems} When describing the grandaddy of source control systems, like SCCS I said it managed the changes for a single file and also prevented multiple people from working on the same file at the same time. This is representative of a whole class of source control systems. In these you have the idea of checking-out'' a file so you can edit it. At the same time while other people using the system can see who is working on the file they are prevented from touching it. They can get a read-only copy so they can say build software but only the owner'' can edit it. When done editing the owner'' checks it back in then anyone else could work on on it. At the same time the system has recorded who had it and the changes made to it. This system works well in small groups with real time communication. A common problem is that a file is checked out by some one else and \textbf{you} have to make a change in it. In a small group setting, just a shout over the cube wall will solve the problem. \subsection{Merge systems} In systems represented by CVS or Subversion the barrier is not getting a file to work on but putting it back under version control. In these systems you pull the source code files to a working directory in your area. Then you edit these files making necessary changes. When done you commit or check them back into the repository. At this point they are back under version control and the system knows the changes from the last version to this version. This gets around the problem mentioned above when others are blocked from working on a file. You now have the opposite problem in that more than one person can edit the same file and make changes. This is handled by the check-in process. There only one person at a time may check in a file. That being the case the system checks the file and if there are changes in repository file that are NOT in the one to be checked in stops the check in process. The system will ask if the user wants to merge these changes into his copy. Once that is done the new version of the file can be checked in. This type of system is used on large projects like the Linux kernel or other systems where you have a large number of geographically distributed contributors. \subsection{Distributed systems} The representatives of two major systems we have described thus far are centralized. That is there is only one repository on a single server. When you get a copy of the files or check in files it all goes to just one place. These work and can support many, many users. A distributed system is an extension of this where it allows the repositories to be duplicated and has mechanisms to synchronize them. With a single server users of the repository must be able to connect to it to get updates and for check ins of new code. If you are not connected to the server you are stuck and cannot continue working. Distributed systems allow you to have your own copy of the repository then continue working and when back in communication synchronize with the server. This is very useful where people take their work home and cannot access the company network. Each person can have a copy of the repository and continue working and re-sync upon return to the office. \subsection{Common Terms} The following is a list of terms I will use when talking about version control or Fossil. \begin{description} \item [{Repository}] This is the store when the version controlled files are kept. It will be managed by a source control system \item [{SCS}] Source control system, this is software that manages a group of files keeping track of changes and allowing multiple users to modify them in a controlled fashion \item [{Commit}] In Fossil to store the current set of new and changed files into the repository. \item [{Trunk}] The main line of code descent in a Fossil repository. \item [{Branch}] A user defined split in the files served by an SCS. This allow multiple work points on the same repository. Older branches (versions) might have bug fixes applied and newer branches (versions) can have new features added. \item [{Fork}] In Fossil an involuntary split in the code path, occurs when a file in the repository has changes not in a file to be committed. \end{description}   | | | | | | < | < > | < < | < < < < < <  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63  \chapter{Source Control \& Why you need it} \section{What is Source Control?} A source control system is software that manages the files in a project. A project (like this book or a software application) usually has a number of files. These files in turn are managed by organizing them in directories and sub-directories. At any particular time this set of files in their present edited state make up a working copy of the project at the latest version. If other people are working the same project you would give them your current working copy to start with. As they find and fix problems, their working copy will become different from the one that you have (it will be in a different version). For you to be able to continue where they left off, you will need some mechanism to update your working copy of the files to the latest version available in the team. As soon as you have updated your files, this new version of the project goes through the same cycle again. Most likely the current version will be identified with a code, this is why books have editions and software has versions. Software developers on large projects with multiple developers could see this cycle and realized they needed a tool to control the changes. With multiple developers sometimes the same file would be edited by two different people changing it in different ways and records of what got changed would be lost. It was hard to bring out a new release of the software and be sure that all the work of all team members to fix bugs and write enhancements were included. A tool called Source Code Control System \cite{SCCS} was developed at Bell Labs in 1972 to track changes in files. It would remember each of the changes made to a file and store comments about why this was done. It also limited who could edit the file so conflicting edits would not be done. \cite{USE-SCCS} \label{versioning}This was important but developers could see more was needed. They needed to be able to save the state of all the files in a project and give it a name (i.e., Release 3.14). As software projects mature you will have a released version of the software being used as well as bug reports written against it, while the next release of the software is being developed adding new features. The source control system would have to handle what are now called branches. One branch name for example "Version 1" is released but continues to have fixes added to create Version 1.1, 1.2, etc. At the same time you also have another branch which named "Version 2" with new features added under construction. In 1986 the open source Concurrent Version Control system CVS \cite{CVS} was developed. This system could label groups of files and allow multiple branches (i.e. versions) simultaneously. There have been many other systems developed since them some open source and some proprietary. Fossil which was originally released in 2006 \cite{FOSSIL-HOME} is a easy to install version control system that also includes a trouble ticketing system ( Figure\vref{fig:viewticket}), a wiki ( Figure \vref{sub:Wiki-Use}) and self hosted web server ( Figure\vref{fig:Starting-Webserver}). \section{Why version the files in your project?} Why do you want to use a source control system? You won't be able to create files, delete files or, move files between directories at random. Making changes in your code becomes a check list of steps that must be followed carefully. With all those hassles why do it? One of the most horrible feelings as a developer is the It worked yesterday'' syndrome. That is, you had code that worked just fine and now it doesn't. If you work on only one document, it is conceivable that you saved a copy under a different name (perhaps with a date) that you could go back to. But if you did not, you doubtlessly feel helpless at your inability to get back to working code. With a source control system and careful adherence to procedures you can just go back in time and get yesterday's code, or the code from one hour ago, or from last month. After you have don this, starting from known good code, you can figure out what happened. Having a source control system also gives you the freedom to experiment, let's try that radical new technique'', and if it doesn't work it's easy to just go back to the previous state. The rest of this book is a user manual for the Fossil version control system that does code management and much much more. It runs on multiple OS's and is free and open source software (FOSS). It is simple to install as it has only one executable and the repositories it creates are a single file that is easy to back up and are usually only 50\% the size of the original source. \subsection{How to get it} If this has interested you then you can get a copy of the Fossil executable here \url{http://www.fossil-scm.org/download.html}. There are Linux, Mac, and Windows executable links on this page. The source code is also available if you want or need to compile yourself. This web site, containing this PDF and the code behind the PDF, is self-hosted by Fossil (see Section\vref{sec:Multiple-Users}). \section{Source control description} This next section is useful if you have not used source control systems before. I will define some of the vocabulary and explain the basic ideas of source control. \subsection{Check out systems} When describing the grandaddy of source control systems, like SCCS I said it managed the changes for a single file and also prevented multiple people from working on the same file at the same time. This is representative of a whole class of source control systems. In these you have the idea of checking-out'' a file so you can edit it. At the same time while other people using the system can see who is working on the file they are prevented from touching it. They can get a read-only copy so they can say build software but only the owner'' can edit it. When done editing the owner'' checks it back in then anyone else could work on on it. At the same time the system has recorded who had it and the changes made to it. This system works well in small groups with real time communication. A common problem is that a file is checked out by some one else and \textbf{you} have to make a change in it. In a small group setting, just a shout over the cube wall will solve the problem. \subsection{Merge systems} In systems represented by CVS or Subversion the barrier is not getting a file to work on but putting it back under version control. In these systems you pull the source code files to a working directory in your area. Then you edit these files making necessary changes. When done you commit or check them back into the repository. At this point they are back under version control and the system knows the changes from the last version to this version. This gets around the problem mentioned above when others are blocked from working on a file. You now have the opposite problem in that more than one person can edit the same file and make changes. This is handled by the check-in process. There only one person at a time may check in a file. That being the case the system checks the file and if there are changes in repository file that are NOT in the one to be checked in stops the check in process. The system will ask if the user wants to merge these changes into his copy. Once that is done the new version of the file can be checked in. This type of system is used on large projects like the Linux kernel or other systems where you have a large number of geographically distributed contributors. \subsection{Distributed systems} The representatives of two major systems we have described thus far are centralized. That is there is only one repository on a single server. When you get a copy of the files or check in files it all goes to just one place. These work and can support many, many users. A distributed system is an extension of this where it allows the repositories to be duplicated and has mechanisms to synchronize them. With a single server users of the repository must be able to connect to it to get updates and for check ins of new code. If you are not connected to the server you are stuck and cannot continue working. Distributed systems allow you to have your own copy of the repository then continue working and when back in communication synchronize with the server. This is very useful where people take their work home and cannot access the company network. Each person can have a copy of the repository and continue working and re-sync upon return to the office. \subsection{Common Terms} The following is a list of terms I will use when talking about version control or Fossil. \begin{description} \item [{Repository}] This is the store when the version controlled files are kept. It will be managed by a source control system \item [{SCS}] Source control system, this is software that manages a group of files keeping track of changes and allowing multiple users to modify them in a controlled fashion \item [{Commit}] In Fossil to store the current set of new and changed files into the repository. \item [{Trunk}] The main line of code descent in a Fossil repository. \item [{Branch}] A user defined split in the files served by an SCS. This allow multiple work points on the same repository. Older branches (versions) might have bug fixes applied and newer branches (versions) can have new features added. \item [{Fork}] In Fossil an involuntary split in the code path, occurs when a file in the repository has changes not in a file to be committed. \end{description} 

Changes to fossilbook.out.

 1 2 3 4 5 6 7 8 9 10  \BOOKMARK [0][-]{chapter.1}{1 Source Control \046 Why you need it}{}% 1 \BOOKMARK [1][-]{section.1.1}{1.1 What is it}{chapter.1}% 2 \BOOKMARK [1][-]{section.1.2}{1.2 Why do it ?}{chapter.1}% 3 \BOOKMARK [2][-]{subsection.1.2.1}{1.2.1 How to get it}{section.1.2}% 4 \BOOKMARK [1][-]{section.1.3}{1.3 Source control description}{chapter.1}% 5 \BOOKMARK [2][-]{subsection.1.3.1}{1.3.1 Check out systems}{section.1.3}% 6 \BOOKMARK [2][-]{subsection.1.3.2}{1.3.2 Merge systems}{section.1.3}% 7 \BOOKMARK [2][-]{subsection.1.3.3}{1.3.3 Distributed systems}{section.1.3}% 8 \BOOKMARK [2][-]{subsection.1.3.4}{1.3.4 Common Terms}{section.1.3}% 9 \BOOKMARK [0][-]{chapter.2}{2 Single Users}{}% 10   | |  1 2 3 4 5 6 7 8 9 10  \BOOKMARK [0][-]{chapter.1}{1 Source Control \046 Why you need it}{}% 1 \BOOKMARK [1][-]{section.1.1}{1.1 What is Source Control?}{chapter.1}% 2 \BOOKMARK [1][-]{section.1.2}{1.2 Why version the files in your project?}{chapter.1}% 3 \BOOKMARK [2][-]{subsection.1.2.1}{1.2.1 How to get it}{section.1.2}% 4 \BOOKMARK [1][-]{section.1.3}{1.3 Source control description}{chapter.1}% 5 \BOOKMARK [2][-]{subsection.1.3.1}{1.3.1 Check out systems}{section.1.3}% 6 \BOOKMARK [2][-]{subsection.1.3.2}{1.3.2 Merge systems}{section.1.3}% 7 \BOOKMARK [2][-]{subsection.1.3.3}{1.3.3 Distributed systems}{section.1.3}% 8 \BOOKMARK [2][-]{subsection.1.3.4}{1.3.4 Common Terms}{section.1.3}% 9 \BOOKMARK [0][-]{chapter.2}{2 Single Users}{}% 10 

Changes to fossilbook.pdf.

cannot compute difference between binary files

Changes to fossilbook.tex.
