Changeset View
Changeset View
Standalone View
Standalone View
documentation/content/en/articles/contributing/_index.adoc
Context not available. | |||||
:sectnumlevels: 6 | :sectnumlevels: 6 | ||||
:source-highlighter: rouge | :source-highlighter: rouge | ||||
:experimental: | :experimental: | ||||
:images-path: articles/contributing/ | |||||
ifeval::["{backend}" == "html5"] | |||||
include::shared/en/mailing-lists.adoc[] | ifdef::env-beastie+backend-html5[] | ||||
include::shared/en/urls.adoc[] | include::shared/authors.adoc[] | ||||
endif::[] | include::shared/mirrors.adoc[] | ||||
include::shared/releases.adoc[] | |||||
ifeval::["{backend}" == "pdf"] | include::shared/{{% lang %}}/mailing-lists.adoc[] | ||||
include::../../../../shared/en/mailing-lists.adoc[] | include::shared/{{% lang %}}/urls.adoc[] | ||||
include::../../../../shared/en/urls.adoc[] | :imagesdir: ../../../images/{images-path} | ||||
endif::[] | endif::[] | ||||
ifeval::["{backend}" == "epub3"] | ifndef::env-beastie[] | ||||
include::../../../../shared/en/mailing-lists.adoc[] | include::../../../../shared/asciidoctor.adoc[] | ||||
include::../../../../shared/en/urls.adoc[] | |||||
endif::[] | endif::[] | ||||
[.abstract-title] | [.abstract-title] | ||||
Context not available. | |||||
All that these people need to contribute is an investment of time and a willingness to learn. | All that these people need to contribute is an investment of time and a willingness to learn. | ||||
. Read through the FAQ and Handbook periodically. If anything is poorly explained, ambiguous, out of date or incorrect, let us know. Even better, send us a fix (AsciiDoc is not difficult to learn, but there is no objection to plain text submissions). | . Read through the FAQ and Handbook periodically. If anything is poorly explained, ambiguous, out of date or incorrect, let us know. Even better, send us a fix (AsciiDoc is not difficult to learn, but there is no objection to plain text submissions). | ||||
. Help translate FreeBSD documentation into your native language. If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date and correct. First take a look at the link:{fdp-primer}#translations[Translations FAQ] in the FreeBSD Documentation Project Primer. You are not committing yourself to translating every single FreeBSD document by doing this - as a volunteer, you can do as much or as little translation as you desire. Once someone begins translating, others almost always join the effort. If you only have the time or energy to translate one part of the documentation, please translate the installation instructions. | . Help translate FreeBSD documentation into your native language. If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date and correct. First take a look at the extref:{fdp-primer}[Translations FAQ, translations] in the FreeBSD Documentation Project Primer. You are not committing yourself to translating every single FreeBSD document by doing this - as a volunteer, you can do as much or as little translation as you desire. Once someone begins translating, others almost always join the effort. If you only have the time or energy to translate one part of the documentation, please translate the installation instructions. | ||||
. Read the {freebsd-questions} occasionally (or even regularly). It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! These forums can also be a source of ideas for things to improve upon. | . Read the {freebsd-questions} occasionally (or even regularly). It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! These forums can also be a source of ideas for things to improve upon. | ||||
[[ongoing-programmer-tasks]] | [[ongoing-programmer-tasks]] | ||||
Context not available. | |||||
There are a number of easy ways you can contribute to keeping the ports tree up to date and in good working order: | 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 link:{porters-handbook}[create a port] for it. | * Find some cool or useful software and extref:{porters-handbook}[create a port] for it. | ||||
* There are a large number of ports that have no maintainer. Become a maintainer and <<adopt-port>>. | * There are a large number of ports that have no maintainer. Become a maintainer and <<adopt-port>>. | ||||
* If you have created or adopted a port, be aware of <<maintain-port>>. | * If you have created or adopted a port, be aware of <<maintain-port>>. | ||||
* When you are looking for a quick challenge you could <<fix-broken>>. | * When you are looking for a quick challenge you could <<fix-broken>>. | ||||
Context not available. | |||||
An idea or suggestion of _general_ technical interest should be mailed to the {freebsd-hackers}. | An idea or suggestion of _general_ technical interest should be mailed to the {freebsd-hackers}. | ||||
Likewise, people with an interest in such things (and a tolerance for a _high_ volume of mail!) may subscribe to the {freebsd-hackers}. | Likewise, people with an interest in such things (and a tolerance for a _high_ volume of mail!) may subscribe to the {freebsd-hackers}. | ||||
See link:{handbook}#eresources-mail[The FreeBSD Handbook] for more information about this and other mailing lists. | See extref:{handbook}[The FreeBSD Handbook, eresources-mail] for more information about this and other mailing lists. | ||||
If you find a bug or are submitting a specific change, please report it using the https://bugs.FreeBSD.org/submit/[bug submission form]. | If you find a bug or are submitting a specific change, please report it using the https://bugs.FreeBSD.org/submit/[bug submission form]. | ||||
Try to fill-in each field of the bug report. | Try to fill-in each field of the bug report. | ||||
Context not available. | |||||
After filing a report, you should receive confirmation along with a tracking number. | After filing a report, you should receive confirmation along with a tracking number. | ||||
Keep this tracking number so that you can update us with details about the problem. | Keep this tracking number so that you can update us with details about the problem. | ||||
See also link:{problem-reports}[this article] on how to write good problem reports. | See also extref:{problem-reports}[this article] on how to write good problem reports. | ||||
=== Changes to the Documentation | === Changes to the Documentation | ||||
Changes to the documentation are overseen by the {freebsd-doc}. | Changes to the documentation are overseen by the {freebsd-doc}. | ||||
Please look at the link:{fdp-primer}[FreeBSD Documentation Project Primer] for complete instructions. | Please look at the extref:{fdp-primer}[FreeBSD Documentation Project Primer] for complete instructions. | ||||
Send submissions and changes (even small ones are welcome!) using the same method as any other bug report. | Send submissions and changes (even small ones are welcome!) using the same method as any other bug report. | ||||
=== Changes to Existing Source Code | === Changes to Existing Source Code | ||||
An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. | An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. | ||||
There is a special on-going release of FreeBSD known as "FreeBSD-CURRENT" which is made available in a variety of ways for the convenience of developers working actively on the system. | There is a special on-going release of FreeBSD known as "FreeBSD-CURRENT" which is made available in a variety of ways for the convenience of developers working actively on the system. | ||||
See link:{handbook}#current-stable[The FreeBSD Handbook] for more information about getting and using FreeBSD-CURRENT. | See extref:{handbook}[The FreeBSD Handbook, current-stable] for more information about getting and using FreeBSD-CURRENT. | ||||
Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. | Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. | ||||
Chances of this can be minimized somewhat by subscribing to the {freebsd-announce} and the {freebsd-current} lists, where discussions on the current state of the system take place. | Chances of this can be minimized somewhat by subscribing to the {freebsd-announce} and the {freebsd-current} lists, where discussions on the current state of the system take place. | ||||
Context not available. | |||||
==== 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 extref:{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. | ||||
Context not available. | |||||
This section outlines the process to follow to keep your ports up to date. | This section outlines the process to follow to keep your ports up to date. | ||||
This is an overview. | This is an overview. | ||||
More information about upgrading a port is available in the link:{porters-handbook}[Porter's Handbook]. | More information about upgrading a port is available in the extref:{porters-handbook}[Porter's Handbook]. | ||||
[.procedure] | [.procedure] | ||||
==== | ==== | ||||
Context not available. | |||||
. Submit changes | . 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. | 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 link:{problem-reports}[Writing FreeBSD Problem Reports] for information on how to write a really good PR. | Please refer to extref:{problem-reports}[Writing FreeBSD Problem Reports] for information on how to write a really good PR. | ||||
+ | + | ||||
[NOTE] | [NOTE] | ||||
====== | ====== | ||||
Please do not submit a man:shar[1] archive of the entire port; instead, use man:git-format-patch[1] or man:diff[1] `-ruN`. | Please do not submit a man:shar[1] archive of the entire port; instead, use man:git-format-patch[1] or man:diff[1] `-ruN`. | ||||
In this way, committers can much more easily see exactly what changes are being made. | In this way, committers can much more easily see exactly what changes are being made. | ||||
The Porter's Handbook section on link:{porters-handbook}#port-upgrading[Upgrading] has more information. | The Porter's Handbook section on extref:{porters-handbook}[Upgrading, port-upgrading] has more information. | ||||
====== | ====== | ||||
. Wait | . Wait | ||||
+ | + | ||||
Context not available. | |||||
[[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 extref:{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. | extref:{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]. | ||||
Context not available. | |||||
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 extref:{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. | ||||
Context not available. |