Date: Sat, 30 Jan 2021 19:37:20 GMT From: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: d8d889ea90 - main - MFH info missing from Committers Guide Message-ID: <202101301937.10UJbKsY075046@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=d8d889ea90432d249f7410f39921d0b11bade8e4 commit d8d889ea90432d249f7410f39921d0b11bade8e4 Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2021-01-30 19:36:26 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2021-01-30 19:36:26 +0000 MFH info missing from Committers Guide Restore MFH info in the committers guide. PR: 253065 Submitted by: fernanpe@ --- .../en/articles/committers-guide/_index.adoc | 414 ++++++++++++++++++++- 1 file changed, 411 insertions(+), 3 deletions(-) diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index 6460115072..dd0fee788a 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -2037,17 +2037,18 @@ Systems may only be moved from one tier to another by approval of the FreeBSD Co [[ports]] == Ports Specific FAQ -.Adding a New Port +[[ports-qa-adding]] +=== Adding a New Port [[ports-qa-add-new]] -=== How do I add a new port? +==== How do I add a new port? First, please read the section about repository copies. The easiest way to add a new port is the `addport` script located in the [.filename]#ports/Tools/scripts# directory. It adds a port from the directory specified, determining the category automatically from the port [.filename]#Makefile#. It also adds an entry to the port's category [.filename]#Makefile#. It was written by `{mharo}`, `{will}`, and `{garga}`. When sending questions about this script to the {freebsd-ports}, please also CC `{crees}`, the current maintainer. [[ports-qa-add-new-extra]] -=== Any other things I need to know when I add a new port? +==== Any other things I need to know when I add a new port? Check the port, preferably to make sure it compiles and packages correctly. This is the recommended sequence: @@ -2070,6 +2071,413 @@ If the port came from a submitter who has not contributed to the Project before, Close the PR if the port came in as a PR. To close a PR, change the state to `Issue Resolved` and the resolution as `Fixed`. +[[ports-qa-removing]] +=== Removing an Existing Port + +[[ports-qa-remove-one]] +==== How do I remove an existing port? + +First, please read the section about repository copies. Before you remove the port, you have to verify there are no other ports depending on it. + +* Make sure there is no dependency on the port in the ports collection: +** The port's PKGNAME appears in exactly one line in a recent INDEX file. +** No other ports contains any reference to the port's directory or PKGNAME in their Makefiles ++ +[TIP] +==== +When using Git, consider using `git grep`, it is much faster than `grep -r`. +==== ++ +* Then, remove the port: ++ +[.procedure] +==== +* Remove the port's files and directory with `svn remove`. +* 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. +* Remove the port from [.filename]#ports/LEGAL# if it is there. +==== + +Alternatively, you can use the rmport script, from [.filename]#ports/Tools/scripts#. 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. +==== + +[.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,bash] +.... +% 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,bash] +.... +% 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. +. 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. +==== + +[[ports-qa-freeze]] +=== Ports Freeze + +[[ports-qa-freeze-what]] +==== What is a “ports freeze”? + +A “ports freeze” was a restricted state the ports tree was put in before a release. It was used to ensure a higher quality for the packages shipped with a release. It usually lasted a couple of weeks. During that time, build problems were fixed, and the release packages were built. This practice is no longer used, as the packages for the releases are built from the current stable, quarterly branch. + +For more information on how to merge commits to the quarterly branch, see <<ports-qa-misc-request-mfh>>. + +[[ports-qa-quarterly]] +=== Quarterly Branches + +[[ports-qa-misc-request-mfh]] +==== What is the procedure to request authorization for merging a commit to the quarterly branch? + +When doing the commit, add the branch name to the `MFH:` line, for example: + +[.programlisting] +.... +MFH: 2014Q1 +.... + +It will automatically notify the {ports-secteam} and the {portmgr}. They will then decide if the commit can be merged and answer with the procedure. + +If the commit has already been made, send an email to the {ports-secteam} and the {portmgr} with the revision number and a small description of why the commit needs to be merged. + +[TIP] +==== +Tip: + +If the MFH is covered by a blanket approval, please explain why with a couple of words on the `MFH` line, so that the reviewing team can skip this commit and save time. For example: + +[.programlisting] +.... +MFH: 2014Q1 (runtime fix) +MFH: 2014Q1 (browser blanket) +.... + +The list of blanket approvals is available in <<ports-qa-blanket>>. +==== + +[[ports-qa-blanket]] +==== Are there any changes that can be merged without asking for approval? + +The following blanket approvals for merging to the quarterly branches are in effect: + +[NOTE] +==== +This blanket approval also applies to direct commits for ports that have been removed from `head`. +==== + +[IMPORTANT] +==== +These fixes must be tested on the quarterly branch. +==== + +* Fixes that do not result in a change in contents of the resulting package. For example: +** [.filename]#pkg-descr#: `WWW`: URL updates (existing 404, moved or incorrect) +Build, runtime or packaging fixes, if the quarterly branch version is currently broken. +Missing dependencies (detected, linked against but not registered via `*_DEPENDS`). +* Fixing link:{porters-handbook}#uses-shebangfix[shebangs], stripping installed libraries and binaries, and plist fixes. +* Backport of security and reliability fixes which only result in `PORTREVISION` bumps and no changes to enabled features. for example, adding a patch fixing a buffer overflow. +* Minor version changes that do nothing but fix security or crash-related issues. +* Adding/fixing `CONFLICTS`. +* Web Browsers, browser plugins, and their required dependencies. + +[IMPORTANT] +==== +Commits that are not covered by these blanket approvals always require explicit approval of either {ports-secteam} or {portmgr}. +==== + +[[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,bash] +.... +% /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. + +[source,bash] +.... +% /usr/ports/Tools/scripts/mfh r407208 r407713 r407722 r408567 r408943 r410728 +.... +==== + +[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,bash] +.... +% /usr/ports/Tools/scripts/mfh 2016Q1 r407208 r407713 +/!\ The latest branch is 2016Q2, do you really want to commit to 2016Q1? [y/n] +.... +==== + +[[ports-qa-new-category]] +=== Creating a New Category + +[[ports-qa-new-category-how]] +==== What is the procedure for creating a new category? + +Please see link:{porters-handbook}#proposing-categories[Proposing a New Category] in the Porter's Handbook. Once that procedure has been followed and the PR has been assigned to the {portmgr}, it is their decision whether or not to approve it. If they do, it is their responsibility to: + +[.procedure] +==== +. Perform any needed moves. (This only applies to physical categories.) +. Update the `VALID_CATEGORIES` definition in [.filename]#ports/Mk/bsd.port.mk#. +. Assign the PR back to you. +==== + +[[ports-qa-new-category-physical]] +==== What do I need to do to implement a new physical category? + +[.procedure] +==== +. Upgrade each moved port's [.filename]#Makefile#. Do not connect the new category to the build yet. ++ +To do this, you will need to: ++ +[.procedure] +====== +. Change the port's `CATEGORIES` (this was the point of the exercise, remember?) The new category is listed first. This will help to ensure that the PKGORIGIN is correct. +. Run a `make describe`. Since the top-level `make index` that you will be running in a few steps is an iteration of `make describe` over the entire ports hierarchy, catching any errors here will save you having to re-run that step later on. +. If you want to be really thorough, now might be a good time to run man:portlint[1]. +====== ++ +. Check that the ``PKGORIGIN``s are correct. The ports system uses each port's `CATEGORIES` entry to create its `PKGORIGIN`, which is used to connect installed packages to the port directory they were built from. If this entry is wrong, common port tools like man:pkg_version[1] and man:portupgrade[1] fail. ++ +To do this, use the [.filename]#chkorigin.sh# tool: `env PORTSDIR=/path/to/ports sh -e /path/to/ports/Tools/scripts/chkorigin.sh`. This will check every port in the ports tree, even those not connected to the build, so you can run it directly after the move operation. Hint: do not forget to look at the ``PKGORIGIN``s of any slave ports of the ports you just moved! +. On your own local system, test the proposed changes: first, comment out the SUBDIR entries in the old ports' categories' [.filename]##Makefile##s; then enable building the new category in [.filename]#ports/Makefile#. Run make checksubdirs in the affected category directories to check the SUBDIR entries. Next, in the [.filename]#ports/# directory, run make index. This can take over 40 minutes on even modern systems; however, it is a necessary step to prevent problems for other people. +. Once this is done, you can commit the updated [.filename]#ports/Makefile# to connect the new category to the build and also commit the [.filename]#Makefile# changes for the old category or categories. +. Add appropriate entries to [.filename]#ports/MOVED#. +. Update the documentation by modifying: +** the link:{porters-handbook}#PORTING-CATEGORIES[list of categories] in the Porter's Handbook +** [.filename]#doc/en_US.ISO8859-1/htdocs/ports#. Note that these are now displayed by sub-groups, as specified in [.filename]#doc/en_US.ISO8859-1/htdocs/ports/categories.descriptions#. ++ +(Note: these are in the docs, not the ports, repository). If you are not a docs committer, you will need to submit a PR for this. ++ +. Only once all the above have been done, and no one is any longer reporting problems with the new ports, should the old ports be deleted from their previous locations in the repository. +==== + +It is not necessary to manually update the link:https://www.FreeBSD.org/ports/[ports web pages] to reflect the new category. This is done automatically via the change to [.filename]#en_US.ISO8859-1/htdocs/ports/categories# and the automated rebuild of INDEX. + +==== What do I need to do to implement a new virtual category? + +This is much simpler than a physical category. Only a few modifications are needed: + +* the link:{porters-handbook}#PORTING-CATEGORIES[list of categories] in the Porter's Handbook +* [.filename]#en_US.ISO8859-1/htdocs/ports/categories# + +[[ports-qa-misc-questions]] +=== Miscellaneous Questions + +[[ports-qa-misc-blanket-approval]] +==== Are there changes that can be committed without asking the maintainer for approval? + +Blanket approval for most ports applies to these types of fixes: + +* Most infrastructure changes to a port (that is, modernizing, but not changing the functionality). For example, the blanket covers converting to new `USES` macros, enabling verbose builds, and switching to new ports system syntaxes. +* Trivial and _tested_ build and runtime fixes. +* Documentations or metadata changes to ports, like [.filename]#pkg-descr# or `COMMENT`. + +[IMPORTANT] +==== +Exceptions to this are anything maintained by the {portmgr}, or the {security-officer}. No unauthorized commits may ever be made to ports maintained by those groups. +==== + +[[ports-qa-misc-correctly-building]] +==== How do I know if my port is building correctly or not? + +The packages are built multiple times each week. If a port fails, the maintainer will receive an email from `pkg-fallout@FreeBSD.org`. + +Reports for all the package builds (official, experimental, and non-regression) are aggregated at link:pkg-status.FreeBSD.org[pkg-status.FreeBSD.org]. + +[[ports-qa-misc-INDEX]] +==== I added a new port. Do I need to add it to the [.filename]#INDEX#? + +No. The file can either be generated by running `make index`, or a pre-generated version can be downloaded with `make fetchindex`. + +[[ports-qa-misc-no-touch]] +==== Are there any other files I am not allowed to touch? + +Any file directly under [.filename]#ports/#, or any file under a subdirectory that starts with an uppercase letter ([.filename]#Mk/#, [.filename]#Tools/#, etc.). In particular, the {portmgr} is very protective of [.filename]#ports/Mk/bsd.port*.mk# so do not commit changes to those files unless you want to face their wrath. + +[[ports-qa-misc-updated-distfile]] +==== What is the proper procedure for updating the checksum for a port distfile when the file changes without a version change? + +When the checksum for a distribution file is updated due to the author updating the file without changing the port revision, the commit message includes a summary of the relevant diffs between the original and new distfile to ensure that the distfile has not been corrupted or maliciously altered. If the current version of the port has been in the ports tree for a while, a copy of the old distfile will usually be available on the ftp servers; otherwise the author or maintainer should be contacted to find out why the distfile has changed. + +[[ports-exp-run]] +==== How can an experimental test build of the ports tree (exp-run) be requested? + +An exp-run must be completed before patches with a significant ports impact are committed. The patch can be against the ports tree or the base system. + +Full package builds will be done with the patches provided by the submitter, and the submitter is required to fix detected problems _(fallout)_ before commit. + +[.procedure] +==== +. Go to the link:https://bugs.freebsd.org/submit[Bugzilla new PR page]. +. Select the product your patch is about. +. Fill in the bug report as normal. Remember to attach the patch. +. If at the top it says “Show Advanced Fields” click on it. It will now say “Hide Advanced Fields”. Many new fields will be available. If it already says “Hide Advanced Fields”, no need to do anything. +. In the “Flags” section, set the “exp-run” one to `?`. As for all other fields, hovering the mouse over any field shows more details. +. Submit. Wait for the build to run. +. {portmgr} will reply with a possible fallout. +. Depending on the fallout: +** If there is no fallout, the procedure stops here, and the change can be committed, pending any other approval required. +... If there is fallout, it _must_ be fixed, either by fixing the ports directly in the ports tree, or adding to the submitted patch. +... When this is done, go back to step 6 saying the fallout was fixed and wait for the exp-run to be run again. Repeat as long as there are broken ports. +==== + [[non-committers]] == Issues Specific to Developers Who Are Not Committers
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202101301937.10UJbKsY075046>