New ports contributor's guide This chapter is a summary of Porter's Handbook with a few add-ons, specific to new contributor. It was aimed to answer most of questions (new) contributors can have. Introduction Ports tree is the most open part of the FreeBSD Project and a lot of people (are strongly encouraged to) contribute to it. When you're a maintainer, you must always remenber that people can use your port(s) in a production environment, so it implies you have to be wise in your changes, sure of your choices, and ready to be involved in problem resolution. Don't hesitate to post your questions, comments or patches to ports@FreeBSD.org mailing list to help us to improve ports tree architecture. FreeBSD Ports Contributors' Big List of Rules (also called "scaring list of responsibilities"): 1. Maintaining a port is not a title, but a responsibility. 2. Respect other maintainers. 3. Subscribe to mailing-lists. 4. Before submitting new ports (specially important ones), you should practise on unmaintained ports. 5. Be selective in your ports maintainership. 6. Understand what you do. 7. Start with small ports, and finish with bigger ones. 8. Be honest with yourself. Details: 1. Maintaining a port is not a title, but a responsability. Anyone can "maintain" hundreds of ports. Assuming maintainership is a huge task which sometimes goes far beyond what you expected. Maintaining port(s) implies: - You must update the port, and optionnaly be able to backport security fixes - If your port is widely used as dependency, you must ensure changes won't break ports depending on it. - You must fix build, as quick as you can - You must answer all kind of questions regarding the port 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, non-committers maintainer may not track GNATS activity and it can be frustrating for maintainer to be skipped. (see Sending PR section for more details) If you have a specific question or patch, don't Cc: ports@FreeBSD.org, except if you think your mail is REALLY important or related to the day-to-day use of the port (i.e. don't bother ports@FreeBSD.org subscribers #XXX) Don't flame maintainers, would you be happy if someone insult you because he disliks your work? When your update affects other ports, please contact directly all maintainers, ideally before you submit the update. For example, when library version is bumped, please contact ALL maintainers before, at leat Cc' or Bcc' them if you post to ports@FreeBSD.org. But please, do it before you submit your changes. 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 perl on FreeBSD: perl@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 unmaintained ports. Since practice makes perfect, please try to get familiar with ports system by cleaning/fixing/updating unmaintained ports, you will help us to provide an up-to-date ports tree, OTHO your work will be specially apprecied #XXX. 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 unmaintained 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 unmaintained ports (AKA "orphaned ports") About one quarter of ports are unmaintained, most of them are abandonware, but few of them are still under development, and maybe very important. To provide an efficient and complete ports tree, unmaintained ports require some work on. 1. Cleaning unmaintained ports. Even if they are abandoned, unmaintained 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 - Use new USE_* facilities. 2. Updating/patching unmaintained ports Many of unmaintained ports are not up-to-date. If you want to get involved in ports collection, feel free to update them. Of course, you can patch ports to support more knobs too. 3. Fixing/unbreak unmaintained ports Unmaintained ports can be marked as broken or be unbuildable: they are waiting for a fix. See build logs on pointyhat or on portsmon to find which ports fails and why. 4. Adopting unmaintained ports The best way to have an up to date and fully functionnal ports tree is to have a little of unmaintained 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, report some positive or negative feedback to the maintainer. Another 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 - Don't Cc: ports@FreeBSD.org. Committers and maintainer are usually subscribed to ports@FreeBSD.org AND ports-bugs@FreeBSD.org, so cross posting is useless, even annoying. It won't speed up the commit. If your PR is important, and you are scared it will be lost in the mass, you can send a mail to post@FreeBSD.org with a small desciption and the PR number. - For a new port send a shar archive and for update send an unified diff. F.A.Q. Q: Why my PR is not committed ? Q: How long is the maintainer timeout ? A: Please refer to the handbook. OTO Q: I can't send a PR. How can I do ? A: send-pr doesn't work correctly because your local mail system is not correctly configured.