From owner-svn-doc-all@FreeBSD.ORG Mon Apr 6 05:11:52 2015 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 87195928; Mon, 6 Apr 2015 05:11:52 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 6E02528; Mon, 6 Apr 2015 05:11:52 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id t365BqGC090401; Mon, 6 Apr 2015 05:11:52 GMT (envelope-from eadler@FreeBSD.org) Received: (from eadler@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id t365BoFL090394; Mon, 6 Apr 2015 05:11:50 GMT (envelope-from eadler@FreeBSD.org) Message-Id: <201504060511.t365BoFL090394@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: eadler set sender to eadler@FreeBSD.org using -f From: Eitan Adler Date: Mon, 6 Apr 2015 05:11:50 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r46482 - in head: de_DE.ISO8859-1/articles de_DE.ISO8859-1/articles/contributing-ports en_US.ISO8859-1/articles en_US.ISO8859-1/articles/contributing en_US.ISO8859-1/articles/contributi... X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 06 Apr 2015 05:11:52 -0000 Author: eadler Date: Mon Apr 6 05:11:49 2015 New Revision: 46482 URL: https://svnweb.freebsd.org/changeset/doc/46482 Log: contributing and contributing-ports: combine them - combine the 'how to contribute' doc and the 'contributing to ports' doc. - modernize the 'contributing to ports' doc - use &os; - prefer poudriere to tinderbox Reviewed by: crees, bapt, mat No objections from: bdrewery, gavin, wblock Deleted: head/de_DE.ISO8859-1/articles/contributing-ports/ head/en_US.ISO8859-1/articles/contributing-ports/ head/fr_FR.ISO8859-1/articles/contributing-ports/ head/nl_NL.ISO8859-1/articles/contributing-ports/ head/pt_BR.ISO8859-1/articles/contributing-ports/ Modified: head/de_DE.ISO8859-1/articles/Makefile head/en_US.ISO8859-1/articles/Makefile head/en_US.ISO8859-1/articles/contributing/article.xml head/fr_FR.ISO8859-1/articles/Makefile head/ja_JP.eucJP/articles/Makefile head/nl_NL.ISO8859-1/articles/Makefile head/pt_BR.ISO8859-1/articles/Makefile Modified: head/de_DE.ISO8859-1/articles/Makefile ============================================================================== --- head/de_DE.ISO8859-1/articles/Makefile Mon Apr 6 04:47:40 2015 (r46481) +++ head/de_DE.ISO8859-1/articles/Makefile Mon Apr 6 05:11:49 2015 (r46482) @@ -6,7 +6,6 @@ # basiert auf: 1.42 SUBDIR = contributing -gUBDIR+= contributing-ports SUBDIR+= explaining-bsd SUBDIR+= freebsd-update-server SUBDIR+= nanobsd Modified: head/en_US.ISO8859-1/articles/Makefile ============================================================================== --- head/en_US.ISO8859-1/articles/Makefile Mon Apr 6 04:47:40 2015 (r46481) +++ head/en_US.ISO8859-1/articles/Makefile Mon Apr 6 05:11:49 2015 (r46482) @@ -5,7 +5,6 @@ SUBDIR+= bsdl-gpl SUBDIR+= building-products SUBDIR+= committers-guide SUBDIR+= contributing -SUBDIR+= contributing-ports SUBDIR+= contributors SUBDIR+= cups SUBDIR+= explaining-bsd Modified: head/en_US.ISO8859-1/articles/contributing/article.xml ============================================================================== --- head/en_US.ISO8859-1/articles/contributing/article.xml Mon Apr 6 04:47:40 2015 (r46481) +++ head/en_US.ISO8859-1/articles/contributing/article.xml Mon Apr 6 05:11:49 2015 (r46482) @@ -12,7 +12,9 @@ - JordanHubbardContributed by + JordanHubbard + SamLawrance + MarkLinimon @@ -28,20 +30,22 @@ contributing - So you want to contribute to FreeBSD? That is great! FreeBSD + So you want to contribute to &os;? That is great! &os; relies on the contributions of its user base to survive. Your contributions are not only appreciated, they are - vital to FreeBSD's continued growth. + vital to &os;'s continued growth. - Contrary to what some people might have you believe, you do - not need to be a hot-shot programmer or a close personal friend of - the FreeBSD core team to have your contributions accepted. A - large and growing number of international contributors, of greatly - varying ages and areas of technical expertise, develop FreeBSD. - There is always more work to be done than there are people + A large and growing number of international contributors, of + greatly varying ages and areas of technical expertise, develop + &os;. There is always more work to be done than there are people available to do it, and more help is always appreciated. - The FreeBSD project is responsible for an entire operating + As a volunteer, what you do is limited only by what you want + to do. However, we do ask that you are aware of what other + members of the &os; community will expect of you. You may want + to take this into account before deciding to volunteer. + + The &os; project is responsible for an entire operating system environment, rather than just a kernel or a few scattered utilities. As such, our TODO lists span a very wide range of tasks: from documentation, beta testing and @@ -218,8 +222,53 @@ - Pick one of the items from the <quote>Ideas</quote> - page + Ongoing Ports Tasks + + The Ports Collection is a perpetual work in progress. We + want to provide our users with an easy to use, up to date, high + quality repository of third party software. We need people to + donate some of their time and effort to help us achieve this + goal. + + Anyone can get involved, and there are lots of different + ways to do so. Contributing to ports is an excellent way to + help give back something to the project. + Whether you are looking for an ongoing role, or a fun challenge + for a rainy day, we would love to have your help! + + There are a number of easy ways you can contribute to + keeping the ports tree up to date and in good working + order: + + + + Find some cool or useful software and + create a port + for it. + + + + There are a large number of ports that have no + maintainer. Become a maintainer and + adopt a port. + + + + If you have created or adopted a port, be + aware of what you need to do + as a maintainer. + + + + When you are looking for a quick challenge you + could fix a bug or a broken + port. + + + + + + Pick one of the items from the Ideas page The &os; list of projects and ideas for volunteers is also @@ -441,5 +490,711 @@ + + Contributing to ports + + + Adopting an unmaintained port + + + Choosing an unmaintained port + + Taking over maintainership of ports that are + unmaintained is a great way to get involved. Unmaintained + ports are only updated and fixed when somebody volunteers to + work on them. There are a large number of unmaintained + ports. It is a good idea to start with adopting a port that + you use regularly. + + Unmaintained ports have their + MAINTAINER set to + ports@FreeBSD.org. A list of unmaintained + ports and their current errors and problem reports can be seen + at the &os; + Ports Monitoring System. + + Some ports affect a large number of others due to + dependencies and slave port relationships. Generally, we + want people to have some experience before they maintain such + ports. + + You can find out whether or not a port has dependencies + or slave ports by looking at a master index of ports called + INDEX. (The name of the file varies + by release of &os;; for instance, + INDEX-8.) Some ports have conditional + dependencies that are not included in a default + INDEX build. We expect you to be able to + recognize such ports by looking through other ports' + Makefiles. + + + + How to adopt the port + + First make sure you understand your + responsibilities as a + maintainer. Also read the + Porter's + Handbook. Please do not commit yourself + to more than you feel you can comfortably + handle. + + You may request maintainership of any unmaintained port + as soon as you wish. Simply set MAINTAINER + to your own email address and send a PR (Problem Report) with + the change. If the port has build errors or needs updating, + you may wish to include any other changes in the same PR. + This will help because many committers are less willing to + assign maintainership to someone who does not have a known + track record with &os;. Submitting PRs that fix build errors + or update ports are the best ways to establish one. + + File your PR with category ports and + class change-request. A committer will + examine your PR, commit the changes, and finally close the + PR. Sometimes this process can take a little while + (committers are volunteers, too :). + + + + + The challenge for port maintainers + + This section will give you an idea of why ports need to be + maintained and outline the responsibilities of a port + maintainer. + + + Why ports require maintenance + + Creating a port is a once-off task. Ensuring that a + port is up to date and continues to build and run requires + an ongoing maintenance effort. Maintainers are the people + who dedicate some of their time to meeting these goals. + + The foremost reason ports need maintenance is to bring + the latest and greatest in third party software to the &os; + community. An additional challenge is to keep individual + ports working within the Ports Collection framework as it + evolves. + + As a maintainer, you will need to manage the following + challenges: + + + + + New software versions and updates. + + New versions and updates of existing ported + software become available all the time, and these need + to be incorporated into the Ports Collection in order + to provide up-to-date software. + + + + + + Changes to dependencies. + + If significant changes are made to the dependencies + of your port, it may need to be updated so that it will + continue to work correctly. + + + + + + Changes affecting dependent ports. + + If other ports depend on a port that you maintain, + changes to your port may require coordination with + other maintainers. + + + + + + Interaction with other users, maintainers and + developers. + + Part of being a maintainer is taking on a support + role. You are not expected to provide general support + (but we welcome it if you choose to do so). What you + should provide is a point of coordination for + &os;-specific issues regarding your ports. + + + + + + Bug hunting. + + A port may be affected by bugs which are specific + to &os;. You will need to investigate, find, and fix + these bugs when they are reported. Thoroughly testing + a port to identify problems before they make their way + into the Ports Collection is even better. + + + + + + Changes to ports infrastructure and policy. + + Occasionally the systems that are used to build + ports and packages are updated or a new recommendation + affecting the infrastructure is made. You should be + aware of these changes in case your ports are affected + and require updating. + + + + + + Changes to the base system. + + &os; is under constant development. Changes to + software, libraries, the kernel or even policy changes + can cause flow-on change requirements to ports. + + + + + + + Maintainer responsibilities + + + Keep your ports up to date + + This section outlines the process to follow to keep your + ports up to date. + + This is an overview. More information about upgrading a + port is available in the + + Porter's Handbook. + + + + Watch for updates + + Monitor the upstream vendor for new versions, + updates and security fixes for the software. + Announcement mailing lists or news web pages are useful + for doing this. Sometimes users will contact you and + ask when your port will be updated. If you are busy + with other things or for any reason just cannot update + it at the moment, ask if they will help you by + submitting an update. + + You may also receive automated email from the + &os; Ports Version Check informing + you that a newer version of your port's distfile is + available. More information about that system + (including how to stop future emails) will be provided + in the message. + + + + Incorporate changes + + When they become available, incorporate the changes + into the port. You need to be able to generate a patch + between the original port and your updated port. + + + + Review and test + + Thoroughly review and test your changes: + + + + Build, install and test your port on as many + platforms and architectures as you can. It is + common for a port to work on one branch or platform + and fail on another. + + + + Make sure your port's dependencies are complete. + The recommended way of doing this is by installing + your own ports tinderbox. + See resources + for more information. + + + + Check that the packing list is up to date. This + involves adding in any new files and directories and + removing unused entries. + + + + Verify your port using &man.portlint.1; as a + guide. See resources for important + information about using + portlint. + + + + Consider whether changes to your port might + cause any other ports to break. If this is the + case, coordinate the changes with the maintainers of + those ports. This is especially important if your + update changes the shared library version; in this + case, at the very least, the dependent ports will + need to get a PORTREVISION bump + so that they will automatically be upgraded by + automated tools such as + portmaster or + &man.portupgrade.1;. + + + + + + Submit changes + + Send your update by submitting a PR with an + explanation of the changes and a patch containing the + differences between the original port and the updated + one. Please refer to Writing FreeBSD + Problem Reports for information on how to + write a really good PR. + + + Please do not submit a &man.shar.1; archive of the + entire port; instead, use &man.diff.1; + -ruN. In this way, committers can + much more easily see exactly what changes are being + made. The Porter's Handbook section on Upgrading + has more information. + + + + + Wait + + At some stage a committer will deal with your PR. + It may take minutes, or it may take weeks — so + please be patient. + + + + Give feedback + + If a committer finds a problem with your changes, + they will most likely refer it back to you. A prompt + response will help get your PR committed faster, and + is better for maintaining a thread of conversation + when trying to resolve any problems. + + + + And Finally + + Your changes will be committed and your port will + have been updated. The PR will then be closed by the + committer. That's it! + + + + + + Ensure your ports continue to build correctly + + This section is about discovering and fixing problems + that stop your ports from building correctly. + + &os; only guarantees that the Ports Collection works on + the -STABLE branches. + In + theory, you should be able to get by with running the latest + release of each stable branch (since the ABIs are not + supposed to change) but if you can run the branch, that is + even better. + + Since the majority of &os; installations run on + PC-compatible machines (what is termed the + i386 architecture), we expect you to keep + the port working on that architecture. We prefer that ports + also work on the amd64 architecture + running native. It is completely fair to ask for help if + you do not have one of these machines. + + + The usual failure modes for + non-x86 machines are that the original + programmers assumed that, for instance, pointers are + ints, or that a relatively lax older + gcc compiler was being used. + More and more, application authors are reworking their + code to remove these assumptions — but if the author + is not actively maintaining their code, you may need to do + this yourself. + + + These are the tasks you need to perform to ensure your + port is able to be built: + + + + Watch for build failures + + Check your mail for mail from + pkg-fallout@FreeBSD.org + and the distfiles scanner + to see if any of the port which are failing to build + are out of date. + + + + Collect information + + Once you are aware of a problem, collect information + to help you fix it. Build errors reported by + pkg-fallout are accompanied by logs + which will show you where the build failed. If the + failure was reported to you by a user, ask them to send + you information which may help in diagnosing the + problem, such as: + + + + Build logs + + + + The commands and options used to build the + port (including options set in + /etc/make.conf) + + + + A list of packages installed on their system + as shown by &man.pkg.info.1; + + + + The version of &os; they are running as + shown by &man.uname.1; -a + + + + When their ports collection was last + updated + + + + When their ports tree amd + INDEX was last updated + + + + + + Investigate and find a solution + + Unfortunately there is no straightforward process to + follow to do this. Remember, though: if you are stuck, + ask for help! The &a.ports; is a good place to start, + and the upstream developers are often very + helpful. + + + + Submit changes + + Just as with updating a port, you should now + incorporate changes, review and test, submit your + changes in a PR, and provide feedback if + required. + + + + Send patches to upstream authors + + In some cases, you will have to make patches to the + port to make it run on FreeBSD. Some (but not all) + upstream authors will accept such patches back into + their code for the next release. If so, this may even + help their users on other BSD-based systems as well and + perhaps save duplicated effort. Please consider sending + any applicable patches to the authors as a + courtesy. + + + + + + + Investigate bug reports and PRs related to your + port + + This section is about discovering and fixing + bugs. + + &os;-specific bugs are generally caused by assumptions + about the build and runtime environments that do not apply + to &os;. You are less likely to encounter a problem of this + type, but it can be more subtle and difficult to + diagnose. + + These are the tasks you need to perform to ensure your + port continues to work as intended: + + + + Respond to bug reports + + Bugs may be reported to you through email via the + + Problem Report database. Bugs may also be + reported directly to you by users. + + You should respond to PRs and other reports within + 14 days, but please try not to take that long. Try to + respond as soon as possible, even if it is just to say + you need some more time before you can work on the + PR. + + If you have not responded after 14 days, any + committer may commit from a PR that you have not + responded to via a + maintainer-timeout. + + + + Collect information + + If the person reporting the bug has not also + provided a fix, you need to collect the information that + will allow you to generate one. + + If the bug is reproducible, you can collect most of + the required information yourself. If not, ask the + person who reported the bug to collect the information + for you, such as: + + + + A detailed description of their actions, + expected program behavior and actual behavior + + + + Copies of input data used to trigger the + bug + + + + Information about their build and execution + environment — for example, a list of installed + packages and the output of &man.env.1; + + + + Core dumps + + + + Stack traces + + + + + + Eliminate incorrect reports + + Some bug reports may be incorrect. For example, + the user may have simply misused the program; or their + installed packages may be out of date and require + updating. Sometimes a reported bug is not specific to + &os;. In this case report the bug to the upstream + developers. If the bug is within your capabilities to + fix, you can also patch the port so that the fix is + applied before the next upstream release. + + + + Find a solution + + As with build errors, you will need to sort out a + fix to the problem. Again, remember to ask if you are + stuck! + + + + Submit or approve changes + + Just as with updating a port, you should now + incorporate changes, review and test, and submit your + changes in a PR (or send a follow-up if a PR already + exists for the problem). If another user has submitted + changes in the PR, you can also send a follow-up saying + whether or not you approve the changes. + + + + + + Providing support + + Part of being a maintainer is providing support — + not for the software in general — but for the port and + any &os;-specific quirks and problems. Users may contact + you with questions, suggestions, problems and patches. Most + of the time their correspondence will be specific to + &os;. + + Occasionally you may have to invoke your skills in + diplomacy, and kindly point users seeking general support to + the appropriate resources. Less frequently you will + encounter a person asking why the RPMs + are not up to date or how can they get the software to run + under Foo Linux. Take the opportunity to tell them that + your port is up to date (if it is, of course!), and suggest + that they try &os;. + + Sometimes users and developers will decide that you are + a busy person whose time is valuable and do some of the work + for you. For example, they might: + + + + submit a PR or send you patches to update your + port, + + + + investigate and perhaps provide a fix to a PR, + or + + + + otherwise submit changes to your port. + + + + In these cases your main obligation is to respond in a + timely manner. Again, the timeout for non-responsive + maintainers is 14 days. After this period changes may be + committed unapproved. They have taken the trouble to do + this for you; so please try to at least respond promptly. + Then review, approve, modify or discuss their changes with + them as soon as possible. + + If you can make them feel that their contribution is + appreciated (and it should be) you will have a better chance + persuading them to do more things for you in the future + :-). + + + + + + Finding and fixing a broken port + + There are two really good places to find a port that needs + some attention. + + You can use the web + interface to the Problem Report database to search + through and view unresolved PRs. The majority of ports PRs are + updates, but with a little searching and skimming over synopses + you should be able to find something interesting to work on (the + sw-bug class is a good place to + start). + + The other place is the &os; Ports Monitoring + System. In particular look for unmaintained ports + with build errors and ports that are marked + BROKEN. It is OK to send changes for a + maintained port as well, but remember to ask the maintainer in + case they are already working on the problem. + + Once you have found a bug or problem, collect information, + investigate and fix! If there is an existing PR, follow up to + that. Otherwise create a new PR. Your changes will be reviewed + and, if everything checks out, committed. + + + + When to call it quits + + As your interests and commitments change, you may find that + you no longer have time to continue some (or all) of your ports + contributions. That is fine! Please let us know if you are no + longer using a port or have otherwise lost time or interest in + being a maintainer. In this way we can go ahead and allow other + people to try to work on existing problems with the port without + waiting for your response. Remember, &os; is a volunteer + project, so if maintaining a port is no fun anymore, it is + probably time to let someone else do it! + + In any case, the Ports Management Team + (portmgr) reserves the right to reset your + maintainership if you have not actively maintained your port in + some time. (Currently, this is set to 3 months.) By this, we + mean that there are unresolved problems or pending updates that + have not been worked on during that time. + + + + Resources for ports maintainers and contributors + + The Porter's + Handbook is your hitchhiker's guide to the ports + system. Keep it handy! + + Writing FreeBSD + Problem Reports describes how to best formulate and + submit a PR. In 2005 more than eleven thousand ports PRs were + submitted! Following this article will greatly assist us in + reducing the time needed to handle your PRs. + + The + Problem Report database. + + The FreeBSD Ports + Monitoring System can show you cross-referenced + information about ports such as build errors and problem + reports. If you are a maintainer you can use it to check on the + build status of your ports. As a contributor you can use it to + find broken and unmaintained ports that need to be fixed. + + The FreeBSD Ports + distfile scanner can show you ports for which the + distfiles are not fetchable. You can check on your own ports or + use it to find ports that need their + MASTER_SITES updated. + + ports-mgmt/poudriere is the most + thorough way to test a port through the entire cycle of + installation, packaging, and deinstallation. + documentation is located at the + poudriere home page + + &man.portlint.1; is an application which can be used to + verify that your port conforms to many important stylistic and + functional guidelines. portlint is a + simple heuristic application, so you should use it + only as a guide. If + portlint suggests changes which seem + unreasonable, consult the Porter's Handbook + or ask for advice. + + The &a.ports; is for general ports-related discussion. It + is a good place to ask for help. You can subscribe, or + read and search the list archives. Reading the + archives of the &a.ports-bugs; and the &a.cvs-ports; may also be + of interest. + + + Modified: head/fr_FR.ISO8859-1/articles/Makefile ============================================================================== --- head/fr_FR.ISO8859-1/articles/Makefile Mon Apr 6 04:47:40 2015 (r46481) +++ head/fr_FR.ISO8859-1/articles/Makefile Mon Apr 6 05:11:49 2015 (r46482) @@ -9,7 +9,6 @@ SUBDIR = building-products SUBDIR+= committers-guide SUBDIR+= contributing -SUBDIR+= contributing-ports SUBDIR+= contributors SUBDIR+= explaining-bsd SUBDIR+= filtering-bridges Modified: head/ja_JP.eucJP/articles/Makefile ============================================================================== --- head/ja_JP.eucJP/articles/Makefile Mon Apr 6 04:47:40 2015 (r46481) +++ head/ja_JP.eucJP/articles/Makefile Mon Apr 6 05:11:49 2015 (r46482) @@ -7,7 +7,6 @@ SUBDIR = #SUBDIR+= committers-guide #SUBDIR+= console-server SUBDIR+= contributing -#SUBDIR+= contributing-ports SUBDIR+= contributors #SUBDIR+= cups #SUBDIR+= explaining-bsd Modified: head/nl_NL.ISO8859-1/articles/Makefile ============================================================================== --- head/nl_NL.ISO8859-1/articles/Makefile Mon Apr 6 04:47:40 2015 (r46481) +++ head/nl_NL.ISO8859-1/articles/Makefile Mon Apr 6 05:11:49 2015 (r46482) @@ -5,7 +5,6 @@ SUBDIR = SUBDIR+= contributing -SUBDIR+= contributing-ports SUBDIR+= explaining-bsd SUBDIR+= problem-reports SUBDIR+= solid-state Modified: head/pt_BR.ISO8859-1/articles/Makefile ============================================================================== --- head/pt_BR.ISO8859-1/articles/Makefile Mon Apr 6 04:47:40 2015 (r46481) +++ head/pt_BR.ISO8859-1/articles/Makefile Mon Apr 6 05:11:49 2015 (r46482) @@ -11,7 +11,6 @@ SUBDIR = SUBDIR+= building-products SUBDIR+= contributing -SUBDIR+= contributing-ports SUBDIR+= explaining-bsd SUBDIR+= freebsd-questions SUBDIR+= freebsd-update-server