From nobody Fri Oct 20 15:16:17 2023 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4SBp812xqhz4xtS8 for ; Fri, 20 Oct 2023 15:16:17 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4SBp812SNjz4t4x; Fri, 20 Oct 2023 15:16:17 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1697814977; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=VLhCYLyEbOGgBiggg/Ow/SC9RCBdNqWELPfLJan0sDo=; b=dgi1YDKyXvH00p+3ruxSkPDLb5F1uHvzgLEhYQVdvih6mi9Q4BJEkBXwQV9EkswIaw2ZEQ ptqH8C+lpUBiH+xRk5+AVxz16UXlBlczpkrfjwY01VYdrmx3JhmjPHH9+3S+enZuYcIMmx 7tiLWPU6vzGZq7ul1bIjBiw7RswtJBjwcc21qsqORtuk7/AFXz1BbGXtnJgitmsz8W6kRe uYIYoPDCFfEko92r2nc+sOgsphyehJlEQ47XjZcY28w4WTNeQeRvjp1LJCwelLMpa7I6t1 Ak6VG5YjB0aenJNrJhFZXRAfOXZTLztKd+6T6ggFWk+sB3EEKQ+MPfIssJwDOg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1697814977; a=rsa-sha256; cv=none; b=FePqRIldKrXjLnGesM5eM19FcjALnIetW1Ccfh+wId7j1z0xjXcWTz5JSCgIcfSpZX6+6k qfywQ146n+iCSnXRNLumsVPfPT3BndusgGRsifDUu2WKM9E5It8CTsEfBf7gdcxpRHZKsU 1Twmy5bCqw2+WL8Y5vKHIuoC50OKFSNDGlvtCyOxv+wqRKd1J7T/Wyd3K3COFIfrotG6Q1 nFhCGto6pJFJnEOKr+jugKH9E0BVOTW763vFkvkmsAyzxKRO0JXZQ/7uFGs3wWeu1ORoqr DImJRExX0xFZ1NUC3rWTOUn5KUr85pYan8h/86+ho9mX3diK2s5ZPEPxEAyxeQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1697814977; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=VLhCYLyEbOGgBiggg/Ow/SC9RCBdNqWELPfLJan0sDo=; b=nNYMT/SMvpiflFHASsb93An7M9iZHvsVdTFWbrpg9tDc5kIMA3Snpxzt23bpSZFFPKcht+ VQbonj+RvEPWM3/K9jRR98BHUCeez3+N0oT5n5QB/fT8jy4xlpXk6At4zykU65euEE2L2S q7uDwN4EeLZbErHJPXiFU9fPEGyPp5n4792NI3Oop6bR0yTWWeNWriqNN+EZxSkqFGAS+r vaR8JRq61F++vHRN3p/SkPjU1E1Lv30LtM1g0qsgDkcyDuuvwlUp4f55983MlbNv+j8Z2a n7ZqpPhIQ1hJdjqk4xO1FTDMUb3rRSDdam63z7w5/Z4OfuLAjw7Ds0gVrBDSXQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4SBp811WL7zdQP; Fri, 20 Oct 2023 15:16:17 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 39KFGHls055162; Fri, 20 Oct 2023 15:16:17 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 39KFGHCR055158; Fri, 20 Oct 2023 15:16:17 GMT (envelope-from git) Date: Fri, 20 Oct 2023 15:16:17 GMT Message-Id: <202310201516.39KFGHCR055158@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Mitchell Horne Subject: git: 7f6cab7b88 - main - developers-handbook: remove SVN vendor import section List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: mhorne X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 7f6cab7b88f859796ce325ec0f7194ff43e69ae9 Auto-Submitted: auto-generated The branch main has been updated by mhorne: URL: https://cgit.FreeBSD.org/doc/commit/?id=7f6cab7b88f859796ce325ec0f7194ff43e69ae9 commit 7f6cab7b88f859796ce325ec0f7194ff43e69ae9 Author: Mitchell Horne AuthorDate: 2023-10-20 15:14:19 +0000 Commit: Mitchell Horne CommitDate: 2023-10-20 15:14:19 +0000 developers-handbook: remove SVN vendor import section It is obsolete. Point to the chapter in the Committer's Guide instead. Reviewed by: carlavilla, imp, emaste Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D42301 --- .../books/developers-handbook/policies/_index.adoc | 169 +-------------------- 1 file changed, 3 insertions(+), 166 deletions(-) diff --git a/documentation/content/en/books/developers-handbook/policies/_index.adoc b/documentation/content/en/books/developers-handbook/policies/_index.adoc index 8a82420765..93a034458c 100644 --- a/documentation/content/en/books/developers-handbook/policies/_index.adoc +++ b/documentation/content/en/books/developers-handbook/policies/_index.adoc @@ -105,173 +105,10 @@ The ability to maintain the package in the future will be a key issue in the dec Because it makes it harder to import future versions minor, trivial and/or cosmetic changes are _strongly discouraged_ on files that are still tracking the vendor branch. ==== -[[vendor-import-svn]] -=== Vendor Imports with SVN - -This section describes the vendor import procedure with Subversion in details. - -[.procedure] -. *Preparing the Tree* -+ -If this is your first import after the switch to SVN, you will have to flatten and clean up the vendor tree, and bootstrap merge history in the main tree. -If not, you can safely omit this step. -+ -During the conversion from CVS to SVN, vendor branches were imported with the same layout as the main tree. -For example, the foo vendor sources ended up in [.filename]#vendor/foo/dist/contrib/foo#, but it is pointless and rather inconvenient. -What we really want is to have the vendor source directly in [.filename]#vendor/foo/dist#, like this: -+ -[source,bash] -.... -% cd vendor/foo/dist/contrib/foo -% svn move $(svn list) ../.. -% cd ../.. -% svn remove contrib -% svn propdel -R svn:mergeinfo -% svn commit -.... -+ -Note that, the `propdel` bit is necessary because starting with 1.5, Subversion will automatically add `svn:mergeinfo` to any directory you copy or move. -In this case, you will not need this information, since you are not going to merge anything from the tree you deleted. -+ -[NOTE] -==== -You may want to flatten the tags as well. -The procedure is exactly the same. -If you do this, put off the commit until the end. -==== -+ -Check the [.filename]#dist# tree and perform any cleanup that is deemed to be necessary. -You may want to disable keyword expansion, as it makes no sense on unmodified vendor code. -In some cases, it can be even be harmful. -+ -[source,bash] -.... -% svn propdel svn:keywords -R . -% svn commit -.... -+ -Bootstrapping of `svn:mergeinfo` on the target directory (in the main tree) to the revision that corresponds to the last change was made to the vendor tree prior to importing new sources is also needed: -+ -[source,bash] -.... -% cd head/contrib/foo -% svn merge --record-only ^/vendor/foo/dist@12345678 . -% svn commit -.... -+ -With some shells, the `^` in the above command may need to be escaped with a backslash. -. *Importing New Sources* -+ -Prepare a full, clean tree of the vendor sources. -With SVN, we can keep a full distribution in the vendor tree without bloating the main tree. -Import everything but merge only what is needed. -+ -Note that you will need to add any files that were added since the last vendor import, and remove any that were removed. -To facilitate this, you should prepare sorted lists of the contents of the vendor tree and of the sources you are about to import: -+ -[source,bash] -.... -% cd vendor/foo/dist -% svn list -R | grep -v '/$' | sort > ../old -% cd ../foo-9.9 -% find . -type f | cut -c 3- | sort > ../new -.... -+ -With these two files, the following command will list removed files (files only in [.filename]#old#): -+ -[source,bash] -.... -% comm -23 ../old ../new -.... -+ -While the command below will list added files (files only in [.filename]#new#): -+ -[source,bash] -.... -% comm -13 ../old ../new -.... -+ -Let us put this together: -+ -[source,bash] -.... -% cd vendor/foo/foo-9.9 -% tar cf - . | tar xf - -C ../dist -% cd ../dist -% comm -23 ../old ../new | xargs svn remove -% comm -13 ../old ../new | xargs svn add -.... -+ -[WARNING] -==== -If there are new directories in the new distribution, the last command will fail. -You will have to add the directories, and run it again. -Conversely, if any directories were removed, you will have to remove them manually. -==== -+ -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 `*`. -** There should be no other properties on any file in the tree. -+ -[NOTE] -==== -You are ready to commit, but you should first check the output of `svn stat` and `svn diff` to make sure everything is in order. -==== -+ -Once you have committed the new vendor release, you should tag it for future reference. -The best and quickest way is to do it directly in the repository: -+ -[source,bash] -.... -% svn copy ^/vendor/foo/dist svn_base/vendor/foo/9.9 -.... -+ -To get the new tag, you can update your working copy of [.filename]#vendor/foo#. -+ -[NOTE] -==== -If you choose to do the copy in the checkout instead, do not forget to remove the generated `svn:mergeinfo` as described above. -==== +[[vendor-import]] +=== Vendor Imports -. *Merging to __-HEAD__* -+ -After you have prepared your import, it is time to merge. -Option `--accept=postpone` tells SVN not to handle merge conflicts yet, because they will be taken care of manually: -+ -[source,bash] -.... -% cd head/contrib/foo -% svn update -% svn merge --accept=postpone ^/vendor/foo/dist -.... -+ -Resolve any conflicts, and make sure that any files that were added or removed in the vendor tree have been properly added or removed in the main tree. It is always a good idea to check differences against the vendor branch: -+ -[source,bash] -.... -% svn diff --no-diff-deleted --old=^/vendor/foo/dist --new=. -.... -+ -`--no-diff-deleted` tells SVN not to check files that are in the vendor tree but not in the main tree. -+ -[NOTE] -==== -With SVN, there is no concept of on or off the vendor branch. -If a file that previously had local modifications no longer does, just remove any left-over cruft, such as FreeBSD version tags, -so it no longer shows up in diffs against the vendor tree. -==== -+ -If any changes are required for the world to build with the new sources, make them now - and test until you are satisfied that everything build and runs correctly. -. *Commit* -+ -Now, you are ready to commit. -Make sure you get everything in one go. -Ideally, you would have done all steps in a clean tree, in which case you can just commit from the top of that tree. -That is the best way to avoid surprises. -If you do it properly, the tree will move atomically from a consistent state with the old code to a consistent state with the new code. +The standard process for managing contributed software and vendor branches is described in detail by the extref:{committers-guide}#vendor-import-git[Committer's Guide]. [[policies-encumbered]] == Encumbered Files