[myserver-commit] [2771] Fixed grammar mistakes in the development model document.

[Giuseppe Scrivano]

Revision: 2771
          http://svn.sv.gnu.org/viewvc/?view=rev&root=myserver&revision=2771
Author:   gscrivano
Date:     2008-08-30 09:08:30 +0000 (Sat, 30 Aug 2008)

Log Message:
-----------
Fixed grammar mistakes in the development model document.  Thanks to Michael 
Ploujnikov

Modified Paths:
--------------
    trunk/documentation/dev/development_model/dev_model.tex

Modified: trunk/documentation/dev/development_model/dev_model.tex
===================================================================
--- trunk/documentation/dev/development_model/dev_model.tex     2008-08-29 
21:50:39 UTC (rev 2770)
+++ trunk/documentation/dev/development_model/dev_model.tex     2008-08-30 
09:08:30 UTC (rev 2771)
@@ -54,48 +54,48 @@
 \end{figure}
 
 \begin{section}{Introduction}
-This document is an introduction to how develop GNU MyServer and
-interact with other team members.
-It is not and it doesn't want to be a complete guide to be a
-programmer but only an introduction to the development model used by
+This document is an introduction to developing the GNU MyServer and
+interacting with other team members.
+It is not and it does not intend to be a complete guide for a
+programmer. It is only meant as an introduction to the development model used 
by
 this project.
 The figure \ref{figure:dev_proc} shows the GNU MyServer development
 process.
 In short, at every loop some objectives are planned and a new release
-will be out when they will be completed.
-Before the final release is completed, some minors releases are done
+is made when they are all completed.
+Before the final release is completed, some minor releases are done
 on specified dates, no matter if planned objectives are already
 completed or not.
 
-This development model is not test-driven because write tests and
-develop code are parallel processes.
+This development model is not test-driven because writing tests and
+developing code are parallel processes.
 If somebody finds test-driven a better choice then he or she is free
-to adopt it, it is a personal choice, in any case code is committed
-to the central repository after it is compilable and it is validated
+to adopt it. It is a personal choice. In any case code is committed
+to the central repository after it is compilable is validated
 by all tests.
 The central repository at any time must contain a snapshot of the
 current development status and it must be compilable and usable.
 
-Differently the bugs fixing process is test driven, when a bug is
-detected it should be reproduced by a test.  After the code is
-modified to validate all tests, including the new bug test.
+On the other hand, the bug fixing process is test-driven. When a bug is
+detected it should be reproduced by a test. Then the code is
+modified to pass all tests, including the new bug test.
 Objectives are replanned after a bug is fixed because there can be
-need to release immediately.
+a need to release immediately.
 
-Before the release, code can be changed until it reaches a good
+Before a release, code can be changed until it reaches a good
 readable status (refactoring).
 \end{section}
 
-\begin{section}{How start hacking}
-The first step to take before be a MyServer hacker is to fetch latest
+\begin{section}{How to start hacking}
+The first step to being a MyServer hacker is to fetch latest
 source code version from the subversion version(section
-\ref{section:svn}) and be able to compile it, only after you are able
+\ref{section:svn}) and to be able to compile it. Only after you are able
 to compile and execute MyServer you can think about modify its source
 code.
-To be updated about the MyServer development the best idea is to join
-the mailing lists (section \ref{section:ml}), it is not required to
-partecipate actively there, reading what other members are discussing
-is a good way to be introduced to the project; hopefully after some
+To stay updated about the MyServer development the best idea is to join
+the mailing lists (section \ref{section:ml}). It is not required to
+partecipate actively there. However, reading what other members are discussing
+is a good way to be introduced to the project. Hopefully after some
 time you will be very active there too.
 \end{section}
 
