New ports contributor's guide This chapter is a summary of Porter's Handbook with a few add-ons, specific to new contributor. It should answer most of new contributors' questions. Ports tree is surely the most open part of the FreeBSD Project and a lot of people contribute to it. You must always remenber that people may use your port(s) in a production environment, so be wise in your changes. FreeBSD Ports Contributors' Big List of Rules: 1. Maintaining a port is not a title, but a responsability. 2. Respect other maintainers. 3. Subscribe to mailing-lists. 4. Before submitting new ports (specially important ones), you should practise on orphaned ports. 5. Be selective in your ports. 6. Understand what you do. 7. Start with small ports, and finish with bigger one. 8. Be honest with yourself. 9. If you make a mistake... Details: 1. Maintaining a port is not a title, but a responsability. Anyone can "maintain" hundreds of ports. Assuming maintainership is a huge task. You are responsible for your port(s). It implies: - you must update the port - you must fix build - you must answer all kind of questions concerning the port - If you port is widely used as dependency, you must ensure that it won't break ports depending on it. 2. Respect other maintainers. Since you are contributor, it's obvious you respect committers, but you should "treat" other maintainers like committers. Don't send directly patch with send-pr, it's frustrating for maintainer to be skipped. (see Sending PR section) If you have a specific question or patch, don't Cc: ports@FreeBSD.org, except if you think your mail is REALLY important. Don't flame maintainers. When your update implies change, please contact directly all maintainers. e.g. library version is bumped, please contact ALL maintainers before, at least Cc or Bcc them if you post to ports@FreeBSD.org. 3. Subscribe to correct mailing-lists As soon as you contribute to FreeBSD ports system, you are strongly encouraged to subscribe to freebsd-ports@FreeBSD.org and freebsd-ports-bugs@FreeBSD.org mailing-lists. Most of important announcements are posted to freebsd-ports@FreeBSD.org. If you are involved in ports sub-projects please consider these mailing-lists: Gnome on FreeBSD: freebsd-gnome@FreeBSD.org KDE on FreeBSD: kde-freebsd@lists.csociety.org (https://lists.csociety.org/listinfo/kde-freebsd) X11 on FreeBSD: freebsd-x11@FreeBSD.org Extra (but recommanded mailing list) freebsd-current@FreeBSD.org freebsd-stable@FreeBSD.org to cvs-ports@FreeBSD.org 4. Before submitting new ports (specially important ones), you should practise on orphaned ports. Since practice makes perfect, please try to get familiar with ports system by cleaning/fixing/updating orphaned ports. 5. Be selective in your ports. When you create/maintain a port, committers assume that you know how it works. In the best of cases, you have a day-to-day use of it. Please when you submit a port or take over maintainership be sure you can fix it quickly. Don't port applications you can't fix, at least, set MAINTAINER to ports@FreeBSD.org or,even better, look for someone who can take care of it. 6. Understand what you do. It seems obvious, but most of new contributors don't really understand what they do. Once more, read a lot of Makefiles, Mk/bsd.*.mk and practise on orphaned ports. 7. Start with small ports, and finish with bigger one. You can take hours to make a complex port, but how long will it take you to fix it ? That's the question. If you start with small ports, fixing them will be painless. Be wise, always think that you may have many people who use your port(s). 8. Be honest with yourself. First of all, don't contribute if you only want to become a committer. Being committer is attractive but a good ports committer is interested in FreeBSD ports. It's a huge amount of additionnal work. Don't maintain more ports that you can. Don't be arrogant, if someone sends you good patches for one of your ports which you don't specially care about or you don't use/want to maintain anymore, why don't let the submitter maintain the port ? It's not a shame to reset maintainership to ports@FreeBSD.org you know... Working on orphaned ports About one quarter of ports are orphaned, most of them are abandonware, but few of them are still under development. To provide an efficient and complete ports tree, orphaned ports require some work on. 1. Cleaning orphaned ports. Even if they are abandoned, orphaned ports should be sync'ed with new ports system features. This work is a good start point for rookies to get familiar with new Mk/bsd.*.mk macros. Examples: - Use DOCSDIR, DATADIR, EXAMPLESDIR, PORTSDOC macros - Fix dependencies or pkg-plist - Respect CFLAGS 2. Updating/patching orphaned ports Many orphaned ports are not up-to-date. If you want to get involved in ports collection, feel free to update them. You can patch ports to support more knobs too. 3. Fixing/unbreak orphaned ports Orphaned ports can be marked as broken or can't build, and they are waiting for fix. See bento logs to find which ports fails and why. 4. Adopting orphaned ports The best way to have an update to date and functionnal ports tree is to have a little of orphaned ports, feel free to adopt a port. Working on maintained ports Even if a port is maintained it can be out of date or incomplete. Here's some rules to make everybody happy 1. Feedback If you can, give some positive or negative feedback to the maintainer. Real-world use may help the maintainer to make the good choice (specially for default options) 2. Feature requests, patches and update As usual, a feature request with a patch is always better than a single feature request. Please respect maintainer choices, he surely should have a good reason for them. Don't rewrite his Makefile or patches, try to patch in the same spirit. And be polite. :-) Creating a new port. Sending PR Sending PR is an important operation, a good PR is a quickly committed PR. On the other hand, PR database is overused... 1. Efficient filling Here some important hint: - please always use a real mail address and the same originator name - Choose the correct class (see pr-guidelines) - put [maintainer update], [maintainer patch], [update], [patch], [fix], [bento fix], [non-maintainer update], [non-maintainer patch] or [bug] in synopsys - put ${CATEGORY}/${PORTNAME} in synopsys - if you update a port, please notify committers if files were added/removed - be verbose in your description - if you can put all the FreeBSD versions you test (or not) the port Rules - DO NOT DIRECTLY SEND A NON-MAINTAINER UPDATE/FIX/PATCH ! Send your patch directly to the maintainer first (except if the maintainer is a committer). After a reasonnable timeout (i.e. no response, if you receive an ACK, respect maintainer please) you can send a PR. Why ? regular maintainer don't have a direct access to GNATS database, if everyone send patches via send-pr interface the PR database would be quickly flooded by rotten PR. If you don't have any response from the maintainer, send a PR and Cc: maintainer... it may speed up the process. Maintainers are encouraged to use the excellent Mark Lininom's "FreeBSD port status by portname for maintainer" http://lonesome.dyndns.org:4802/bento/errorlogs/portsconcordanceformaintainer.py