From nobody Sun Nov 01 00:40:34 2026 X-Original-To: dev-commits-src-main@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 4jHGGB2ssyz6xhDt for ; Sun, 01 Nov 2026 00:40:34 +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) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 4jHGGB1mnRz3Nv5 for ; Sun, 01 Nov 2026 00:40:34 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1793493634; 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=1n+UfoclOFml3OtDOlitA9P/zypGVibrDx8N9r3s0rQ=; b=BBiQAEUQa38slpbpTp7k08KmqtsWVVuULnD81qysExS9NPlnblYVa7ixG1EvRyEDH8AqJu Kbjt4UZlB6KQ5vhYvuY9zRxsd6OoKS/k71l2z3ezYkGN/El96Lon+UqioVpYmISFyhLgbk BKSGeP6DC2RWPM3hFwDqU8CLCJGP1Ob3GyRrWFr7Oo7FOh2rrc1HOi2sqAVX0JCUXH1nUw WZsKrf1LAu+ZBv45WF87S6ebPs6VlVPHSoGjT09cbenFzYDIHMsokbUbRsi3A49KDn1/Mr UWvFMukaIvev+JmW7RSEUenEJI/2cbyVUJnF5xYRXw4Ym5J4XpyJc00oWAf5Ew== ARC-Seal: i=1; a=rsa-sha256; d=freebsd.org; s=dkim; cv=none; t=1793493634; b=NHZSwJ8Wa4J9ZSXTwY2BrXZEhu7n/bnN3mXFzXUIybu2sIdbEpKCVcdt1N2DRkYUDlte27 rSryv1VMBkrhtKKECKEOLXQ0Oktcl+lhO2jjmmTxygiy2vOqTDmp6MzLlYsg2fJCJ8phrM FEuuhb4wtsxgbDxjifItmvJ8RCV5OB6aMn/gDJnRTXrD94EbsIhVvbiASnCLyBYYtr4lsq 8ssjBe0Ch/HwCH3GWqFyYrILwaQz9Kiv5+Mj2HDg0ixSad7bjgC9Pc4xTJKwbYHIuhq3+i of9zQvxg6jYRGl7rOikjy3a/k5YP5Maw0tsZbKVmlVfCUip0scGxVxVfc96l3A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1793493634; 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=1n+UfoclOFml3OtDOlitA9P/zypGVibrDx8N9r3s0rQ=; b=S1kpkKdO0ny26WFSCx+cFFQUBUGw1JnTDPZXkmNtO+PE8lptRkPG9+aVBcN53DXZs7y7fg yD7RVYOWl1GpXpuvZyJe9WjoiBbfc2fFC6Z5nuNIvljFgxczyw5KGd//YjVq2GAHJtYxn3 VGmyZiC1cHPyvhsQYVUex3Rl1K4ukYv4WSRJj7vNuwLY0Ljprx2IDR50kTZBvlV5jI3tKZ qCFXKxEpZduVFbGkJ7ILk1KUrMrdu6+Y1OIY9WtL/JwTmZBiWRInrmp3iCfU2rAoHM241a yl5tF8BwsMtpoIIkiCsgE+ecE69xVWoP1t1lfOgEI22eKKEhHmJOXNvIwI0Orw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4jHGGB18g7zcF1 for ; Sun, 01 Nov 2026 00:40:34 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 1f7be by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Sun, 01 Nov 2026 00:40:34 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Enji Cooper Subject: git: 91fcc2d8b18c - main - atf/FREEBSD-upgrade: update document/rewrite in Markdown List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main X-BeenThere: dev-commits-src-main@freebsd.org Sender: owner-dev-commits-src-main@FreeBSD.org List-Id: Commit messages for the main branch of the src repository List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: ngie X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 91fcc2d8b18c61b61a1fd5848acecc0adfb17403 Auto-Submitted: auto-generated Date: Sun, 01 Nov 2026 00:40:34 +0000 Message-Id: <6ae68a82.1f7be.538c866a@gitrepo.freebsd.org> The branch main has been updated by ngie: URL: https://cgit.FreeBSD.org/src/commit/?id=91fcc2d8b18c61b61a1fd5848acecc0adfb17403 commit 91fcc2d8b18c61b61a1fd5848acecc0adfb17403 Author: Enji Cooper AuthorDate: 2026-11-01 00:40:01 +0000 Commit: Enji Cooper CommitDate: 2026-11-01 00:40:27 +0000 atf/FREEBSD-upgrade: update document/rewrite in Markdown The document does not reflect current reality with how updates/releases should be managed with contrib/atf . Update it to a state that better reflects current practices with git, as well as information about where the latest version of the project can be found, etc. This change will be used as a template for adding instructions on how to update contrib/kyua and contrib/lutok in future commits. MFC after: 1 month Reviewed by: ziaee, carlavilla Differential Revision: https://reviews.freebsd.org/D59879 --- contrib/atf/FREEBSD-upgrade | 113 +++++++++++++++++++++++++++++++------------- 1 file changed, 81 insertions(+), 32 deletions(-) diff --git a/contrib/atf/FREEBSD-upgrade b/contrib/atf/FREEBSD-upgrade index 4959b1e95de1..9a8cc5d84814 100644 --- a/contrib/atf/FREEBSD-upgrade +++ b/contrib/atf/FREEBSD-upgrade @@ -1,45 +1,94 @@ -This document contains a collection of notes specific to the import -of atf into head. These notes are built on the instructions in -the FreeBSD Subversion Primer that detail how to deal with vendor -branches and you are supposed to follow those: +# atf - http://www.freebsd.org/doc/en/articles/committers-guide/subversion-primer.html +## Introduction -The ATF source code is hosted on GitHub: +This document contains a collection of notes specific to the import of atf into +`:main`. These notes are loosely based on instructions available in the +[FreeBSD Committer's Guide][vendor-import-git-page]. - https://github.com/jmmv/atf +[vendor-import-git-page]: https://docs.freebsd.org/en/articles/committers-guide/#vendor-import-git -and is imported into the atf vendor branch (see base/vendor/atf/). +## Project Release Information -To merge the vendor branch into head do something like this: +The ATF source code is hosted on [GitHub][github-project-page]. See the +[project releases][github-project-releases] page for the latest release. - cd .../base/head/contrib/atf - svn merge --accept=postpone \ - svn+ssh://svn.freebsd.org/base/vendor/atf/dist . - svn remove --force $(cat FREEBSD-Xlist) +[github-project-releases]: https://github.com/freebsd/atf/releases -and resolve any conflicts that may arise at this point. +## Importing New Releases Into the Vendor Branch -Once this is done, you must regenerate bconfig.h. The recommended way -of doing so is by using the release files already imported into the -vendor branch (which is a good justification for importing the verbatim -sources in the first place so that this step is reproducible). You can -use a set of commands similar to the following: +The latest ATF version is imported into the vendor branch, [vendor/atf][vendor-atf-branch]. - mkdir /tmp/atf - cd /tmp/atf - .../vendor/atf/dist/configure \ - --prefix=/ \ - --exec-prefix=/usr \ - --datarootdir=/usr/share - cp bconfig.h .../base/head/contrib/atf/ +[vendor-atf-branch]: https://cgit.freebsd.org/src/tree/?h=vendor/atf -Please do NOT run './configure' straight from the 'dist' directory of -the vendor branch as you easily risk committing build products into the +## Preparing the Sources for Commit + +### The "Merge From Vendor" (MFV) Process + +To merge the vendor branch into head, do something like this: + +``` +% cd "${SRCTOP}/contrib/atf" +% git subtree merge -P contrib/atf freebsd/vendor/atf/ +% git rm --force $(cat FREEBSD-Xlist) +``` +Resolve any conflicts that may arise after running `git rm`. + +### Regenerating Generated Files + +Once the initial MFV is done, all generated files (headers, manpages) must be +regenerated and committed to the source tree. The recommended way of doing so +is by using the release files already imported into the vendor branch, where +possible. You can use a set of commands similar to the following: + +``` +% mkdir /tmp/atf +% cd /tmp/atf +% .../vendor/atf/dist/configure \ + --prefix=/ \ + --exec-prefix=/usr \ + --datarootdir=/usr/share +% gmake all +% for infile in config.h.in "$(find doc -name "*.in")"; do \ + cp "${infile%.in}" .../"base/head/contrib/atf/${infile%/*}"; \ + done +``` +Please do NOT run './configure' straight from the `dist` directory of the +vendor branch: this risks introducing unwanted build products into the source tree. -Lastly, with the list of old and new files in this import, make sure -to update the reachover Makefiles accordingly. +### Updating Makefiles + +Finally, make sure to update the reachover Makefiles accordingly. Here are some +directories/ and `Makefile`s of interest at time of writing: + +- `lib/atf/` +- `libexec/atf/` +- `share/examples/atf/` +- `share/man/man7/Makefile` + +## Pruning Unnecessary Files + +Files and directories under `contrib/atf` were pruned using the following +example command: + +``` +% cd "${SRCTOP}/contrib/atf" +% sh -c 'for F in `grep -v FreeBSD FREEBSD-Xlist`; do rm -Rf ./${F} ; done' +``` + +## Contributing Changes + +To make local changes to atf, simply commit the changes to the `:main` +branch. Never make local changes on the vendor branch which have not already +been merged into the upstream source repository! + +Please contribute back to the [GitHub project][github-project-page] to ease +future release updates. + +## Testing Changes + +Test the build (keeping in mind the `WITH_TESTS`/`WITHOUT_TESTS` build knobs). +If all looks good, you are ready to commit! -Test the build (keeping in mind the WITH_TESTS/WITHOUT_TESTS knobs) and, -if all looks good, you are ready to commit all the changes in one go. +[github-project-page]: https://github.com/freebsd/atf/