Date: Tue, 6 Apr 2021 19:10:59 GMT From: Rene Ladan <rene@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 3c9ef247f5 - main - Committers Guide: update the ports-specific sections to git. Message-ID: <202104061910.136JAxtv091666@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=3c9ef247f5ccea4a478670780aba89367a865c28 commit 3c9ef247f5ccea4a478670780aba89367a865c28 Author: Rene Ladan <rene@FreeBSD.org> AuthorDate: 2021-04-06 18:53:12 +0000 Commit: Rene Ladan <rene@FreeBSD.org> CommitDate: 2021-04-06 18:53:12 +0000 Committers Guide: update the ports-specific sections to git. - Remove notes that the migration is in progress - Remove old branch names and URLs - Remove mention of psvn - Remove section about re-adding a deleted port, git add will do the right thingn natively (most of the times). - Remove section about repo-copies, git has no copy command. - Simplify instructions for moving a port. - Remove section about the mfh tool. Merges are now just cherry-picks. Reviewed by: crees, emaste, imp, lwhsu, mat Differential Revision: https://reviews.freebsd.org/D29450 --- .../en/articles/committers-guide/_index.adoc | 239 +++------------------ 1 file changed, 26 insertions(+), 213 deletions(-) diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index e9ea2cb9c3..36f3f52baa 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -61,8 +61,8 @@ toc::[] |`_doc/_` Git Repository |`ssh://git@gitrepo.FreeBSD.org/doc.git` (see also <<git-getting-started-doc-layout>>). -|`_ports/_` Subversion Root -|`svn+ssh://repo.FreeBSD.org/ports` (see also <<svn-getting-started-ports-layout>>). +|`_ports/_` Git Repository +|`ssh://git@gitrepo.FreeBSD.org/ports.git` (see also <<git-getting-started-ports-layout>>). |_Internal Mailing Lists_ |developers (technically called all-developers), doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (Each project repository has its own -developers and -committers mailing lists. Archives for these lists can be found in the files [.filename]#/local/mail/repository-name-developers-archive# and [.filename]#/local/mail/repository-name-committers-archive# on the `FreeBSD.org` cluster.) @@ -463,22 +463,14 @@ When you are done, report the bad version to the developer (or fix the bug yours Again, the git-bisect manual (linked above) is a good resource for when things go wrong or for unusual cases. ==== Ports Considerations -The ports migration is in progress, and some of this section may change before that is complete. The ports tree operates the same way. The branch names are different and the repositories are in different locations. -The legacy GitHub mirror is at https://github.com/freebsd/freebsd-ports.git . -The canonical cgit mirror is https://cgit-beta.freebsd.org/ports.git . -The production git repo will be https://git.freebsd.org/ports.git and ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git) when the time comes. +The cgit repository web interface for use with web browsers is at https://cgit.freebsd.org/ports.git . +The production git repository is at https://git.freebsd.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git). -The 'current' branches are 'master' (legacy) and 'main' (new) respectively. -The quarterly branches are named the same as in FreeBSD's svn repo. - -[NOTE] -==== -The cgit repo for ports is considered beta. -The git hashes may change as problems are found in the conversion prior to the cutover. -==== +The 'current' branch is 'main' . +The quarterly branches are named 'yyyyQn' for year 'yyyy' and quarter 'n'. ==== Managing Local Changes This section addresses tracking local changes. @@ -2157,17 +2149,17 @@ A few noteworthy directories are: LANG above is the two character language code. All document source is encoded using Unicode. -[[svn-getting-started-ports-layout]] +[[git-getting-started-ports-layout]] ==== FreeBSD Ports Tree Branches and Layout -In `svn+ssh://repo.freebsd.org/ports`, _ports_ refers to the repository root of the ports tree. +In `ssh://gitrepo.freebsd.org/ports.git`, _ports_ refers to the repository root of the ports tree. -In general, most FreeBSD port work will be done within the [.filename]#head/# branch of the ports tree which is the actual ports tree used to install software. +In general, most FreeBSD port work will be done within the `main` branch of the ports tree which is the actual ports tree used to install software. Some other key locations are: -* /branches/RELENG_n_n_n which corresponds to `RELENG_n_n_n` is used to merge back security updates in preparation for a release. -* /tags/RELEASE_n_n_n which corresponds to `RELEASE_n_n_n` represents a release tag of the ports tree. -* /tags/RELEASE_n_EOL represents the end of life tag of a specific FreeBSD branch. +* `yyyyQn` (a branch), where `yyyy` represents the current year and `n` represents the current quarter (e.g. 2021Q2), which receives mostly security and bugfixes. +* release/`x.y.z` (a tag), which represents a release tag of the ports tree. +* `n`-eol (a tag), which represents the end of life tag of FreeBSD branch `n.X`. [[svn-daily-use]] === Daily Use @@ -2299,13 +2291,6 @@ To commit all changes in, for example, [.filename]#lib/libfetch/# and [.filename % svn commit lib/libfetch usr/bin/fetch .... -There is also a commit wrapper for the ports tree to handle the properties and sanity checking the changes: - -[source,shell] -.... -% /usr/ports/Tools/scripts/psvn commit -.... - [[svn-daily-use-adding-and-removing]] ==== Adding and Removing Files @@ -4142,7 +4127,7 @@ When using Git, consider using `git grep`, it is much faster than `grep -r`. + [.procedure] ==== -* Remove the port's files and directory with `svn remove`. +* Remove the port's files and directory with `git rm`. * Remove the `SUBDIR` listing of the port in the parent directory [.filename]#Makefile#. * Add an entry to [.filename]#ports/MOVED#. * Search for entries in [.filename]#ports/security/vuxml/vuln.xml# and adjust them accordingly. In particular, check for previous packages with the new name which version could include the new port. @@ -4153,99 +4138,16 @@ Alternatively, you can use the rmport script, from [.filename]#ports/Tools/scrip This script was written by {vd}. When sending questions about this script to the {freebsd-ports}, please also CC {crees}, the current maintainer. -[[ports-qa-re-adding]] -=== Re-adding a Deleted Port - -[[ports-qa-resurrect]] -==== How do I re-add a deleted port? - -This is essentially the reverse of deleting a port. - -[IMPORTANT] -==== -Do not use `svn add` to add the port. -Follow these steps. -If they are unclear, or are not working, ask for help, do not just `svn add` the port. -==== +[[ports-qa-move-port]] +=== How do I move a port to a new location? [.procedure] ==== -. Figure out when the port was removed. Use this link:https://people.freebsd.org/~crees/removed_ports/index.xml[list], or look for the port on link:http://www.freshports.org/[freshports], and then copy the last living revision of the port: -+ -[source,shell] -.... -% cd /usr/ports/category -% svn cp 'svn+ssh://repo.freebsd.org/ports/head/category/portname/@XXXXXX' portname -.... -+ -Pick the revision that is just before the removal. For example, if the revision where it was removed is 269874, use 269873. -+ -It is also possible to specify a date. In that case, pick a date that is before the removal but after the last commit to the port. -+ -[source,shell] -.... -% cd /usr/ports/category -% svn cp 'svn+ssh://repo.freebsd.org/ports/head/category/portname/@{YYYY-MM-DD}' portname -.... -+ -. Make the changes necessary to get the port working again. If it was deleted because the distfiles are no longer available, either volunteer to host the distfiles, or find someone else to do so. -. If some files have been added, or were removed during the resurrection process, use `svn add` or `svn remove` to make sure all the files in the port will be committed. -. Restore the `SUBDIR` listing of the port in the parent directory [.filename]#Makefile#, keeping the entries sorted. -. Delete the port entry from [.filename]#ports/MOVED#. -. If the port had an entry in [.filename]#ports/LEGAL#, restore it. -. `svn commit` these changes, preferably in one step. -==== - -[TIP] -==== -The `addport` script mentioned in <<ports-qa-adding>> now detects when the port to add has previously existed, and attempts to handle all except the `ports/LEGAL` step automatically. -==== - -[[ports-qa-repocopies]] -=== Repository Copies - -[[ports-qa-repocopy-when]] -==== When do we need a repository copy? - -When you want to add a port that is related to any port that is already in the tree in a separate directory, you have to do a repository copy. -Here related means it is a different version or a slightly modified version. -Examples are [.filename]#print/ghostscript*# (different versions) and [.filename]#x11-wm/windowmaker*# (English-only and internationalized version). - -Another example is when a port is moved from one subdirectory to another, or when the name of a directory must be changed because the authors renamed their software even though it is a descendant of a port already in a tree. - -[[ports-qa-repocopy-how]] -==== What do I need to do? - -With Subversion, a repo copy can be done by any committer: - -* Doing a repo copy: - -[.procedure] -==== -. Verify that the target directory does not exist. -. Use `svn up` to make certain the original files, directories, and checkout information is current. -. Use `svn move` or `svn copy` to do the repo copy. -. Upgrade the copied port to the new version. Remember to add or change the `PKGNAMEPREFIX` or `PKGNAMESUFFIX` so there are no duplicate ports with the same name. In some rare cases it may be necessary to change the `PORTNAME` instead of adding `PKGNAMEPREFIX` or `PKGNAMESUFFIX`, but this is only done when it is really needed — for example, using an existing port as the base for a very similar program with a different name, or upgrading a port to a new upstream version which actually changes the distribution name, like the transition from [.filename]#textproc/libxml# to [.filename]#textproc/libxml2#. In most cases, adding or changing `PKGNAMEPREFIX` or `PKGNAMESUFFIX` suffices. -. Add the new subdirectory to the `SUBDIR` listing in the parent directory [.filename]#Makefile#. You can run make checksubdirs in the parent directory to check this. -. If the port changed categories, modify the CATEGORIES line of the port's [.filename]#Makefile# accordingly -. Add an entry to [.filename]#ports/MOVED#, if you remove the original port. -. Commit all changes on one commit. -==== - -* When removing a port: - -[.procedure] -==== -. Perform a thorough check of the ports collection for any dependencies on the old port location/name, and update them. Running `grep` on [.filename]#INDEX# is not enough because some ports have dependencies enabled by compile-time options. A full `grep -r` of the ports collection is recommended. -. Remove the old port and the old `SUBDIR` entry. +. Perform a thorough check of the ports collection for any dependencies on the old port location/name, and update them. Running `grep` on [.filename]#INDEX# is not enough because some ports have dependencies enabled by compile-time options. A full `git grep` of the ports collection is recommended. +. Remove the `SUBDIR` entry from the old category Makefile and add a `SUBDIR` entry to the new category Makefile. . Add an entry to [.filename]#ports/MOVED#. -==== - -* After repo moves (“rename” operations where a port is copied and the old location is removed): - -[.procedure] -==== -* Follow the same steps that are outlined in the previous two entries, to activate the new location of the port and remove the old one. +. Move the port with `git mv`. +. Commit the changes. ==== [[ports-qa-freeze]] @@ -4328,106 +4230,17 @@ Commits that are not covered by these blanket approvals always require explicit [[ports-qa-misc-commit-mfh]] ==== What is the procedure for merging commits to the quarterly branch? -A script is provided to automate merging a specific commit: [.filename]#ports/Tools/scripts/mfh#. It is used as follows: - -[source,shell] -.... -% /usr/ports/Tools/scripts/mfh 380362 - U 2015Q1 -Checked out revision 380443. -A 2015Q1/security -Updating '2015Q1/security/rubygem-sshkit': -A 2015Q1/security/rubygem-sshkit -A 2015Q1/security/rubygem-sshkit/Makefile -A 2015Q1/security/rubygem-sshkit/distinfo -A 2015Q1/security/rubygem-sshkit/pkg-descr -Updated to revision 380443. ---- Merging r380362 into '2015Q1': -U 2015Q1/security/rubygem-sshkit/Makefile -U 2015Q1/security/rubygem-sshkit/distinfo ---- Recording mergeinfo for merge of r380362 into '2015Q1': - U 2015Q1 ---- Recording mergeinfo for merge of r380362 into '2015Q1/security': - G 2015Q1/security ---- Eliding mergeinfo from '2015Q1/security': - U 2015Q1/security ---- Recording mergeinfo for merge of r380362 into '2015Q1/security/rubygem-sshkit': - G 2015Q1/security/rubygem-sshkit ---- Eliding mergeinfo from '2015Q1/security/rubygem-sshkit': - U 2015Q1/security/rubygem-sshkit - M 2015Q1 -M 2015Q1/security/rubygem-sshkit/Makefile -M 2015Q1/security/rubygem-sshkit/distinfo -Index: 2015Q1/security/rubygem-sshkit/Makefile -=================================================================== ---- 2015Q1/security/rubygem-sshkit/Makefile (revision 380443) -+++ 2015Q1/security/rubygem-sshkit/Makefile (working copy) -@@ -2,7 +2,7 @@ - # $FreeBSD$ - - PORTNAME= sshkit --PORTVERSION= 1.6.1 -+PORTVERSION= 1.7.0 - CATEGORIES= security rubygems - MASTER_SITES= RG - -Index: 2015Q1/security/rubygem-sshkit/distinfo -=================================================================== ---- 2015Q1/security/rubygem-sshkit/distinfo (revision 380443) -+++ 2015Q1/security/rubygem-sshkit/distinfo (working copy) -@@ -1,2 +1,2 @@ --SHA256 (rubygem/sshkit-1.6.1.gem) = 8ca67e46bb4ea50fdb0553cda77552f3e41b17a5aa919877d93875dfa22c03a7 --SIZE (rubygem/sshkit-1.6.1.gem) = 135680 -+SHA256 (rubygem/sshkit-1.7.0.gem) = 90effd1813363bae7355f4a45ebc8335a8ca74acc8d0933ba6ee6d40f281a2cf -+SIZE (rubygem/sshkit-1.7.0.gem) = 136192 -Index: 2015Q1 -=================================================================== ---- 2015Q1 (revision 380443) -+++ 2015Q1 (working copy) - -Property changes on: 2015Q1 -___________________________________________________________________ -Modified: svn:mergeinfo - Merged /head:r380362 -Do you want to commit? (no = start a shell) [y/n] -.... - -At that point, the script will either open a shell for you to fix things, or open your text editor with the commit message all prepared and then commit the merge. - -The script assumes that you can connect to `repo.FreeBSD.org` with SSH directly, so if your local login name is different than your FreeBSD cluster account, you need a few lines in your [.filename]#~/.ssh/config#: - -[.programlisting] -.... -Host *.freebsd.org - User freebsd-login -.... - -[TIP] -==== -The script is also able to merge more than one revision at a time. -If there have been other updates to the port since the branch was created that have not been merged because they were not security related. -Add the different revisions in the order they were committed on the `mfh` line. -The new commit log message will contain the combined log messages from all the original commits. -These messages must be edited to show what is actually being done with the new commit. - +Merging commits to the quarterly branch is very similar to MFC'ing a commit in the src repository, so basically: [source,shell] .... -% /usr/ports/Tools/scripts/mfh r407208 r407713 r407722 r408567 r408943 r410728 +% git checkout 2021Q2 +% git cherry-pick -x $HASH +(verify everything is OK, for example by doing a build test) +% git push .... -==== - -[NOTE] -==== -The mfh script can also take an optional first argument, the branch where the merge is being done. -Only the latest quarterly branch is supported, so specifying the branch is discouraged. -To be safe, the script will give a warning if the quarterly branch is not the latest: -[source,shell] -.... -% /usr/ports/Tools/scripts/mfh 2016Q1 r407208 r407713 -/!\ The latest branch is 2016Q2, do you really want to commit to 2016Q1? [y/n] -.... -==== +where '$HASH' is the hash of the commit you want to copy over to the quarterly branch. +The -x parameter ensures the hash '$HASH' of the main branch is included in the new commit message of the quarterly branch. [[ports-qa-new-category]] === Creating a New Category
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202104061910.136JAxtv091666>