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

[Jean Delvare]

Hi Jerome,

A few random comments on your documentation update patch:

> +\subsection{Sharing your patches}
> +
> +You may sometimes need to share your patches with someone else, or 
> +reapply them on another instance of your software. As quilt patches are all
> +contained in the \textsf{patches} directory, sharing your patches is a
> +very simple operation. Make sure your patches are all up to date using
> +\quilt{refresh}, and distribute the contents of your patches directory.

It might be worth mentioning the "quilt diff --combine" command as
another way to export the patches. While the patches directory carries
more information, a single patch may be more convenient to work with in
in some cases, for example if you want to share your patch series with
someone who doesn't use quilt.

Side question, is there a way to automatically refresh all the patches?
I can't seem to find one. I am thinking of something in the line of
"quilt push --refresh", so the --refresh could go into QUILT_PUSH_ARGS
and "push -a" would do just what was described above ("make sure your
patches are all up to date"). Should I try implementing this?

> +\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. 
> +
> +First make sure that your original patches are all up to date using 
> +\quilt{refresh}.
> +
> +Then if you start in a new directory, retrieve the new version of the 
> sofwtare,

Typo on "software".

> +(e.g. extract it from an archive or retrieve it from a remote source control
> +repository) and copy your original \textsf{patches} directory inside this new
> +directory. Otherwise, if you want to update your local version of the 
> software
> +using a source control client, you must first make sure your local tree is
> +clean of your patches. You can ensure that by removing all patches using
> +\quilt{pop -a} before applying the command that will update the local tree
> +\footnote{
> +    it's a mistake to merge your local changes using the source control

Uppercase "i" please.

> +    client. If you do that you will have a hard time updating your patches. 
> In 
> +    that case, it's better to start from scratch and reapply your patches on 
> a
> +    new project.
> +}. You can double check the clean state of your local tree using the diff 
> tool
> +that comes with your source control client.
> +
> +Finally apply your patches, either one by one or all at once using
> +\quilt{push -a}. If nothing fails, you're done. Otherwise you will have to 
> clean
> +up your patches. If one of your local patch was applied upstream, just 
> remove 
> +it using \quilt{delete}. If there are conflicts betweem the new code and a

Typo on "between".

> +local patch, you may need to rework your patches and \quilt{refresh} them one
> +at a time.
> +

I am not entierly convinced by this subsection. It's a bit too long for
a simple example, most probably because you are mixing 3 different
concepts: exporting the series to a different base, updating the base in
place, and the confusing footnote. The first concept was already covered
by your "Sharing your patches" section above, so I don't think it should
be mentioned again here. You should really dedicate the subsection to a
typical in place codebase update (and we don't care how the update is
done, manually or through CVS, it doesn't matter). Andreas managed to
put this in 3 lines, so you should be able to come up with something
significantly smaller than what you have here. Remember that this PDF
document is meant to give short, typical examples of quilt uses. It's
not meant to cover all possibilities nor explain things in deep detail -
there's a manual page for that.

Thanks,
-- 
Jean Delvare