Re: [Quilt-dev] merging with upstream and adding new files

[Andreas Gruenbacher]

On Sunday 12 June 2005 16:08, jerome lacoste wrote:
> > Agreed, and documenting it is very needed. But let's keep the
> > documentation concise, so that the reader actually understands how easy
> > it is. Updating the codebase is a simple, 4 step process: pop all
> > patches, update the codebase (whatever the method is), delete all
> > redundant patches, push all remaining patches. I don't think we have to
> > say more than just that.
> >
> > Thanks,
> > --
> > Jean Delvare
>
> Second attempt :)

Okay, here are a few changes from me as well. Fine?

Index: doc/main.tex
===================================================================
--- doc/main.tex        8 May 2005 17:43:58 -0000       1.13
+++ doc/main.tex        12 Jun 2005 15:53:03 -0000
@@ -189,6 +189,13 @@
 are not applied at a particular moment (\quilt{next}, \quilt{unapplied}).
 By default, most commands apply to the topmost patch on the stack.
 
+When files in the working directory are changed, those changes become
+part of the working state of the topmost patch, provided that those
+files are part of the patch. Files that are not part of a patch must be
+added before modifying them so that quilt is aware of the original
+versions of the files. The \quilt{refresh} command regenerates a patch.
+After the refresh, the patch and the working state are the same.
+
 Patch files are located in the \textsf{patches} sub-directory of the
 source tree (see Figure~\ref{fig:dir-layout}). The \textsf{QUILT\_PATCHES}
 environment variable can be used to override this location. The
@@ -248,8 +255,7 @@
 
 Documentation related to a patch can be put at the beginning of a patch
 file.  Quilt is careful to preserve all text that precedes the actual
-patch when doing a refresh. (This is limited to patches in unified
-format; see~\cite{info-diff}).
+patch when doing a refresh.
 
 The series file is looked up in the root of the source tree, in the
 patches directory, and in the \textsf{.pc} directory.  The first series
@@ -258,13 +264,13 @@
 set of patches, so the \textsf{patches} sub-directory is a convenient
 location.
 
-The \textsf{.pc} directory and its sub-directories cannot be relocated,
-but \textsf{.pc} may be a symbolic link. While patches are applied to
-the source tree, the \textsf{.pc} directory is essential for many
-operations, including taking patches off the stack (\quilt{pop}), and
-refreshing patches (\quilt{refresh}). Files in the \textsf{.pc}
-directory are automatically removed when they are no longer needed, so
-usually there is no need to clean up manually.
+While patches are applied to the source tree, the \textsf{.pc} directory
+is essential for many operations, including taking patches off the stack
+(\quilt{pop}), and refreshing patches (\quilt{refresh}). Files in the
+\textsf{.pc} directory are automatically removed when they are no longer
+needed, so usually there is no need to clean up manually.  The
+\textsf{QUILT\_PC} environment variable can be used to override the
+location of the \textsf{.pc} directory.
 
 \section{An Example}
 
@@ -281,7 +287,7 @@
 \end{small}
 
 New patches are created with \quilt{new}. A new patch automatically
-becomes the topmost patch on the stack. Files must be added to a patch
+becomes the topmost patch on the stack. Files must be added
 with \quilt{add} before they are modified. Note that this is slightly
 different from the CVS style of interaction: with CVS, files are in the
 repository, and adding them before committing (but after modifying them)
@@ -516,6 +522,26 @@
 } and then applying the patch to the working tree.  The \quilt{fold}
 command combines these steps.
 
+\subsection{Sharing patches with others}
+
+For sharing a set of patches with someone else, the series file which
+contains the list of patches and how they are applied, and the patches
+themselves are all that's needed. The \textsl{.pc} directory only
+contains quilt's working state, and should not be distributed. Make sure
+that all the patches are up-to-date, and refresh patches when
+necessary. The \textsf{--combine} option of \quilt{diff} can be used for
+generating a single patch out of all the patches in the series file.
+
+\subsection{Merging with upstream}
+
+The concept of merging your patches with upstream is identical to applying
+your patches on a more recent version of the software. 
+
+Before merging, make sure to pop all your patches using \quilt{pop -a}.
+Then, update your codebase. Finally, remove obsoleted patches
+from the series file and \quilt{push} the remaining ones, resolve
+conflicts and refresh patches as needed.
+
 \subsection{Forking}
 \label{sec:forking}
 
> I also attach a small Makefile patch.

Nice, thanks.

Cheers,
Andreas.