From nobody Fri Oct 20 15:16:18 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 4SBp823rNkz4xtbs for ; Fri, 20 Oct 2023 15:16:18 +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 4SBp823Pghz4ssR; Fri, 20 Oct 2023 15:16:18 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1697814978; 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=hw048/rqVvENLkgj3SPPTNt5TSeMLsvS+Y8NT3WXvPA=; b=g8V9RypgYWTOaABagrdkO49YDNEcp7FJOlfMg6SH3xnzy6sf+Hk+QxKNGzaWmwLAoEBJH/ Tb3kkzm25qbJaUFvIZtOBtWYzdNbGIJDjelCLae7aUzr+obe6T3nSzEJuvgagcaHUiKA+g 9+99SxnpJbqxdYEHxnYAyj5NgOS9NQHOuItbBx7GQvQ1PHdqbq3Bx4gA2UR668irPbMX2+ ERL2DbE+6Kh7txZ+wLmrjIAW4jfHhBeoA++p+ZTaX0pPYNmQdg6cb4boPxzth0FjSbaWR1 +KyrXouYSMStAaBE1mk6r5J78cinJt5sXxKJ6pRyOE0J8Xpz7y3WvDrb1aNhig== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1697814978; a=rsa-sha256; cv=none; b=S1i7yh9HjW5oTey5vONrLi75Nh3zIQm/8D9vsK6kySwb6vAXrv7DpifONN8s9YDDvS/+OB Bb5Phc9CYTbcZSG/pqvc1hFChmX7FR+SRdikU/A9KxkMR4CgAW5ObSR4DzmYybQPl8QE4b roIQM7rP1NnNruxfidbItHSHuFGGtFzf7DSE8q1ODNCdctwObdh4RN4aBwhyyUSzfhaavL +XZ5jppgWC3W840sCAZwOyVyLFGW8KpFXuidw0MDuuAySORbmwWSmMvxak0l5OiuXPbfR8 lXVela33T/F9+OXb+bOs9bfniDRp+2c83aa/UJUGdbE+oWgzkRLgrreIYhoi8Q== 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=1697814978; 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=hw048/rqVvENLkgj3SPPTNt5TSeMLsvS+Y8NT3WXvPA=; b=XK074r/8QrZmO0WdwiPxOnBOpIQGTm6I94X6pW89XP2RcORe+MMOoh6mPDh8yFcrWvNT6a 2T9k6jg0zIaM5l5ZMcYCimFu7ZH9dRDia3y2Kvgfn5iMlTeUVmk9pYqX4nZav6D7hMT7V1 aiySWA0BP+H7S/v+smaD0I/k/xUxbHOHpZoKZNk0NpTGDunQfmtbYfURYNAHBZzaG8TXQ6 psdX34/G1YMpqaMlGw7Qd0VYw73J6vsIkTX78GUGZVS0boDO0Fm9Yb2jELmjXUTpKHpMVt E/oLhMFcNI+pgBeX+y9dIsyFp3EX2nPH06GXS2RCdj9lc2CyugvMG5WhRMvDsw== 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 4SBp822VKSzdGj; Fri, 20 Oct 2023 15:16:18 +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 39KFGIJD055209; Fri, 20 Oct 2023 15:16:18 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 39KFGIAM055206; Fri, 20 Oct 2023 15:16:18 GMT (envelope-from git) Date: Fri, 20 Oct 2023 15:16:18 GMT Message-Id: <202310201516.39KFGIAM055206@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Mitchell Horne Subject: git: 7e775c6d1a - main - dev-handbook: update description of contrib software 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: 7e775c6d1a9f5629bcb8a54cf0e70b53b1aca7de Auto-Submitted: auto-generated The branch main has been updated by mhorne: URL: https://cgit.FreeBSD.org/doc/commit/?id=7e775c6d1a9f5629bcb8a54cf0e70b53b1aca7de commit 7e775c6d1a9f5629bcb8a54cf0e70b53b1aca7de Author: Mitchell Horne AuthorDate: 2023-10-20 15:14:38 +0000 Commit: Mitchell Horne CommitDate: 2023-10-20 15:15:56 +0000 dev-handbook: update description of contrib software The existing description reflects a time when the process for managing contrib software was less standardized. Provide a brief description of how we manage vendor branches, with some conventions. Reviewed by: carlavilla, imp, emaste Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D42302 --- .../en/books/developers-handbook/policies/_index.adoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/documentation/content/en/books/developers-handbook/policies/_index.adoc b/documentation/content/en/books/developers-handbook/policies/_index.adoc index 93a034458c..cbd8707022 100644 --- a/documentation/content/en/books/developers-handbook/policies/_index.adoc +++ b/documentation/content/en/books/developers-handbook/policies/_index.adoc @@ -87,18 +87,18 @@ The role of the maintainer is as follows: Some parts of the FreeBSD distribution consist of software that is actively being maintained outside the FreeBSD project. For historical reasons, we call this _contributed_ software. -Some examples are sendmail, gcc and patch. +Some examples are LLVM, man:zlib[3], and man:awk[1]. -Over the last couple of years, various methods have been used in dealing with this type of software and all have some number of advantages and drawbacks. -No clear winner has emerged. +The accepted procedure for managing contributed software involves creating a _vendor branch_, where the software can be imported cleanly (without modification) and updates can be tracked in a versioned manner. +Then, the content of the vendor branch is applied to the source tree, possibly with local modifications. +FreeBSD-specific build glue is maintained in the source tree, not in the vendor branch. -Since this is the case, after some debate one of these methods has been selected as the "official" method and will be required for future imports of software of this kind. -Furthermore, it is strongly suggested that existing contributed software converge on this model over time, as it has significant advantages over the old method, including the ability to easily obtain diffs relative to the "official" versions of the source by everyone (even without direct repository access). -This will make it significantly easier to return changes to the primary developers of the contributed software. +Depending on their needs and complexity, individual software projects may deviate from this procedure, at the discretion of the maintainer. +The exact steps required to update a particular piece of contributed software should be recorded in a file named `FREEBSD-upgrade`; +for example, link:https://cgit.freebsd.org/src/tree/contrib/libarchive/FREEBSD-upgrade[libarchive's FREEBSD-upgrade file]. -Ultimately, however, it comes down to the people actually doing the work. -If using this model is particularly unsuited to the package being dealt with, exceptions to these rules may be granted only with the approval of the core team and with the general consensus of the other developers. -The ability to maintain the package in the future will be a key issue in the decisions. +Contributed software is usually placed in the [.filepath]#contrib/# subdirectory of the source tree, with some exceptions. +Contributed software used only by the kernel lives under [.filepath]#sys/contrib/#. [NOTE] ====