Add a section about vendor imports, which is a part of the Subversion
Primer from the FreeBSD wiki. PR: docs/167033 Submitted by: Isabell Long (isabell issyl0 co uk)
This commit is contained in:
Benedict Reuschling
parent
f35ecd8fa1
commit
5f35b677f4
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=38706
1 changed files with 261 additions and 0 deletions
|
|
@ -2142,6 +2142,267 @@ $target - head/$source:$P,$Q,$R</screen>
|
||||||
</sect4>
|
</sect4>
|
||||||
</sect3>
|
</sect3>
|
||||||
|
|
||||||
|
<sect3>
|
||||||
|
<title>Vendor imports with <acronym>SVN</acronym></title>
|
||||||
|
|
||||||
|
<important>
|
||||||
|
<para>Please read this entire section before starting a vendor
|
||||||
|
import.</para>
|
||||||
|
</important>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>Patches to vendor code fall into two categories:</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Vendor patches: these are patches that have been
|
||||||
|
issued by the vendor, or that have been extracted from
|
||||||
|
the vendor's version control system, which address
|
||||||
|
issues which in your opinion can't wait until the next
|
||||||
|
vendor release.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>&os; patches: these are patches that modify the
|
||||||
|
vendor code to address &os;-specific issues.</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>The nature of a patch dictates where it should be
|
||||||
|
committed:</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Vendor patches should be committed to the vendor
|
||||||
|
branch, and merged from there to head. If the patch
|
||||||
|
addresses an issue in a new release that is currently
|
||||||
|
being imported, it <emphasis>must not</emphasis> be
|
||||||
|
committed along with the new release: the release must
|
||||||
|
be imported and tagged first, then the patch can be
|
||||||
|
applied and committed. There is no need to re-tag the
|
||||||
|
vendor sources after committing the patch.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>&os; patches should be committed directly to
|
||||||
|
head.</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</note>
|
||||||
|
|
||||||
|
<sect4>
|
||||||
|
<title>Preparing the tree</title>
|
||||||
|
|
||||||
|
<para>If importing for the first time after the switch to
|
||||||
|
Subversion, flattening and cleaning up the vendor tree is
|
||||||
|
necessary, as well as bootstrapping the merge history in
|
||||||
|
the main tree.</para>
|
||||||
|
|
||||||
|
<sect5>
|
||||||
|
<title>Flattening</title>
|
||||||
|
|
||||||
|
<para>During the conversion from <acronym>CVS</acronym> to
|
||||||
|
Subversion, vendor branches were imported with the same
|
||||||
|
layout as the main tree. This means that the
|
||||||
|
<literal>pf</literal> vendor sources ended up in
|
||||||
|
<filename>vendor/pf/dist/contrib/pf</filename>. The
|
||||||
|
vendor source is best directly in
|
||||||
|
<filename>vendor/pf/dist</filename>.</para>
|
||||||
|
|
||||||
|
<para>To flatten the <literal>pf</literal> tree:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/dist/contrib/pf</replaceable></userinput>
|
||||||
|
&prompt.user; <userinput>svn mv $(svn list) ../..</userinput>
|
||||||
|
&prompt.user; <userinput>cd ../..</userinput>
|
||||||
|
&prompt.user; <userinput>svn rm contrib</userinput>
|
||||||
|
&prompt.user; <userinput>svn propdel -R svn:mergeinfo .</userinput>
|
||||||
|
&prompt.user; <userinput>svn commit</userinput></screen>
|
||||||
|
|
||||||
|
<para>The <literal>propdel</literal> bit is necessary
|
||||||
|
because starting with 1.5, Subversion will automatically
|
||||||
|
add <literal>svn:mergeinfo</literal> to any directory
|
||||||
|
that is copied or moved. In this case, as nothing is
|
||||||
|
being merged from the deleted tree, they just get in the
|
||||||
|
way.</para>
|
||||||
|
|
||||||
|
<para>Tags may be flattened as well (3, 4, 3.5 etc.); the
|
||||||
|
procedure is exactly the same, only changing
|
||||||
|
<literal>dist</literal> to <literal>3.5</literal> or
|
||||||
|
similar, and putting the <command>svn commit</command>
|
||||||
|
off until the end of the process.</para>
|
||||||
|
</sect5>
|
||||||
|
<sect5>
|
||||||
|
<title>Cleaning up</title>
|
||||||
|
|
||||||
|
<para>The <literal>dist</literal> tree can be cleaned up
|
||||||
|
as necessary. Disabling keyword expansion is
|
||||||
|
recommended, as it makes no sense on unmodified vendor
|
||||||
|
code and in some cases it can even be harmful.
|
||||||
|
<application>OpenSSH</application>, for example, includes
|
||||||
|
two files that originated with &os; and still contain the
|
||||||
|
original version tags. To do this:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>svn propdel svn:keywords -R .</userinput>
|
||||||
|
&prompt.root; <userinput>svn commit</userinput></screen>
|
||||||
|
</sect5>
|
||||||
|
<sect5>
|
||||||
|
<title>Bootstrapping merge history</title>
|
||||||
|
|
||||||
|
<para>If importing for the first time after the switch to
|
||||||
|
Subversion, bootstrapping
|
||||||
|
<literal>svn:mergeinfo</literal> on the target directory
|
||||||
|
in the main tree to the to the revision that corresponds
|
||||||
|
to the last related change to the vendor tree, prior to
|
||||||
|
importing new sources:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput>
|
||||||
|
&prompt.user; <userinput>svn merge --record-only svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist@180876</replaceable> .</userinput>
|
||||||
|
&prompt.user; <userinput>svn commit</userinput></screen>
|
||||||
|
</sect5>
|
||||||
|
</sect4>
|
||||||
|
|
||||||
|
<sect4>
|
||||||
|
<title>Importing new sources</title>
|
||||||
|
|
||||||
|
<para>With two commits—one for the import itself and
|
||||||
|
one for the tag—this step can optionally be repeated
|
||||||
|
for every upstream release between the last import and the
|
||||||
|
current import.</para>
|
||||||
|
|
||||||
|
<sect5>
|
||||||
|
<title>Preparing the vendor sources</title>
|
||||||
|
|
||||||
|
<para>Unlike in <acronym>CVS</acronym> where only the needed
|
||||||
|
parts were imported into the vendor tree to avoid bloating
|
||||||
|
the main tree, Subversion is able to store a full
|
||||||
|
distribution in the vendor tree. So, import everything,
|
||||||
|
but merge only what is required.</para>
|
||||||
|
|
||||||
|
<para>A <command>svn add</command> is required to add any
|
||||||
|
files that were added since the last vendor import, and
|
||||||
|
<command>svn rm</command> is required to remove any that
|
||||||
|
were removed since. Preparing sorted lists of the
|
||||||
|
contents of the vendor tree and of the sources that are
|
||||||
|
about to be imported is recommended, to facilitate the
|
||||||
|
process.</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/dist</replaceable></userinput>
|
||||||
|
&prompt.user; <userinput>svn list -R | grep -v '/$' | sort >../old</userinput>
|
||||||
|
&prompt.user; <userinput>cd <replaceable>../pf-4.3</replaceable></userinput>
|
||||||
|
&prompt.user; <userinput>find . -type f | cut -c 3- | sort >../new</userinput></screen>
|
||||||
|
|
||||||
|
<para>With these two files,
|
||||||
|
<command>comm -23 ../old ../new</command>
|
||||||
|
will list removed files (files only in
|
||||||
|
<filename>old</filename>), while
|
||||||
|
<command>comm -13 ../old ../new</command>
|
||||||
|
will list added files only in <filename>new</filename>.</para>
|
||||||
|
</sect5>
|
||||||
|
<sect5>
|
||||||
|
<title>Importing into the vendor tree</title>
|
||||||
|
|
||||||
|
<para>Now, the sources must be copied into
|
||||||
|
<filename><replaceable>dist</replaceable></filename> and
|
||||||
|
the <command>svn add</command> and
|
||||||
|
<command>svn rm</command> commands should be used as
|
||||||
|
needed:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/pf-4.3</replaceable></userinput>
|
||||||
|
&prompt.user; <userinput>tar cf - . | tar xf - -C ../dist</userinput>
|
||||||
|
&prompt.user; <userinput>cd <replaceable>../dist</replaceable></userinput>
|
||||||
|
&prompt.user; <userinput>comm -23 ../old ../new | xargs svn rm</userinput>
|
||||||
|
&prompt.user; <userinput>comm -13 ../old ../new | xargs svn --parents add</userinput></screen>
|
||||||
|
|
||||||
|
<para>If any directories were removed, they will have to be
|
||||||
|
<command>svn rm</command>ed manually. Nothing will break
|
||||||
|
if they are not, but they will remain in the tree.</para>
|
||||||
|
|
||||||
|
<para>Check properties on any new files. All text files
|
||||||
|
should have <literal>svn:eol-style</literal> set to
|
||||||
|
<literal>native</literal>. All binary files should have
|
||||||
|
<literal>svn:mime-type</literal> set to
|
||||||
|
<literal>application/octet-stream</literal> unless there
|
||||||
|
is a more appropriate media type. Executable files should
|
||||||
|
have <literal>svn:executable</literal> set to
|
||||||
|
<literal>*</literal>. No other properties should exist
|
||||||
|
on any file in the tree.</para>
|
||||||
|
|
||||||
|
<para>Committing is now possible, however it is good
|
||||||
|
practice to make sure that everything is OK by using the
|
||||||
|
<command>svn stat</command> and
|
||||||
|
<command>svn diff</command> commands.</para>
|
||||||
|
</sect5>
|
||||||
|
<sect5>
|
||||||
|
<title>Tagging</title>
|
||||||
|
|
||||||
|
<para>Once committed, vendor releases should be tagged for
|
||||||
|
future reference. The best and quickest way to do this
|
||||||
|
is directly in the repository:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>svn cp svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/4.3</replaceable></userinput></screen>
|
||||||
|
|
||||||
|
<para>Once that is complete, <command>svn up</command> the
|
||||||
|
working copy of
|
||||||
|
<filename><replaceable>vendor/pf</replaceable></filename>
|
||||||
|
to get the new tag, although this is rarely
|
||||||
|
needed.</para>
|
||||||
|
|
||||||
|
<para>If creating the tag in the working copy of the tree,
|
||||||
|
<command>svn:mergeinfo</command> results must be removed:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>cd <replaceable>vendor/pf</replaceable></userinput>
|
||||||
|
&prompt.user; <userinput>svn cp dist 4.3</userinput>
|
||||||
|
&prompt.user; <userinput>svn propdel svn:mergeinfo -R 4.3</userinput></screen>
|
||||||
|
</sect5>
|
||||||
|
</sect4>
|
||||||
|
<sect4>
|
||||||
|
<title>Merging to head</title>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput>
|
||||||
|
&prompt.user; <userinput>svn up</userinput>
|
||||||
|
&prompt.user; <userinput>svn merge --accept=postpone svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> .</userinput></screen>
|
||||||
|
|
||||||
|
<para>The <literal>--accept=postpone</literal> tells
|
||||||
|
Subversion that it shouldn't complain because merge conflicts
|
||||||
|
will be taken care of manually.</para>
|
||||||
|
|
||||||
|
<para>It is necessary to resolve any merge conflicts.
|
||||||
|
This process is the same in <acronym>SVN</acronym> as in
|
||||||
|
<acronym>CVS</acronym>.</para>
|
||||||
|
|
||||||
|
<para>Make sure that any files that were added or removed in
|
||||||
|
the vendor tree have been properly added or removed in the
|
||||||
|
main tree. To check diffs against the vendor branch:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> --new=.</userinput></screen>
|
||||||
|
|
||||||
|
<para>The <literal>--no-diff-deleted</literal> tells
|
||||||
|
Subversion not to complain about files that are in the
|
||||||
|
vendor tree but not in the main tree, i.e. things that
|
||||||
|
would have previously been removed before the vendor
|
||||||
|
import, like for example the like the vendor's makefiles
|
||||||
|
and configure scripts.</para>
|
||||||
|
|
||||||
|
<para>Using <acronym>CVS</acronym>, once a file was off the
|
||||||
|
vendor branch, it was not able to be put back. With
|
||||||
|
Subversion, there is no concept of on or off the vendor
|
||||||
|
branch. If a file that previously had local
|
||||||
|
modifications, to make it not show up in diffs in the
|
||||||
|
vendor tree, all that has to be done is remove any left-over
|
||||||
|
cruft like &os; version tags, which is much easier.</para>
|
||||||
|
|
||||||
|
<para>If any changes are required for the world to build
|
||||||
|
with the new sources, make them now, and keep testing
|
||||||
|
until everything builds and runs perfectly.</para>
|
||||||
|
</sect4>
|
||||||
|
<sect4>
|
||||||
|
<title>Committing the vendor import</title>
|
||||||
|
|
||||||
|
<para>Committing is now possible! Everything must be
|
||||||
|
committed in one go. If done properly, the tree will move
|
||||||
|
from a consistent state with old code, to a consistent
|
||||||
|
state with new code.</para>
|
||||||
|
</sect4>
|
||||||
|
</sect3>
|
||||||
|
|
||||||
<sect3>
|
<sect3>
|
||||||
<title>Reverting a Commit</title>
|
<title>Reverting a Commit</title>
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue