diff options
Diffstat (limited to 'documentation/content/en/articles/contributing/_index.adoc')
| -rw-r--r-- | documentation/content/en/articles/contributing/_index.adoc | 54 |
1 files changed, 30 insertions, 24 deletions
diff --git a/documentation/content/en/articles/contributing/_index.adoc b/documentation/content/en/articles/contributing/_index.adoc index 4472701eaf..adbd9bd8ba 100644 --- a/documentation/content/en/articles/contributing/_index.adoc +++ b/documentation/content/en/articles/contributing/_index.adoc @@ -19,20 +19,26 @@ tags: ["Contributing", "FreeBSD", "Non-Programmer Tasks", "Programmer Tasks"] :sectnumlevels: 6 :source-highlighter: rouge :experimental: - -ifeval::["{backend}" == "html5"] -include::shared/en/mailing-lists.adoc[] -include::shared/en/urls.adoc[] +:images-path: articles/contributing/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +:imagesdir: ../../../images/{images-path} +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../shared/asciidoctor.adoc[] endif::[] - -ifeval::["{backend}" == "pdf"] -include::../../../../shared/en/mailing-lists.adoc[] -include::../../../../shared/en/urls.adoc[] endif::[] -ifeval::["{backend}" == "epub3"] -include::../../../../shared/en/mailing-lists.adoc[] -include::../../../../shared/en/urls.adoc[] +ifndef::env-beastie[] +include::../../../../../shared/asciidoctor.adoc[] endif::[] [.abstract-title] @@ -76,7 +82,7 @@ The Project includes documentation writers, Web designers, and support people. 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). -. 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. [[ongoing-programmer-tasks]] @@ -119,7 +125,7 @@ Whether you are looking for an ongoing role, or a fun challenge for a rainy day, 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>>. * 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>>. @@ -139,7 +145,7 @@ Contributions to the system generally fall into one or more of the following 5 c 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}. -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]. Try to fill-in each field of the bug report. @@ -151,19 +157,19 @@ When patches are a lot larger than 20KB, consider compressing them (eg. with man 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. -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 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. === 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. 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. 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. @@ -280,7 +286,7 @@ The FreeBSD Ports Monitoring System (portsmon) is currently not working due to l ==== How to adopt the 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._ You may request maintainership of any unmaintained port as soon as you wish. @@ -331,7 +337,7 @@ As a maintainer, you will need to manage the following challenges: 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 link:{porters-handbook}[Porter's Handbook]. +More information about upgrading a port is available in the extref:{porters-handbook}[Porter's Handbook]. [.procedure] ==== @@ -361,13 +367,13 @@ Thoroughly review and test your 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. -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] ====== 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. -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 + @@ -550,9 +556,9 @@ By this, we mean that there are unresolved problems or pending updates that have [[resources]] === 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. The https://bugs.freebsd.org/bugzilla/query.cgi[Problem Report database]. @@ -569,7 +575,7 @@ Documentation is located at the https://github.com/freebsd/poudriere[poudriere g 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 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. It is a good place to ask for help. |