Changeset View
Changeset View
Standalone View
Standalone View
documentation/content/en/articles/contributing/_index.adoc
Show First 20 Lines • Show All 241 Lines • ▼ Show 20 Lines | |||||||||||
Taking over maintainership of ports that are unmaintained is a great way to get involved. | 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. | Unmaintained ports are only updated and fixed when somebody volunteers to work on them. | ||||||||||
There are a large number of unmaintained ports. | There are a large number of unmaintained ports. | ||||||||||
It is a good idea to start with adopting a port that you use regularly. | 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`. | 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 http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org[FreeBSD Ports Monitoring System]. | A list of unmaintained ports and their current errors and problem reports can be seen at the http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org[FreeBSD Ports Monitoring System]. | ||||||||||
On https://portsfallout.com/fallout?port=&maintainer=ports%40FreeBSD.org[PortsFallout] can be seen a list of unmaintained ports with errors. | |||||||||||
Many unmaintained ports can have pending updates, this can be seen at the https://portscout.freebsd.org/ports@freebsd.org.html[FreeBSD Ports distfile scanner]. | |||||||||||
Some ports affect a large number of others due to dependencies and slave port relationships. | 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. | 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 [.filename]#INDEX#. | You can find out whether or not a port has dependencies or slave ports by looking at a master index of ports called [.filename]#INDEX#. | ||||||||||
(The name of the file varies by release of FreeBSD; for instance, [.filename]#INDEX-8#.) Some ports have conditional dependencies that are not included in a default [.filename]#INDEX# build. | (The name of the file varies by release of FreeBSD; for instance, [.filename]#INDEX-8#.) Some ports have conditional dependencies that are not included in a default [.filename]#INDEX# build. | ||||||||||
We expect you to be able to recognize such ports by looking through other ports' [.filename]#Makefile#'s. | We expect you to be able to recognize such ports by looking through other ports' [.filename]#Makefile#'s. | ||||||||||
[NOTE] | |||||||||||
====== | |||||||||||
The FreeBSD Ports Monitoring System (portsmon) is currently not working due to latest Python updates. | |||||||||||
pauamma_gundo.comUnsubmitted Done Inline Actions
pauamma_gundo.com: | |||||||||||
====== | |||||||||||
==== How to adopt the port | ==== How to adopt the port | ||||||||||
First make sure you understand your <<maintain-port>>. | First make sure you understand your <<maintain-port>>. | ||||||||||
Also read the link:{porters-handbook}[Porter's Handbook]. | Also read the link:{porters-handbook}[Porter's Handbook]. | ||||||||||
_Please do not commit yourself to more than you feel you can comfortably handle._ | _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. | 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. | Simply set `MAINTAINER` to your own email address and send a PR (Problem Report) with the change. | ||||||||||
▲ Show 20 Lines • Show All 220 Lines • ▼ Show 20 Lines | |||||||||||
They have taken the trouble to do this for you; so please try to at least respond promptly. | 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. | 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 :-). | 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 :-). | ||||||||||
[[fix-broken]] | [[fix-broken]] | ||||||||||
=== Finding and fixing a broken port | === Finding and fixing a broken port | ||||||||||
There are two really good places to find a port that needs some attention. | There are some really good places to find a port that needs some attention. | ||||||||||
You can use the https://bugs.freebsd.org/search[web interface] to the Problem Report database to search through and view unresolved PRs. | You can use the https://bugs.freebsd.org/search[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 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 http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System]. | The other place is the http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System]. | ||||||||||
In particular look for unmaintained ports with build errors and ports that are marked `BROKEN`. | In particular look for unmaintained ports with build errors and ports that are marked `BROKEN`. | ||||||||||
https://portsfallout.com/[PortsFallout] shows port issues gathered from the FreeBSD package building. | |||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||
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. | 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. | 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. | Otherwise create a new PR. | ||||||||||
Your changes will be reviewed and, if everything checks out, committed. | Your changes will be reviewed and, if everything checks out, committed. | ||||||||||
[NOTE] | |||||||||||
====== | |||||||||||
The FreeBSD Ports Monitoring System (portsmon) is currently not working due to latest Python updates. | |||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||
====== | |||||||||||
[[mortal-coil]] | [[mortal-coil]] | ||||||||||
=== When to call it quits | === 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. | 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. | 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. | 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, FreeBSD is a volunteer project, so if maintaining a port is no fun any more, it is probably time to let someone else do it! | Remember, FreeBSD is a volunteer project, so if maintaining a port is no fun any more, 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. | 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.) | (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. | By this, we mean that there are unresolved problems or pending updates that have not been worked on during that time. | ||||||||||
[[resources]] | [[resources]] | ||||||||||
=== Resources for ports maintainers and contributors | === Resources for ports maintainers and contributors | ||||||||||
The link:{porters-handbook}[Porter's Handbook] is your hitchhiker's guide to the ports system. Keep it handy! | The link:{porters-handbook}[Porter's Handbook] is your hitchhiker's guide to the ports system. Keep it handy! | ||||||||||
link:{problem-reports}[Writing FreeBSD Problem Reports] describes how to best formulate and submit a PR. | link:{problem-reports}[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. | 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 https://bugs.freebsd.org/bugzilla/query.cgi[Problem Report database]. | The https://bugs.freebsd.org/bugzilla/query.cgi[Problem Report database]. | ||||||||||
The http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System] can show you cross-referenced information about ports such as build errors and problem reports. | The http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System (portsmon)] 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. | 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. | As a contributor you can use it to find broken and unmaintained ports that need to be fixed. | ||||||||||
The http://portscout.FreeBSD.org[FreeBSD Ports distfile scanner] can show you ports for which the distfiles are not fetchable. | The http://portscout.FreeBSD.org[FreeBSD Ports distfile scanner (portscout)] 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. | You can check on your own ports or use it to find ports that need their `MASTER_SITES` updated. | ||||||||||
package:ports-mgmt/poudriere[] is the most thorough way to test a port through the entire cycle of installation, packaging, and deinstallation. | package: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 https://github.com/freebsd/poudriere[poudriere github repository] | Documentation is located at the https://github.com/freebsd/poudriere[poudriere github repository] | ||||||||||
man:portlint[1] is an application which can be used to verify that your port conforms to many important stylistic and functional guidelines. | 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__. | portlint is a simple heuristic application, so you should use it __only as a guide__. | ||||||||||
If portlint suggests changes which seem unreasonable, consult the link:{porters-handbook}[Porter's Handbook] or ask for advice. | If portlint suggests changes which seem unreasonable, consult the link:{porters-handbook}[Porter's Handbook] or ask for advice. | ||||||||||
The {freebsd-ports} is for general ports-related discussion. | The {freebsd-ports} is for general ports-related discussion. | ||||||||||
It is a good place to ask for help. | It is a good place to ask for help. | ||||||||||
You can https://lists.freebsd.org/mailman/listinfo[subscribe, or read and search the list archives]. | You can https://lists.freebsd.org/mailman/listinfo[subscribe, or read and search the list archives]. | ||||||||||
Reading the archives of the {freebsd-ports-bugs} and the {svn-ports-head} may also be of interest. | Reading the archives of the {freebsd-ports-bugs} and the {svn-ports-head} may also be of interest. | ||||||||||
https://portsfallout.com/[PortsFallout] is a place to help in searching for the https://lists.freebsd.org/pipermail/freebsd-pkg-fallout/[FreeBSD package-fallout archive]. | |||||||||||
[[ideas-contributing]] | [[ideas-contributing]] | ||||||||||
== Getting Started in Other Areas | == Getting Started in Other Areas | ||||||||||
Looking for something interesting to get started that is not mentioned elsewhere in this article? The FreeBSD Project has several Wiki pages containing areas within which new contributors can get ideas on how to get started. | Looking for something interesting to get started that is not mentioned elsewhere in this article? The FreeBSD Project has several Wiki pages containing areas within which new contributors can get ideas on how to get started. | ||||||||||
The https://wiki.freebsd.org/JuniorJobs[Junior Jobs] page has a list of projects that might be of interest to people just getting started in FreeBSD, and want to work on interesting things to get their feet wet. | The https://wiki.freebsd.org/JuniorJobs[Junior Jobs] page has a list of projects that might be of interest to people just getting started in FreeBSD, and want to work on interesting things to get their feet wet. | ||||||||||
The https://wiki.freebsd.org/IdeasPage[Ideas Page] contains various "nice to have" or "interesting" things to work on in the Project. | The https://wiki.freebsd.org/IdeasPage[Ideas Page] contains various "nice to have" or "interesting" things to work on in the Project. |