@@ -104,38 +104,37 @@
 Planned tasks are defined by the tasks manager here:
 \url{https://savannah.gnu.org/task/?group=myserver}.
 
-There are two categories of task: \textit{task} and \textit{wish}.
-The former specify a planned task that must be completed.  Once all
+There are two categories of tasks: \textit{task} and \textit{wish}.
+The former specify planned tasks that must be completed.  Once all
 planned task are completed then a new release will be done.
 
 Task that are in the \textit{wish} category are not considered for the
 release.
 
-Any task should be a basic task, in a way that a developer without a
-previous knowledge of the software can start working immediately on
-it.
+Any task should be a stand-alone task, defined in a way that a developer 
without
+previous knowledge of the software can start working on it immediately.
 
-In the past the TODO list files used to be a wish list with tasks like
-\textit{``Implement the FTP protocol''}, such big tasks must be
-avoided and replaced by smaller and more detailed ones, that can be
+In the past, the TODO list files used to be a wish list with tasks like
+\textit{``Implement the FTP protocol''}. Such big tasks must be
+broken down and replaced by smaller and more detailed ones, which can be
 done in few hours.
-Have these macro-tasks means that the feature is not well designed or
-not designed at all and it is a good idea to plan a design for it
-before start working on its implementation and discuss it on the
+Having such macro-tasks means that the feature is not well designed or
+not designed at all. It is a good idea to plan a design for it
+before starting to work on its implementation and discussing it on the
 mailing list with other team members.
-Lately it will be possible to define small tasks and proceed with its
+Later it will be possible to define small tasks and proceed with their
 implementation.
 
-On a bug fix it may be possible to release before other tasks are
-completed, thus all planned tasks that are not completed yet will be
+During a bug fix, it may be possible to release before other tasks are
+completed. In this case all planned tasks that are not completed, will be
 moved to the next release.
 \end{subsection}
 
 \begin{subsection}{Bug tracking}
 Any bug should be notified using this bugs tracking system:
 \url{https://savannah.gnu.org/bugs/?group=myserver}.
-When it is possible, a test for the bug must be provided, it will be
-useful for regression tests as the same bug can appear again in
+When it is possible, a test for the bug must be provided. It will be
+useful for regression tests as the same bug can re-appear in
 future.
 \end{subsection}
 \end{section}
@@ -150,8 +149,8 @@
 \end{subsection}
 
 \begin{subsection}{Code format}
-This simple code snippet shows how format the code and how indent it.
-Don't use the tab character to indent it, instead use 2 blank spaces. 
+This simple code snippet shows how to format the code and how to indent it.
+Please, do not use the tab character for indentation. Instead use 2 blank 
spaces. 
 
 \begin{lstlisting}{language=C++}
 //include/foo.h
@@ -181,83 +180,79 @@
 \end{subsection}
 
 \begin{subsection}{Writing code suggestions}
-These are some simple rules to keep in mind writing code:
+These are some simple rules to keep in mind while writing code:
 \begin{itemize}
 \item Short methods, avoid long methods.
 \item Add comments only when there is really need, code should be
-  clean itself, have many comments will make it more difficult to
+  self-explanatory itself. Having many comments will make it more difficult to
   maintain because any change in the code must be duplicated in the
-  comment.
+  comments.
 \item Add a doxygen compatible comment to every method, this is the
-  only kind of comment that should be always present, more information
+  only kind of comment that should always be present. More information
   about doxygen can be found here:
   \url{http://www.stack.nl/~dimitri/doxygen/}.
-\item Try to avoid mock objects during testing, base classes can be
-  implemented to don't do anything, if you don't know what a mock
+\item Try to avoid mock objects during testing. Base classes can be
+  implemented to not do anything. If you don't know what a mock
   object is then take a look
   here~\url{http://en.wikipedia.org/wiki/Mock_object}.
-\item Possibility to use unit testing as code snippets for APIs, tests
-  code should be as much clean and readable as possible.
-\item Make the code breathe, add blank lines to separe different
+\item Try to use unit testing as code snippets for APIs. Test
+  code should be as clean and as readable as possible.
+\item Let the code breathe. Use blank lines to separe different
   sections and make it clearer.
 \end{itemize}
 \end{subsection}
-In general any \textit{code smell} should be considered too, you can
+In general, any \textit{code smell} should be avoided too. You can
 find some of them here: \url{http://c2.com/cgi/wiki?CodeSmell}.
 \end{section}
 \clearpage
 
 \begin{section}{Mailing lists}\label{section:ml}
-The communication with other project members is fundamental and when a
-message interests everybody then it should be sent on the dev mailing
-list, you can find a list of the mailing lists
+Communication with other project members is fundamental. When a
+message interests everybody, it should be sent on the dev mailing
+list. You can find a list of the mailing lists
 here:~\url{http://savannah.gnu.org/mail/?group=myserver}.
 
 Actually there are two mailing lists:
 \begin{itemize}
-\item address@hidden Differently from what the name can
-  suggest, it is not used only for bugs but for any development
-  related discussion.
-\item address@hidden It is a read-only mailing list,
-  any commit to the repository is notified here.  It is not only a way
-  to annouce you that something happened but it has a very important
-  role in the development process.  Review patches by humans is done
-  at this point, after the commit happened, more eyes can notice
-  better if something is wrong.  If you notice that something is not
-  as it should be, then reply to the address@hidden
-  adding the developer who made the commit in CC, explaining what you
-  consider wrong.
+\item address@hidden Unlike what the name suggests,
+  it is not only used for bugs reports, but for development
+  related discussions also.
+\item address@hidden This is a read-only mailing list.
+  any commit to the repository is posted here.  It is not only a way
+  for annoucing that something happened, but it also plays a very important
+  role in the development process.  The review of patches by humans is done
+  at this point. The more eyes notice a commit, the easier it is to notice 
that something went wrong.  If you notice that something is not
+  as it should be, then reply to address@hidden
+  Add the developer who made the commit in CC and explain what you
+  consider to be wrong.
 \end{itemize}
 \end{section}
 
 \begin{section}{Subversion repository}\label{section:svn}
 \begin{subsection}{Branches}
-If there is need to change many things in the source code, like for
-example when we implemented an event driven scheduler, that changed
-several classes in different sections of the code, then it is a good
-choice to create a branch from \textit{trunk}.
-After the job is completed in a way the branched version is working
-well and it is validated by tests then it can be merged back to the
+If there is a need to change many things in the source code branches are used.
+For example, when we implemented an event driven scheduler, 
+several classes have been changed in different sections of the code.
+Branches are usually based on the \textit{trunk}.
+After the work on a branch has been completed, the branched version is working
+well and it has been validated by tests, the branch can be merged back into the
 \textit{trunk} tree.
-For branches it is not valid the rule that it should work at any time
-or validated by tests as they are experimental versions.  In general
-the developer who created the branch is responsible for the politic to
-follow.
+The revisions which belong to branches do not have to follow strict rules of 
always compiling and passing the test since they are experimental versions.
+In general, the developer who created the branch is responsible for deciding 
what policy to follow.
 \end{subsection}
 
-\begin{subsection}{Access the repository}
-You can find information about how access the source code repository here:
+\begin{subsection}{Accessing the repository}
+You can find information about how to access the source code repository here:
 \url{http://savannah.gnu.org/svn/?group=myserver}.
 \end{subsection}
 
 \begin{subsection}{Commits}
-A commit to the repository shouldn't contain two or more different
+A commit to the repository should not contain two or more different (unrelated)
 modifications to the source code.
-Every commit must be logical different than other ones, any different
-modification must stay in a different commit.
-Use a short but descriptive commit message, the ChangeLog file is not
-maintained manually as it is possible to retrieve it using the commits
-history.  The \textit{svn2cl} utility can generate a GNU compatible
+Every commit must be logically separate from the other ones. 
+Use short, but descriptive commit messages. The ChangeLog file is not
+maintained manually as it is possible to generate it from the revision
+history.  The \textit{svn2cl} utility is used to generate a GNU compatible
 ChangeLog file.
 \end{subsection}
 \end{section}