From owner-freebsd-doc@FreeBSD.ORG Tue Apr 17 18:30:04 2012 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id EE86F106564A for ; Tue, 17 Apr 2012 18:30:04 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id C2DF38FC1B for ; Tue, 17 Apr 2012 18:30:04 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.5/8.14.5) with ESMTP id q3HIU4op040662 for ; Tue, 17 Apr 2012 18:30:04 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.5/8.14.5/Submit) id q3HIU4Io040661; Tue, 17 Apr 2012 18:30:04 GMT (envelope-from gnats) Resent-Date: Tue, 17 Apr 2012 18:30:04 GMT Resent-Message-Id: <201204171830.q3HIU4Io040661@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Isabell Long Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 027EB1065672 for ; Tue, 17 Apr 2012 18:29:51 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22]) by mx1.freebsd.org (Postfix) with ESMTP id E04BA8FC14 for ; Tue, 17 Apr 2012 18:29:50 +0000 (UTC) Received: from red.freebsd.org (localhost [127.0.0.1]) by red.freebsd.org (8.14.4/8.14.4) with ESMTP id q3HITouX033306 for ; Tue, 17 Apr 2012 18:29:50 GMT (envelope-from nobody@red.freebsd.org) Received: (from nobody@localhost) by red.freebsd.org (8.14.4/8.14.4/Submit) id q3HITot9033301; Tue, 17 Apr 2012 18:29:50 GMT (envelope-from nobody) Message-Id: <201204171829.q3HITot9033301@red.freebsd.org> Date: Tue, 17 Apr 2012 18:29:50 GMT From: Isabell Long To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.1 Cc: Subject: docs/167033: [patch] Add the contents of the wiki page about Subversion vendor imports to the committer's guide. X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 17 Apr 2012 18:30:05 -0000 >Number: 167033 >Category: docs >Synopsis: [patch] Add the contents of the wiki page about Subversion vendor imports to the committer's guide. >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: change-request >Submitter-Id: current-users >Arrival-Date: Tue Apr 17 18:30:04 UTC 2012 >Closed-Date: >Last-Modified: >Originator: Isabell Long >Release: 9.0. >Organization: n/a >Environment: >Description: The separate page about Subversion vendor imports in the wiki's version of the Subversion Primer was not SGMLised as part of Google Code-In. Attached is a diff to go into the committer's guide with all the other Subversion Primer stuff. >How-To-Repeat: >Fix: See the attached diff. Patch attached with submission follows: Index: article.sgml =================================================================== RCS file: /home/isabell/freebsd/doc-cvs/doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v retrieving revision 1.317 diff -u -r1.317 article.sgml --- article.sgml 3 Apr 2012 12:07:47 -0000 1.317 +++ article.sgml 17 Apr 2012 18:04:54 -0000 @@ -2143,6 +2143,265 @@ + Vendor imports with <acronym>SVN</acronym> + + + Please read this entire section before starting a vendor + import. + + + + Patches to vendor code fall into two categories: + + + + 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. + + + &os; patches: these are patches that modify the + vendor code to address &os;-specific issues. + + + + The nature of a patch dictates where it should be + committed: + + + + 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 must not 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. + + + &os; patches should be committed directly to + head. + + + + + + Preparing the tree + + 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. + + + Flattening + + During the conversion from CVS to + Subversion, vendor branches were imported with the same + layout as the main tree. This means that the + pf vendor sources ended up in + vendor/pf/dist/contrib/pf. The + vendor source is best directly in + vendor/pf/dist. + + To flatten the pf tree: + + &prompt.user; cd vendor/pf/dist/contrib/pf +&prompt.user; svn mv $(svn list) ../.. +&prompt.user; cd ../.. +&prompt.user; svn rm contrib +&prompt.user; svn propdel -R svn:mergeinfo . +&prompt.user; svn commit + + The propdel bit is necessary + because starting with 1.5, Subversion will automatically + add svn:mergeinfo 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. + + Tags may be flattened as well (3, 4, 3.5 etc.); the + procedure is exactly the same, only changing + dist to 3.5 or + similar, and putting the svn commit + off until the end of the process. + + + Cleaning up + + The dist 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. + OpenSSH, for example, includes + two files that originated with &os; and still contain the + original version tags. To do this: + + &prompt.user; svn propdel svn:keywords -R . +&prompt.root; svn commit + + + Bootstrapping merge history + + If importing for the first time after the switch to + Subversion, bootstrapping + svn:mergeinfo 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: + + &prompt.user; cd head/contrib/pf +&prompt.user; svn merge --record-only svn+ssh://svn.freebsd.org/base/vendor/pf/dist@180876 . +&prompt.user; svn commit + + + + + Importing new sources + + 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. + + + Preparing the vendor sources + + Unlike in CVS 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. + + A svn add is required to add any + files that were added since the last vendor import, and + svn rm 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. + + &prompt.user; cd vendor/pf/dist +&prompt.user; svn list -R | grep -v '/$' | sort >../old +&prompt.user; cd ../pf-4.3 +&prompt.user; find . -type f | cut -c 3- | sort >../new + + With these two files, comm -23 ../old ../new + will list removed files (files only in + old), while comm -13 ../old ../new + will list added files only in new. + + + Importing into the vendor tree + + Now, the sources must be copied into + dist and + the svn add and + svn rm commands should be used as + needed: + + &prompt.user; cd vendor/pf/pf-4.3 +&prompt.user; tar cf - . | tar xf - -C ../dist +&prompt.user; cd ../dist +&prompt.user; comm -23 ../old ../new | xargs svn rm +&prompt.user; comm -13 ../old ../new | xargs svn --parents add + + If any directories were removed, they will have to be + svn rmed manually. Nothing will break + if they are not, but they will remain in the tree. + + Check properties on any new files. All text files + should have svn:eol-style set to + native. All binary files should have + svn:mime-type set to + application/octet-stream unless there + is a more appropriate media type. Executable files should + have svn:executable set to + *. No other properties should exist + on any file in the tree. + + Committing is now possible, however it is good + practice to make sure that everything is OK by using the + svn stat and + svn diff commands. + + + Tagging + + Once committed, vendor releases should be tagged for + future reference. The best and quickest way to do this + is directly in the repository: + + &prompt.user; svn cp svn+ssh://svn.freebsd.org/base/vendor/pf/dist svn+ssh://svn.freebsd.org/base/vendor/pf/4.3 + + Once that is complete, svn up the + working copy of + vendor/pf + to get the new tag, although this is rarely + needed. + + If creating the tag in the working copy of the tree, + svn:mergeinfo results must be removed: + + &prompt.user; cd vendor/pf +&prompt.user; svn cp dist 4.3 +&prompt.user; svn propdel svn:mergeinfo -R 4.3 + + + + Merging to head + + &prompt.user; cd head/contrib/pf +&prompt.user; svn up +&prompt.user; svn merge --accept=postpone svn+ssh://svn.freebsd.org/base/vendor/pf/dist . + + The --accept=postpone tells + Subversion that it shouldn't complain because merge conflicts + will be taken care of manually. + + It is necessary to resolve any merge conflicts. + This process is the same in SVN as in + CVS. + + 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: + + &prompt.user; svn diff --no-diff-deleted --old=svn+ssh://svn.freebsd.org/base/vendor/pf/dist --new=. + + The --no-diff-deleted 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. + + Using CVS, 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. + + 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. + + + Committing the vendor import + + 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. + + + + Reverting a Commit Reverting a commit to a previous version is fairly >Release-Note: >Audit-Trail: >Unformatted: