Date: Tue, 6 Apr 2021 19:11:02 GMT From: Rene Ladan <rene@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: be5f234b0c - main - Porters Handbook: convert most instructions to git Message-ID: <202104061911.136JB2QD091749@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by rene: URL: https://cgit.FreeBSD.org/doc/commit/?id=be5f234b0ccfbc05b6d112e51cdf95686a0ee43e commit be5f234b0ccfbc05b6d112e51cdf95686a0ee43e Author: Rene Ladan <rene@FreeBSD.org> AuthorDate: 2021-04-06 19:09:41 +0000 Commit: Rene Ladan <rene@FreeBSD.org> CommitDate: 2021-04-06 19:09:41 +0000 Porters Handbook: convert most instructions to git - mention cgit instead of svnweb - remove the $FreeBSD$ identifier from the example Makefile, git does not expand keywords. - update instructions to create a diff - update instructions to set up poudriere jails ad ports trees. Reviewed by: emaste, mat Differential Revision: https://reviews.freebsd.org/D29450 --- .../books/porters-handbook/keeping-up/_index.adoc | 4 +- .../books/porters-handbook/makefiles/_index.adoc | 2 +- .../en/books/porters-handbook/order/_index.adoc | 14 ----- .../porters-handbook/porting-samplem/_index.adoc | 5 -- .../porters-handbook/quick-porting/_index.adoc | 11 ++-- .../porters-handbook/slow-porting/_index.adoc | 2 - .../en/books/porters-handbook/special/_index.adoc | 2 +- .../en/books/porters-handbook/testing/_index.adoc | 14 ++--- .../books/porters-handbook/upgrading/_index.adoc | 62 ++++++++-------------- 9 files changed, 36 insertions(+), 80 deletions(-) diff --git a/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc b/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc index b95cd8488b..ea01a72767 100644 --- a/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc +++ b/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc @@ -40,10 +40,10 @@ To use FreshPorts, an account is required. Those with registered email addresses FreshPorts also has a sanity test feature which automatically tests each commit to the FreeBSD ports tree. If subscribed to this service, a committer will receive notifications of any errors which FreshPorts detects during sanity testing of their commits. -[[svnweb]] +[[cgit]] == The Web Interface to the Source Repository -It is possible to browse the files in the source repository by using a web interface. Changes that affect the entire port system are now documented in the http://svnweb.FreeBSD.org/ports/head/CHANGES[CHANGES] file. Changes that affect individual ports are now documented in the http://svnweb.FreeBSD.org/ports/head/UPDATING[UPDATING] file. However, the definitive answer to any question is undoubtedly to read the source code of http://svnweb.FreeBSD.org/ports/head/Mk/bsd.port.mk[bsd.port.mk], and associated files. +It is possible to browse the files in the source repository by using a web interface. Changes that affect the entire port system are now documented in the https://cgit.freebsd.org/ports/tree/CHANGES[CHANGES] file. Changes that affect individual ports are now documented in the https://cgit.FreeBSD.org/ports/tree/UPDATING[UPDATING] file. However, the definitive answer to any question is undoubtedly to read the source code of https://cgit.FreeBSD.org/ports/tree/Mk/bsd.port.mk[bsd.port.mk], and associated files. [[ports-mailing-list]] == The FreeBSD Ports Mailing List diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc index f198adc83b..7b8b0ba0a4 100644 --- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc +++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc @@ -1149,7 +1149,7 @@ MASTER_SITES= ${MASTER_SITE_GNU} MASTER_SITE_SUBDIR= make .... -These values and variables are defined in https://svnweb.freebsd.org/ports/head/Mk/bsd.sites.mk?view=markup[Mk/bsd.sites.mk]. New entries are added often, so make sure to check the latest version of this file before submitting a port. +These values and variables are defined in https://cgit.freebsd.org/ports/tree/Mk/bsd.sites.mk[Mk/bsd.sites.mk]. New entries are added often, so make sure to check the latest version of this file before submitting a port. [TIP] ==== diff --git a/documentation/content/en/books/porters-handbook/order/_index.adoc b/documentation/content/en/books/porters-handbook/order/_index.adoc index ff8e404f44..0802c2e28a 100644 --- a/documentation/content/en/books/porters-handbook/order/_index.adoc +++ b/documentation/content/en/books/porters-handbook/order/_index.adoc @@ -31,20 +31,6 @@ toc::[] The first sections of the [.filename]#Makefile# must always come in the same order. This standard makes it so everyone can easily read any port without having to search for variables in a random order. -The first line of a [.filename]#Makefile# is always a comment containing the Subversion version control ID, followed by an empty line. In new ports, it looks like this: - -[.programlisting] -.... -# $FreeBSD$ -.... - -In existing ports, Subversion has expanded it to look like this: - -[.programlisting] -.... -# $FreeBSD: head/ports-mgmt/pkg/Makefile 437007 2017-03-26 21:25:47Z bapt $ -.... - [NOTE] ==== The sections and variables described here are mandatory in a ordinary port. In a slave port, many sections and variables can be skipped. diff --git a/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc b/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc index c835d0009b..0307f18a51 100644 --- a/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc +++ b/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc @@ -35,11 +35,6 @@ The format shown is the recommended one for ordering variables, empty lines betw [.programlisting] .... -# $FreeBSD$ -[ ^^^^^^^^^ This will be automatically replaced with RCS ID string by SVN -when it is committed to our repository. If upgrading a port, do not alter -this line back to "$FreeBSD$". SVN deals with it automatically.] - [section to describe the port itself and the master site - PORTNAME and PORTVERSION or the DISTVERSION* variables are always first, followed by CATEGORIES, and then MASTER_SITES, which can be followed diff --git a/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc index 27227a5b15..5f587c54e9 100644 --- a/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc +++ b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc @@ -57,8 +57,6 @@ The minimal [.filename]#Makefile# would look something like this: [.programlisting] .... -# $FreeBSD$ - PORTNAME= oneko DISTVERSION= 1.1b CATEGORIES= games @@ -70,7 +68,7 @@ COMMENT= Cat chasing a mouse all over the screen .include <bsd.port.mk> .... -Try to figure it out. Do not worry about the contents of the `$FreeBSD$` line, it will be filled in automatically by Subversion when the port is imported to our main ports tree. A more detailed example is shown in the crossref:porting-samplem[porting-samplem,sample Makefile] section. +Try to figure it out. A more detailed example is shown in the crossref:porting-samplem[porting-samplem,sample Makefile] section. [[porting-desc]] == Writing the Description Files @@ -232,13 +230,12 @@ Next, create a man:patch[1], file. Assuming the port is called `oneko` and is in .Creating a [.filename]#.diff# for a New Port [example] ==== -Add all the files with `svn add`. `cd` to the base of the ports tree so full paths to the changed files are included in the diff, then generate the diff with `svn diff`. For example: +Add all the files with `git add .`, then generate the diff with `git diff`. For example: [source,shell] .... -% svn add . -% cd ../.. -% svn diff games/oneko > oneko.diff +% git add . +% git diff --staged > oneko.diff .... [IMPORTANT] diff --git a/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc b/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc index 0df377f3d1..e1c17a32fe 100644 --- a/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc +++ b/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc @@ -147,8 +147,6 @@ When generating patches for new, added files, `-N` is used to tell man:diff[1] t % diff -u -N newfile.orig newfile > patch-pathname-newfile .... -Do not add `$FreeBSD$` RCS strings in patches. When patches are added to the Subversion repository with `svn add`, the `fbsd:nokeywords` property is set to `yes` automatically so keywords in the patch are not modified when committed. The property can be added manually with `svn propset fbsd:nokeywords yes _files..._`. - Using the recurse (`-r`) option to man:diff[1] to generate patches is fine, but please look at the resulting patches to make sure there is no unnecessary junk in there. In particular, diffs between two backup files, [.filename]##Makefile##s when the port uses `Imake` or GNU `configure`, etc., are unnecessary and have to be deleted. If it was necessary to edit [.filename]#configure.in# and run `autoconf` to regenerate `configure`, do not take the diffs of `configure` (it often grows to a few thousand lines!). Instead, define `USES=autoreconf` and take the diffs of [.filename]#configure.in#. [[slow-patch-automatic-replacements]] diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc index d01f331efa..10598628bd 100644 --- a/documentation/content/en/books/porters-handbook/special/_index.adoc +++ b/documentation/content/en/books/porters-handbook/special/_index.adoc @@ -2951,7 +2951,7 @@ The default value for `DATADIR` is [.filename]#${PREFIX}/share/${PORTNAME}#. It As for the choice of building Java ports from source or directly installing them from a binary distribution, there is no defined policy at the time of writing. However, people from the https://www.freebsd.org/java/[FreeBSD Java Project] encourage porters to have their ports built from source whenever it is a trivial task. -All the features that have been presented in this section are implemented in [.filename]#bsd.java.mk#. If the port needs more sophisticated Java support, please first have a look at the http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=log[bsd.java.mk Subversion log] as it usually takes some time to document the latest features. Then, if the needed support that is lacking would be beneficial to many other Java ports, feel free to discuss it on the freebsd-java. +All the features that have been presented in this section are implemented in [.filename]#bsd.java.mk#. If the port needs more sophisticated Java support, please first have a look at the https://cgit.FreeBSD.org/ports/tree/Mk/bsd.java.mk[bsd.java.mk Git log] as it usually takes some time to document the latest features. Then, if the needed support that is lacking would be beneficial to many other Java ports, feel free to discuss it on the freebsd-java. Although there is a `java` category for PRs, it refers to the JDK porting effort from the FreeBSD Java project. Therefore, submit the Java port in the `ports` category as for any other port, unless the issue is related to either a JDK implementation or [.filename]#bsd.java.mk#. diff --git a/documentation/content/en/books/porters-handbook/testing/_index.adoc b/documentation/content/en/books/porters-handbook/testing/_index.adoc index 8e4c910ed3..25901637df 100644 --- a/documentation/content/en/books/porters-handbook/testing/_index.adoc +++ b/documentation/content/en/books/porters-handbook/testing/_index.adoc @@ -203,7 +203,7 @@ Fetch a `11.4-RELEASE` for `amd64` from the FTP server given by `FREEBSD_HOST` i [source,shell] .... -# poudriere jail -c -j 11i386 -v stable/11 -a i386 -m svn+https +# poudriere jail -c -j 11i386 -v stable/11 -a i386 -m git+https .... Create `tank/poudriere/jails/11i386`, mount it on [.filename]#/poudriere/jails/11i386#, then check out the tip of the Subversion branch of `FreeBSD-11-STABLE` from `SVN_HOST` in [.filename]#poudriere.conf# into [.filename]#/poudriere/jails/11i386/usr/src#, then complete a `buildworld` and install it into [.filename]#/poudriere/jails/11i386#. @@ -215,7 +215,7 @@ If a specific Subversion revision is needed, append it to the version string. Fo [source,shell] .... -# poudriere jail -c -j 11i386 -v stable/11@123456 -a i386 -m svn+https +# poudriere jail -c -j 11i386 -v stable/11@123456 -a i386 -m git+https .... ==== @@ -231,7 +231,7 @@ To create a Poudriere jail for `14.0-CURRENT`: [source,shell] .... -# poudriere jail -c -j 13amd64 -v head -a amd64 -m svn+https +# poudriere jail -c -j 14amd64 -v main -a amd64 -m git+https .... In order to run a `14.0-CURRENT` Poudriere jail you must be running `14.0-CURRENT`. In general, newer kernels can build and run older jails. For instance, a `14.0-CURRENT` kernel can build and run a `11.4-STABLE` Poudriere jail if the `COMPAT_FREEBSD11` kernel option was compiled in (on by default in `14.0-CURRENT`[.filename]#GENERIC# kernel config). @@ -268,7 +268,7 @@ updates the specified jail to the latest version available. For FreeBSD releases [TIP] ==== -For jails employing a `svn+*` method, it is helpful to add `-J _NumberOfParallelBuildJobs_` to speed up the build by increasing the number of parallel compile jobs used. For example, if the building machine has 6 CPUs, use: +For jails employing a `git+*` method, it is helpful to add `-J _NumberOfParallelBuildJobs_` to speed up the build by increasing the number of parallel compile jobs used. For example, if the building machine has 6 CPUs, use: [source,shell] .... @@ -291,16 +291,16 @@ or [source,shell] .... -# poudriere ports -c -m svn+https +# poudriere ports -c -m git+https .... -These commands create `tank/poudriere/ports/default`, mount it on [.filename]#/poudriere/ports/default#, and populate it using either man:portsnap[8] or Subversion. Afterward it is included in the list of known ports trees: +These commands create `tank/poudriere/ports/default`, mount it on [.filename]#/poudriere/ports/default#, and populate it using Git, man:portsnap[8], or Subversion. Afterward it is included in the list of known ports trees: [source,shell] .... # poudriere ports -l PORTSTREE METHOD TIMESTAMP PATH -default svn+https 2020-07-20 04:23:56 /poudriere/ports/default +default git+https 2020-07-20 04:23:56 /poudriere/ports/default .... [NOTE] diff --git a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc index ed78762bfa..cff0c810d8 100644 --- a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc +++ b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc @@ -31,7 +31,7 @@ toc::[] When a port is not the most recent version available from the authors, update the local working copy of [.filename]#/usr/ports#. The port might have already been updated to the new version. -When working with more than a few ports, it will probably be easier to use Subversion to keep the whole ports collection up-to-date, as described in the link:{handbook}#ports-using/[Handbook]. This will have the added benefit of tracking all the port's dependencies. +When working with more than a few ports, it will probably be easier to use Git to keep the whole ports collection up-to-date, as described in the link:{handbook}#ports-using/[Handbook]. This will have the added benefit of tracking all the port's dependencies. The next step is to see if there is an update already pending. To do this, there are two options. There is a searchable interface to the https://bugs.freebsd.org/search/[FreeBSD Problem Report (PR) or bug database]. Select `Ports & Packages` in the `Product` multiple select menu, and enter the name of the port in the `Summary` field. @@ -48,18 +48,18 @@ To create a suitable `diff` for a single patch, copy the file that needs patchin % diff -u something.orig something > something.diff .... -Otherwise, either use the `svn diff` method (<<svn-diff>>) or copy the contents of the port to an entire different directory and use the result of the recursive man:diff[1] output of the new and old ports directories (for example, if the modified port directory is called [.filename]#superedit# and the original is in our tree as [.filename]#superedit.bak#, then save the result of `diff -ruN superedit.bak superedit`). Either unified or context diff is fine, but port committers generally prefer unified diffs. Note the use of the `-N` option-this is the accepted way to force diff to properly deal with the case of new files being added or old files being deleted. Before sending us the diff, please examine the output to make sure all the changes make sense. (In particular, make sure to first clean out the work directories with `make clean`). +Otherwise, either use the `git diff` method (<<git-diff>>) or copy the contents of the port to an entire different directory and use the result of the recursive man:diff[1] output of the new and old ports directories (for example, if the modified port directory is called [.filename]#superedit# and the original is in our tree as [.filename]#superedit.bak#, then save the result of `diff -ruN superedit.bak superedit`). Either unified or context diff is fine, but port committers generally prefer unified diffs. Note the use of the `-N` option-this is the accepted way to force diff to properly deal with the case of new files being added or old files being deleted. Before sending us the diff, please examine the output to make sure all the changes make sense. (In particular, make sure to first clean out the work directories with `make clean`). [NOTE] ==== -If some files have been added, copied, moved, or removed, add this information to the problem report so that the committer picking up the patch will know what man:svn[1] commands to run. +If some files have been added, copied, moved, or removed, add this information to the problem report so that the committer picking up the patch will know what man:git[1] commands to run. ==== To simplify common operations with patch files, use `make makepatch` as described in crossref:slow-porting[slow-patch,Patching]. Other tools exists, like [.filename]#/usr/ports/Tools/scripts/patchtool.py#. Before using it, please read [.filename]#/usr/ports/Tools/scripts/README.patchtool#. If the port is unmaintained, and you are actively using it, please consider volunteering to become its maintainer. FreeBSD has over 4000 ports without maintainers, and this is an area where more volunteers are always needed. (For a detailed description of the responsibilities of maintainers, refer to the section in the link:{developers-handbook}#POLICIES-MAINTAINER[Developer's Handbook].) -To submit the diff, use the https://bugs.freebsd.org/submit/[bug submit form] (product `Ports & Packages`, component `Individual Port(s)`). Always include the category with the port name, followed by colon, and brief descripton of the issue. Examples: `_category/portname_: _add FOO option_`; `_category/portname_: _Update to X.Y_`. Please mention any added or deleted files in the message, as they have to be explicitly specified to man:svn[1] when doing a commit. Do not compress or encode the diff. +To submit the diff, use the https://bugs.freebsd.org/submit/[bug submit form] (product `Ports & Packages`, component `Individual Port(s)`). Always include the category with the port name, followed by colon, and brief descripton of the issue. Examples: `_category/portname_: _add FOO option_`; `_category/portname_: _Update to X.Y_`. Please mention any added or deleted files in the message, as they have to be explicitly specified to man:git[1] when doing a commit. Do not compress or encode the diff. Before submitting the bug, review the link:{problem-reports}#pr-writing/[ Writing the problem report] section in the Problem Reports article. It contains far more information about how to write useful problem reports. @@ -70,76 +70,56 @@ If the upgrade is motivated by security concerns or a serious fault in the curre [NOTE] ==== -Please use man:diff[1] or `svn diff` to create updates to existing ports. Other formats include the whole file and make it impossible to see just what has changed. When diffs are not included, the entire update might be ignored. +Please use man:diff[1] or `git diff` to create updates to existing ports. Other formats include the whole file and make it impossible to see just what has changed. When diffs are not included, the entire update might be ignored. ==== Now that all of that is done, read about how to keep up-to-date in crossref:keeping-up[keeping-up,Keeping Up]. -[[svn-diff]] -== Using Subversion to Make Patches +[[git-diff]] +== Using Git to Make Patches -When possible, please submit a man:svn[1] diff. They are easier to handle than diffs between "new and old" directories. It is easier to see what has changed, and to update the diff if something was modified in the Ports Collection since the work on it began, or if the committer asks for something to be fixed. Also, a patch generated with `svn diff` can be easily applied with `svn patch` and will save some time to the committer. +When possible, please submit a man:git[1] diff. They are easier to handle than diffs between "new and old" directories. It is easier to see what has changed, and to update the diff if something was modified in the Ports Collection since the work on it began, or if the committer asks for something to be fixed. Also, a patch generated with `git diff` can be easily applied with `git apply` and will save some time to the committer. [source,shell] .... -% cd ~/my_wrkdir <.> -% svn co https://svn.FreeBSD.org/ports/head/dns/pdnsd <.> -% cd ~/my_wrkdir/pdnsd +% cd ~/my_ports_wrkdir <.> +% git clone https://cgit.FreeBSD.org/ports.git <.> +% cd ~/my_wrkdir/dns/pdnsd .... <.> This can be anywhere, of course. Building ports is not limited to within [.filename]#/usr/ports/#. -<.> https://svn.FreeBSD.org/[svn.FreeBSD.org] is the FreeBSD public Subversion server. See link:{handbook}#svn-mirrors[Subversion mirror sites] for more information. +<.> https://cgit.FreeBSD.org/[cgit.FreeBSD.org] is the FreeBSD public Git server. See link:{handbook}#svn-mirrors[Subversion mirror sites] for more information. -While in the port directory, make any changes that are needed. If adding, copying, moving, or removing a file, use `svn` to track these changes: +While in the port directory, make any changes that are needed. If adding, moving, or removing a file, use `git` to track these changes: [source,shell] .... -% svn add new_file -% svn copy some_file file_copy -% svn move old_name new_name -% svn remove deleted_file +% git add new_file +% git mv old_name new_name +% git rm deleted_file .... Make sure to check the port using the checklist in crossref:quick-porting[porting-testing,Testing the Port] and crossref:quick-porting[porting-portlint,Checking the Port with `portlint`]. [source,shell] .... -% svn status -% svn update <.> +% git status --short +% git pull --rebase <.> .... -<.> This will attempt to merge the differences between the patch and current repository version. Watch the output carefully. The letter in front of each file name indicates what was done with it. See <<table-svn-up>> for a complete list. - -[[table-svn-up]] -.Subversion Update File Prefixes -[cols="10%,90%", frame="none"] -|=== -|U -|The file was updated without problems. - -|G -|The file was updated without problems (only when working against a remote repository). - -|M -|The file had been modified, and was merged without conflicts. - -|C -|The file had been modified, and was merged with conflicts. -|=== - -If `C` is displayed as a result of `svn update`, it means something changed in the Subversion repository and man:svn[1] was not able to merge the local changes with those from the repository. It is always a good idea to inspect the changes anyway, since man:svn[1] does not know anything about the structure of a port, so it might (and probably will) merge things that do not make sense. +<.> This will attempt to merge the differences between the patch and current repository version. Watch the output carefully. The letter in front of each file name indicates what was done with it. The last step is to make a unified man:diff[1] of the changes: [source,shell] .... -% svn diff > ../`make -VPKGNAME`.diff +% git diff . > ../`make -VPKGNAME`.diff .... [NOTE] ==== -If files have been added, copied, moved, or removed, include the man:svn[1] `add`, `copy`, `move`, and `remove` commands that were used. `svn move` or `svn copy` must be run before the patch can be applied. `svn add` or `svn remove` must be run after the patch is applied. +If files have been added, moved, or removed, include the man:git[1] `add`, `mv`, and `rm` commands that were used. `git mv` must be run before the patch can be applied. `git add` or `git rm` must be run after the patch is applied. ==== Send the patch following the link:{problem-reports}#pr-writing/[problem report submission guidelines].
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202104061911.136JB2QD091749>