os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

contributing and contributing-ports: combine them

Browse source 
- 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
This commit is contained in:
Eitan Adler 2015-04-06 05:11:49 +00:00
parent a7ecf541de
commit ce168f063c
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=46482
17 changed files with 767 additions and 4771 deletions
de_DE.ISO8859-1/articles
Makefile
contributing-ports
Makefilearticle.xml
en_US.ISO8859-1/articles
Makefile
contributing-ports
Makefilearticle.xml
contributing
article.xml
fr_FR.ISO8859-1/articles
Makefile
contributing-ports
Makefilearticle.xml
ja_JP.eucJP/articles
Makefile
nl_NL.ISO8859-1/articles
Makefile
contributing-ports
Makefilearticle.xml
pt_BR.ISO8859-1/articles
Makefile
contributing-ports
Makefilearticle.xml

1
de_DE.ISO8859-1/articles/Makefile
View file

@ -6,7 +6,6 @@
# basiert auf: 1.42
SUBDIR = contributing
gUBDIR+= contributing-ports
SUBDIR+= explaining-bsd
SUBDIR+= freebsd-update-server
SUBDIR+= nanobsd

24
de_DE.ISO8859-1/articles/contributing-ports/Makefile
View file

@ -1,24 +0,0 @@
#
# The FreeBSD Documentation Project
# The FreeBSD German Documentation Project
#
# $FreeBSD$
# $FreeBSDde: de-docproj/articles/contributing-ports/Makefile,v 1.1 2007/07/11 08:21:55 jkois Exp $
# basiert auf: 1.1
#
# Article: Zu den Ports beitragen
DOC?= article
FORMATS?= html html-split
WITH_ARTICLE_TOC?= YES
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.xml
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

907
de_DE.ISO8859-1/articles/contributing-ports/article.xml
View file

@ -1,907 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
<!-- The FreeBSD Documentation Project
The FreeBSD German Documentation Project
$FreeBSD$
$FreeBSDde: de-docproj/articles/contributing-ports/article.xml,v 1.11 2011/12/24 14:32:22 bcr Exp $
basiert auf: 1.9
-->
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="de">
<info><title>Zur FreeBSD Ports-Sammlung beitragen</title>
<abstract>
<para>Dieser Artikel beschreibt, wie man zur FreeBSD
Ports-Sammlung beitragen kann.</para>
<para><emphasis>Übersetzt von Martin Wilke</emphasis>.</para>
</abstract>
<authorgroup>
<author><personname><firstname>Sam</firstname><surname>Lawrance</surname></personname></author>
<author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author>
</authorgroup>
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
<pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
</info>
<indexterm><primary>Ports, beitragen</primary></indexterm>
<sect1>
<title>Einleitung</title>
<para>Die Ports-Sammlung ist ständig in Bearbeitung. Wir
wollen unseren Benutzern eine einfach zu verwendende,
aktuelle und qualitativ hochwertige Quelle für Software
von Drittanbietern bereitstellen. Deshalb suchen wir immer
Personen, die etwas von ihrer Zeit aufwenden können,
um uns dabei zu helfen.</para>
<para>An der Ports-Sammlung zu arbeiten
ist ein hervorragender Weg, um zu helfen und dem Projekt
etwas zurück zu geben. Egal, ob Sie eine dauerhafte
Funktion oder eine kleine Aufgabe für einen
regnerischen Tag suchen - wir würden uns über
Ihre Hilfe freuen!</para>
<para>Als Freiwillige/r setzen Sie sich selbst Grenzen.
Sie sollten sich aber immer bewusst sein, dass andere
Mitglieder der &os; Community möglicherweise auch
etwas von Ihnen erwarten. Sie sollten dies auf jeden
Fall in Ihre Entscheidung mit einbeziehen.</para>
</sect1>
<sect1 xml:id="what-contribute">
<title>Was Sie tun können, um uns zu helfen</title>
<para>Um die Ports-Sammlung aktuell und in einem sauberen Zustand
zu halten, sind viele Dinge zu erledigen:</para>
<itemizedlist>
<listitem>
<para>Finden Sie eine begehrte oder nützliche
Software und <link linkend="create-port">erstellen Sie einen
Port</link>.</para>
</listitem>
<listitem>
<para>Es gibt eine große Anzahl von Ports, die keinen
Maintainer haben. Werden Sie Maintainer und <link linkend="adopt-port">betreuen Sie einen Port</link>.</para>
</listitem>
<listitem>
<para>Wenn Sie einen Port erstellt haben oder betreuen,
vergessen Sie nicht, <link linkend="maintain-port">welche Aufgaben ein Maintainer
hat</link>.</para>
</listitem>
<listitem>
<para>Wenn Sie nur eine kleine Aufgabe suchen,
könnten Sie beispielsweise <link linkend="fix-broken">einen Bug oder defekten
Port fixen</link>.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="create-port">
<title>Erstellen Sie einen neuen Port</title>
<para>Es gibt ein eigenes Handbuch, das beim Erstellen
(und Aktualisieren) von Ports hilft. Es heißt <link xlink:href="&url.books.porters-handbook;">Porter-Handbuch</link>.
Das Porter-Handbuch ist die beste Referenz, um mit
dem Ports-System zu arbeiten. Es enthält Details
darüber, wie das Ports-System funktioniert und wie
man mit/an den Ports arbeitet.</para>
</sect1>
<sect1 xml:id="adopt-port">
<title>Übernahme eines nicht betreuten Ports</title>
<sect2>
<title>Einen nicht betreuten Port aussuchen</title>
<para>Die Betreuung eines Ports ist ein guter Weg zu helfen.
Nicht betreute Ports bleiben nur aktuell und stabil, wenn ein
Freiwilliger dafür sorgt. Es gibt eine grosse Anzahl
nicht betreuter Ports, daher ist es eine gute Idee für
den Einstieg, einen verwaisten Port zu übernehmen, den
Sie auch regelmässig selbst verwenden.</para>
<para>Nicht betreute Ports haben als <varname>MAINTAINER</varname>
den Wert <literal>ports@FreeBSD.org</literal>. Eine Liste
der derzeit nicht betreuten Ports sowie Informationen zu deren
aktuellen Fehlern und Problemen können Sie unter <link xlink:href="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">
&os; Ports Monitoring System</link> einsehen.</para>
<para>Einige Ports beeinflussen durch Abhängigkeiten
und <quote>Slave-Port-Beziehungen</quote> eine grosse
Anzahl anderer Ports. Generell ist es ratsam, dass
Maintainer über ein Mindestmaß an Erfahrung
verfügen, bevor Sie derartige Ports betreuen.</para>
<para>Um herauszufinden, ob ein Port Abhängigkeiten
oder Slave-Ports hat, können Sie im
<quote>Master-Port-Index</quote>
<filename>/usr/ports/INDEX</filename> nachsehen. (Der Name der
Datei kann bei den einzelnen Releases von FreeBSD variieren,
z.B. <filename>INDEX-8</filename>). Einige Ports haben
bedingte Abhängigkeiten, die nicht im Standard-Index
<filename>INDEX</filename> zu finden sind. Wir erwarten, dass
Sie in der Lage sind, solche Ports zu erkennen, indem Sie sich
die <filename>Makefile</filename>s anderer Ports
ansehen.</para> </sect2>
<sect2>
<title>Wie man einen Port übernimmt</title>
<para>Bitte vergewissern Sie sich, dass Sie die
<link linkend="maintain-port">Aufgaben eines
Maintainers</link> verstanden haben. Lesen Sie bitte auch
das <link xlink:href="&url.books.porters-handbook;">Porter-Handbuch</link>.
<emphasis>Übernehmen Sie nicht mehr Aufgaben, als Sie
bewältigen können</emphasis>.</para>
<para>Sie können einen nicht reservierten Port jederzeit
übernehmen, die Entscheidung liegt bei Ihnen. Wenn
Sie dazu bereit sind, setzen Sie <varname>MAINTAINER</varname>
auf Ihre E-Mail-Adresse und reichen einen Problembericht (PR)
mit den von Ihnen vorgenommenen Änderungen ein. Wenn beim
Kompilieren des Ports Fehler auftreten oder eine
Aktualisierung notwendig ist, können Sie derartige Änderungen
dem selben PR beifügen. Das ist sehr hilfreich, weil sich
viele Committer weigern, die Wartung eines Ports zu übergeben,
wenn jemand nicht die nötige Erfahrung mit &os; vorweisen
kann. Das Einreichen von PRs, die Kompilierfehler beheben
oder Ports aktualisieren, ist der beste Weg, um Erfahrung zu
sammeln.</para>
<para>Erstellen Sie Ihren PR mit der
<foreignphrase>category</foreignphrase>
<literal>ports</literal> und der
<foreignphrase>class</foreignphrase>
<literal>change-request</literal>. Ein Committer wird Ihren
PR analysieren, die Änderungen committen und danach den PR
abschließen. Manchmal kann dieser Prozess eine Weile dauern
(auch Committer sind "nur" freiwillige Helfer!).</para>
</sect2>
</sect1>
<sect1 xml:id="maintain-port">
<title>Die Herausforderung als Ports-Maintainer</title>
<para> Dieser Abschnitt erklärt, warum Ports betreut werden
müssen, und beschreibt die Pflichten eines
Ports-Maintainers.</para>
<sect2 xml:id="why-maintenance">
<title>Warum müssen Ports betreut werden?</title>
<para>Einen Port zu erstellen ist eine einmalige Sache.
Sicherzustellen, dass ein Port aktuell ist und auch in Zukunft
funktioniert, erfordert hingegen eine laufende Betreuung
und einen nicht zu unterschätzenden Arbeitsaufwand.
Maintainer sind Personen, die einen Teil ihrer Zeit dazu
verwenden, einen Port für andere FreeBSD-Anwender aktuell
und einfach installierbar zu halten.</para>
<para>Der wichtigste Grund für die Betreuung von Ports
ist der Wunsch, der &os;-Community die neueste und beste
Drittanbieter-Software zur Verfügung zu stellen. Eine
zusätzliche Herausforderung ist die Aufrechterhaltung
der Funktionalität einzelner Ports innerhalb der
sich verändernden Ports-Sammlung.</para>
<para>Als Ports-Maintainer werden Sie folgende
Herausforderungen meistern:</para>
<itemizedlist>
<listitem>
<formalpara>
<title>Neue Software-Versionen und
Aktualisierungen</title>
<para>Neue Versionen und Aktualisierung von bereits
portierter Software werden kontinuierlich
veröffentlicht und müssen in die Ports-Sammlung
integriert werden, um aktuelle Software ausliefern zu
können.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Änderungen an Abhängigkeiten ihres
Ports</title>
<para>Wenn bedeutende Änderungen an den
Abhängigkeiten Ihres Ports gemacht wurden,
kann es vonnöten sein, diesen zu aktualisieren,
damit er weiterhin korrekt funktioniert.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Änderungen an abhängigen Ports</title>
<para>Wenn andere Ports von einem Ihrer betreuten
Ports abhängig sind, müssen Änderungen
eventuell mit anderen Maintainern abgesprochen
werden.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Zusammenwirken von anderen Benutzern,
Maintainern und Entwicklern</title>
<para>Ein Teil der Aufgabe eines Maintainers ist es,
Support zu leisten. Damit ist kein Hauptsupport
für die Software gemeint (wir haben allerdings nichts
dagegen, wenn Sie sich dennoch entscheiden, dies zu
tun). Ihre Aufgabe ist aber, sich um &os;-spezifische
Fragen zu Ihren Ports zu kümmern.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Bugs finden</title>
<para>Eine Portierung könnte vielleicht von
&os;-spezifischen Bugs beeinflusst werden. In einem
solchen Fall ist es Ihre Aufgabe, den Fehler zu finden
und zu beheben. Daher sollten Sie Ihren Port umfassend
testen, um derartige Probleme zu entdecken, bevor Sie
einen Port in die Ports-Sammlung aufnehmen.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Änderungen an Ports, Infrastruktur und
Lizenzen</title>
<para>Gelegentlich werden die Werkzeuge für das Bauen von
Ports erneuert oder es wird ein neuer Vorschlag zur
Infrastruktur der Ports-Sammlung gemacht. Sie sollten
von diesen Änderungen wissen, falls Ihre Ports betroffen
sind und aktualisiert werden müssen.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Änderungen am Basissystem</title>
<para>&os; ist in ständiger Entwicklung.
Änderungen an Software, Bibliotheken, dem Kernel
oder sogar Lizenzänderungen können
Änderungsbedarf an den Ports auslösen.</para>
</formalpara>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Aufgaben eines Maintainers</title>
<sect3>
<title>Halten Sie Ihre Ports aktuell</title>
<para>Dieser Abschnitt bietet einen kurzen Überblick zu
diesem Thema. Ausführliche Informationen zur
Aktualisierung von Ports finden Sie im <link xlink:href="&url.books.porters-handbook;">Porter-Handbuch</link>.</para>
<procedure>
<step>
<title>Achten Sie auf Aktualisierungen</title>
<para>Überwachen Sie Ihr Programm auf neue Versionen
der Software, Aktualisierungen und Security-Fixes.
Ankündigungen in Mailinglisten oder auf
Nachrichtenseiten im Internet sind dabei sehr
hilfreich. Manchmal werden Sie von Benutzern gefragt
werden, wann Ihr Port eine Aktualisierung bekommt.
Wenn Sie mit anderen Dingen beschäftigt sind oder aus
sonstigen Gründen keine Aktualisierung
bereitstellen können, fragen Sie den Benutzer
doch einfach, ob er Ihnen bei der Aktualisierung
helfen möchte.</para>
<para>Es kann auch vorkommen, dass Sie eine automatisch
generierte E-Mail vom
<literal>&os; Ports Version Check</literal>
bekommen, die Sie darüber informiert, dass eine
aktuellere Version des Distfiles Ihres Ports
verfügbar ist. Weitere Informationen über
dieses System (inklusive einer Erklärung, wie Sie
derartige E-Mails in Zukunft vermeiden können) finden
Sie ebenfalls in einer solchen Nachricht.</para>
</step>
<step>
<title>Aufnehmen von Änderungen</title>
<para>Wenn verfügbar, integrieren Sie die
Veränderungen in den Port. Sie müssen in der
Lage sein, einen Patch zwischen dem alten und dem neuen
Port zu generieren.</para>
</step>
<step>
<title>Nachprüfung und Test</title>
<para>Überprüfen und testen Sie
ihre Änderungen gründlich:</para>
<itemizedlist>
<listitem>
<para>Kompilieren, installieren und testen Sie
ihren Port auf so vielen Plattformen und
Architekturen, wie Sie können. Es kommt sehr
häufig vor, dass ein Port auf einem
Entwicklungszweig oder einer Plattform
funktioniert, auf einer anderen Plattform aber
Fehler erzeugt.</para>
</listitem>
<listitem>
<para>Stellen Sie sicher, dass die
Abhängigkeiten ihres Ports vollständig
sind. Die empfohlene Vorgehensweise dafür
ist, dass Sie ihre eigenen Ports in einer
<application>Tinderbox</application> kompilieren.
Weitere Informationen zu diesem Thema finden Sie im
Abschnitt <link linkend="resources">Ressourcen</link>
dieses Artikels.</para>
</listitem>
<listitem>
<para>Stellen Sie sicher, dass die Liste der zu
installierenden Dateien und Verzeichnisse aktuell
ist.</para>
</listitem>
<listitem>
<para>Überprüfen Sie ihren Port mit
&man.portlint.1;. Sehen Sie sich dazu den Abschnitt
<link linkend="resources">Ressourcen</link> an.
Dieser enthält wichtige Informationen zum
Einsatz von <application>portlint</application>.</para>
</listitem>
<listitem>
<para>Achten Sie darauf, dass Änderungen an Ihrem
Port nicht den Bau eines anderen Ports verhindern.
Ist dies der Fall, besprechen Sie die von Ihnen
durchgeführten Änderungen mit den
Maintainern der betroffenen Ports. Dies ist
besonders dann wichtig, wenn Ihre Aktualisierung die
<quote>Shared Library</quote>-Version ändert; in
diesem Fall werden Sie für die abhängigen Ports
einen <varname>PORTREVISION</varname>-Bump
benötigen, damit diese von automatisierten
Werkzeugen wie <application>portmaster</application>
oder &man.portupgrade.1; auf dem neuesten Stand
gehalten werden.</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Änderungen einreichen</title>
<para>Reichen Sie ihre Aktualisierungen mit einem PR ein,
welcher die Änderungen erklärt und einen Patch
enthält, der die Änderungen zwischen dem
Original und Ihrer aktualisierten Version umfasst.
Lesen Sie bitte zuerst den Artikel <link xlink:href="&url.articles.problem-reports.en;">Writing FreeBSD
Problem Reports</link>, der das korrekte Einreichen
von Problemberichten beschreibt.</para>
<note>
<para>Bitte schicken Sie kein &man.shar.1;-Archiv
des gesamten Ports. Benutzen Sie stattdessen
&man.diff.1; <literal>-ruN</literal>. Auf diese Art
und Weise können Committer viel einfacher erkennen,
welche Änderungen vorgenommen wurden. Das
Porter-Handbuch enthält viele nützliche Informationen
zum <link xlink:href="&url.books.porters-handbook;/port-upgrading.html">Upgrading</link>
eines Ports.</para>
</note>
</step>
<step>
<title>Warten</title>
<para>Es kann nur sehr wenig Zeit vergehen, bis sich ein
Committer mit Ihrem PR befasst. Es kann aber auch
mehrere Wochen dauern, bis eine Reaktion erfolgt - haben
Sie bitte Geduld.</para>
</step>
<step>
<title>Feedback geben</title>
<para>Wenn ein Committer Probleme in Ihren Änderungen
entdeckt, wird er Sie darüber informieren. Eine
schnelle Reaktion Ihrerseits ist hilfreich, um Ihren PR
rasch bearbeiten zu können. Außerdem hilft
es Ihnen, den Faden nicht zu verlieren, wenn Sie
versuchen, aufgetretene Probleme zu lösen.</para>
</step>
<step>
<title>Und zuletzt...</title>
<para>Ihre Änderungen werden übermittelt und im
Anschluss daran wird Ihr Port aktualisiert. Der
betreffende PR wird danach vom Committer geschlossen.
Herzlichen Glückwunsch, Sie haben es geschafft!</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Stellen Sie sicher, dass Ihre Ports den Buildprozess
weiterhin erfolgreich durchlaufen</title>
<para>Dieser Abschnitt beschreibt, wie Sie Probleme entdecken
und beheben, die ihre Ports daran hindern, den Buildprozess
erfolgreich zu durchlaufen.</para>
<para>&os; garantiert nur für die
<literal>-STABLE</literal>-Zweige, dass die
Ports-Sammlung korrekt funktioniert. Sie sollten
<literal>7-STABLE</literal> oder
<literal>8-STABLE</literal> benutzen, wobei der letztere
Zweig bevorzugt wird. Theoretisch sollte es ausreichen, das
aktuelle <quote>Stable Release</quote> des jeweiligen
<literal>STABLE</literal>-Zweigs einzusetzen (da die ABIs
in der Regel nicht geändert werden), es empfiehlt sich
aber, dem jeweiligen STABLE-Zweig zu folgen.</para>
<para>Seit die Mehrheit von &os;-Installationen auf
PC-kompatiblen Maschinen arbeitet
(<literal>i386</literal>-Architektur) erwarten wir, dass Ihr
Port auf dieser Architektur funktioniert. Ebenfalls
bevorzugen wir es, wenn Ports nativ auf der
<literal>amd64</literal>-Architektur funktionieren. Es ist
durchaus in Ordnung, um Hilfe zu fragen, wenn Sie keine
solche Maschine besitzen.</para>
<note>
<para>Häufige Fehler beim Umgang mit
nicht-<literal>i386</literal> Maschinen entstehen,
weil Programmierer ür Instanzen und Pointer
<literal>int</literal>s verwendeten, oder weil der
relativ simple <application>gcc</application>-Compiler
genutzt wird. Immer mehr Programmautoren
überarbeiten ihren Code, um diese Fehler zu
beseitigen &mdash; wenn der Programmautor seinen Code
allerdings nicht aktiv betreut, müssen Sie dies
eventuell selbst in die Hand nehmen.</para>
</note>
<para>Sie sollten die folgende Liste durchgehen, um
sicherzustellen, dass Ihr Port gebaut werden kann:</para>
<procedure>
<step>
<title>Achten Sie auf Build-Fehler</title>
<para>Überprüfen Sie regelmäßig den Ports
Building Cluster <link xlink:href="http://pointyhat.FreeBSD.org">pointyhat</link>
und den <link xlink:href="http://www.portscout.org">Distfiles-Scanner</link>,
um festzustellen, ob einer Ihrer Ports nicht gebaut oder
die Distfiles nicht geladen werden können (lesen Sie den
Abschnitt <link linkend="resources">Ressourcen</link>
dieses Artikels für weitere Informationen zu diesen
Systemen). Fehlerberichte kommen eventuell auch von
anderen Benutzern oder als automatisierte Meldungen per
E-Mail.</para>
</step>
<step>
<title>Sammeln Sie Informationen</title>
<para>Wenn Sie ein Problem entdecken, benötigen Sie
als Erstes Informationen, die Ihnen dabei helfen, dieses
Problem zu beheben. Build-Fehler, die von
<literal>pointyhat</literal> gemeinsam mit Logdateien
verschickt werden, zeigen Ihnen, an welcher Stelle
der Fehler auftritt. Wenn Ihnen ein Fehler von
einem anderen Benutzer mitgeteilt wird, fragen
Sie nach, ob er bereit ist, ihnen Informationen
zukommen zu lassen, die eventuell bei der Diagnose
des Problems helfen können, wie z.B.:</para>
<itemizedlist>
<listitem>
<para>Build-Logs.</para>
</listitem>
<listitem>
<para>Die Werkzeuge und Optionen, mit denen ein Port
gebaut wurde (inklusive der Optionen in
<filename>/etc/make.conf</filename>).</para>
</listitem>
<listitem>
<para>Eine Liste installierter Pakete auf dem
System kann mit &man.pkg.info.1; erstellt
werden.</para>
</listitem>
<listitem>
<para>Die &os;-Version, welche benutzt wird, kann
mit &man.uname.1;<command> -a</command>
ermittelt werden.</para>
</listitem>
<listitem>
<para>Wann die Ports-Sammlung das letzte Mal
aktualisiert wurde.</para>
</listitem>
<listitem>
<para>Wann die <filename>INDEX</filename>-Datei
zuletzt aktualisiert wurde.</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Suchen und finden Sie eine Lösung</title>
<para>Leider gibt es keinen allgemein gültigen
Weg, dies zu tun. Denken Sie daran: Wenn Probleme
auftauchen bitten Sie einfach jemanden um Hilfe!
Ein guter Anfang ist die Mailingliste &a.ports;.
Auch die Entwickler der Software selbst sind oft sehr
hilfreich.</para>
</step>
<step>
<title>Änderungen übermitteln</title>
<para>Genau wie beim Aktualisieren eines Ports
sollten Änderungen integriert, geprüft
und getestet werden. Reichen Sie Ihre Arbeit als
PR ein und geben Sie Feedback, falls dies notwendig
ist.</para>
</step>
<step>
<title>Patches an Programmautoren senden</title>
<para>Manchmal müssen Sie Patches erstellen, um
einen Port unter FreeBSD zum Laufen zu bekommen.
Einige (aber nicht alle) Programmautoren nehmen
diese Patches in Ihren Code für das nächste
Release auf. Dies kann den Benutzern anderer
BSD-Systeme helfen und einiges an unnötiger Mehrarbeit
ersparen. Bitte betrachten Sie das Versenden von
verwertbaren Patches an die Autoren als ein Gebot der
Höflichkeit.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Ermitteln Sie Bug-Reports und PRs, die Ihre Ports
betreffen</title>
<para>&os;-spezifische Bugs werden meistens durch falsche
Annahmen über Build- und Laufzeitumgebungen, die
nicht zu &os; passen, verursacht. Derartige Probleme zu
entdecken ist oft sehr schwierig, glücklicherweise
sind derartige Probleme aber nicht sehr häufig.</para>
<para>Folgende Schritte sind notwendig, um sicherzustellen,
dass ihr Port weiterhin wie gewünscht funktioniert:</para>
<procedure>
<step>
<title>Antworten Sie auf Bug-Reports</title>
<para>Bugs können Ihnen als E-Mail durch die <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
GNATS Problem Report database</link> zugestellt
werden, Sie können Ihnen aber auch direkt von
Benutzern gemeldet werden.</para>
<para>Sie sollten innerhalb von 14 Tagen auf PRs und andere
Berichte antworten. Versuchen Sie schnellstmöglich
zu antworten, selbst wenn Sie nur mitteilen können,
dass Sie noch etwas Zeit brauchen, bevor Sie den PR
bearbeiten können.</para>
<para>Sollten Sie nicht innerhalb von 14 Tagen geantwortet
haben, darf jeder Committer via
<literal>maintainer-timeout</literal> auf einen PR, den
Sie nicht beantwortet haben, reagieren.</para>
</step>
<step>
<title>Sammeln Sie Informationen</title>
<para>Wenn mit dem Bug-Report nicht auch gleichzeitig eine
Lösung übermittelt wird, müssen Sie zuerst
die zum Beheben des Problems nötigen Informationen
sammeln.</para>
<para>Wenn der Fehler reproduzierbar ist, können Sie
die meisten Informationen selbst sammeln. Wenn nicht,
bitten Sie die Person, die den Fehler gefunden hat,
diese Informationen für Sie zu sammeln:</para>
<itemizedlist>
<listitem>
<para>Eine genaue Beschreibung dessen, was Er/Sie
getan hat, den erwarteten Programmverlauf und den
tatsächlichen Ablauf.</para>
</listitem>
<listitem>
<para>Eine Kopie der Eingabedaten, die den Fehler
auslösen.</para>
</listitem>
<listitem>
<para>Informationen über das System, auf dem der
Port gebaut und ausgeführt wird, etwa die Liste
der installierten Pakete sowie die Ausgabe von
&man.env.1;.</para>
</listitem>
<listitem>
<para>Core dumps.</para>
</listitem>
<listitem>
<para>Stack traces.</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Schließen Sie falsche Reports aus</title>
<para>Einige Fehlerberichte sind eventuell falsch. Es
kommt vor, dass ein Programm falsch benutzt wird.
Weiterhin können installierten Pakete veraltet sein und
müssten einfach nur aktualisiert werden. Manchmal ist
ein gemeldeter Fehler auch nicht &os;-spezifisch. In
diesem Fall melden Sie den Fehler den derzeitigen
Entwicklern der Software. Wenn Sie in der Lage sind,
den Fehler zu beheben, können Sie dies natürlich
trotzdem tun und den Entwicklern Ihren Patch zukommen
lassen.</para>
</step>
<step>
<title>Lösungen finden</title>
<para>Bei Build-Fehlern werden Sie eine Lösung finden
müssen. Denken Sie daran zu fragen, wenn Sie nicht
weiterkommen!</para>
</step>
<step>
<title>Änderungen einreichen oder annehmen</title>
<para>Genau so wie bei der Aktualisierung eines Ports
sollten Sie alle Änderungen zuvor analysieren und
testen, um Sie danach als neuen PR (oder als
Folgebericht (<foreignphrase>follow-up</foreignphrase>),
falls ein PR zu diesem Problem bereits existiert)
einzureichen. Falls ein anderer Anwender Änderungen
für einen PR eingereicht hat, können Sie einen
Folgebericht erstellen, mit dem Sie die vorgeschlagenen
Änderungen akzeptieren oder (mit einer
Begründung) ablehnen.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Support leisten</title>
<para>Teilaufgabe eines Maintainers ist es, Support zu leisten
&mdash; nicht den Hauptsupport für die Software &mdash;
aber für seine Ports und &os;-spezifische Schlampereien
und Probleme. Benutzer kontaktieren Sie vielleicht wegen
Fragen, Anregungen, Problemen und Patches. Die meiste Zeit
werden sich derartige Mitteilungen spezifisch auf &os;
beziehen.</para>
<para>Manchmal müssen Sie eventuell ihre diplomatischen
Fähigkeiten auffrischen und Benutzer freundlich an die
korrekten Anlaufstellen für den Hauptsupport verweisen.
Nur selten werden Sie auf eine Person treffen, die Sie
fragt, warum die <literal>RPM</literal>s nicht aktuell sind
oder wie Sie die Software unter <literal>Foo Linux</literal>
zum Laufen bringen. Ergreifen Sie die Gelegenheit und
berichten Sie, dass Ihr Port aktuell ist (natürlich nur,
wenn er es auch tatsächlich ist) und schlagen Sie vor,
einmal &os; auszuprobieren.</para>
<para>Wenn Sie Glück haben, werden Benutzer und Entwickler
gelegentlich daran denken, dass Sie eine sehr
beschäftigte Person sind, deren Zeit nicht
unerschöpflich, sondern kostbar ist, und werden vielleicht
ein Teil Ihrer Arbeit für Sie übernehmen.
Beispielsweise könnten sie:</para>
<itemizedlist>
<listitem>
<para>Einen PR einreichen oder Ihnen Patches
schicken.</para>
</listitem>
<listitem>
<para>Einen vorhandenen PR untersuchen und eventuell einen
Patch dazu erstellen.</para>
</listitem>
<listitem>
<para>Ihnen Änderungen für Ihre Ports zusenden.</para>
</listitem>
</itemizedlist>
<para>In diesem Fall ist ihre Hauptaufgabe zeitnahes
Antworten. Der Timeout für nicht ansprechbare Maintainer
beträgt auch hier wieder 14 Tage. Nach dieser Periode
können Änderungen ohne ihre Prüfung eingereicht
werden. Diese Personen haben sich die Arbeit gemacht, etwas
für Sie zu übernehmen, versuchen Sie daher, möglichst
rasch zu antworten. Danach überprüfen, akzeptieren,
verändern oder diskutieren Sie diese Änderungen mit
den betroffenen Personen so schnell wie möglich.</para>
<para>Wenn Sie vermitteln können, dass Sie deren Arbeit
zu schätzen wissen (und das sollten Sie), dann werden Sie
eine bessere Chance haben, dass diese Personen ihnen auch in
Zukunft etwas Arbeit abnehmen. <!-- smiley -->:-)</para>
</sect3>
</sect2>
</sect1>
<sect1 xml:id="fix-broken">
<title>Defekte Ports finden und reparieren</title>
<para>Es gibt zwei wirklich gute Anlaufstellen, um Ports
zu finden, die ihre Aufmerksamkeit benötigen.</para>
<para>Sie können das <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">Web
Interface der Problem Reports-Datenbank</link> nutzen, um nach
ungelösten Problemen zu suchen. Die Mehrheit der PRs, die
zu Ports eingereicht werden, betreffen Aktualisierungsprobleme,
aber mit ein bißchen Recherche in den Übersichten
und Zusammenfassungen sollten Sie das eine oder andere
Interessante finden. (Die Kategorie <literal>sw-bug</literal>
ist ein guter Platz, um mit der Arbeit zu beginnen).</para>
<para>Die zweite Anlaufstelle ist das <link xlink:href="http://portsmon.FreeBSD.org/">&os; Ports Monitoring
System</link>. Hier können Sie nicht betreute Ports mit
Build-Fehlern und Ports, die als <varname>BROKEN</varname>
gekennzeichnet sind, finden. Natürlich ist es auch in
Ordnung, Änderungen an betreuten Ports zu machen. Denken
Sie aber bitte daran, den Maintainer zuvor davon zu
informieren, da dieser möglicherweise bereits an diesem
Problem arbeitet.</para>
<para>Sobald Sie einen Fehler oder ein Problem gefunden haben,
sammeln Sie dazu Informationen und versuchen Sie, den Fehler
zu analysieren und zu beheben! Wenn sich bereits ein PR mit
diesem Problem befasst, knüpfen Sie dort an. Ansonsten
reichen Sie einen neuen PR ein. Die von Ihnen vorgeschlagenen
Änderungen werden danach geprüft. Sind diese in
Ordnung, werden Sie danach committed.</para>
</sect1>
<sect1 xml:id="mortal-coil">
<title>Sagen Sie Bescheid, wenn Sie einen Port nicht mehr
betreuen möchten</title>
<para>So wie Ihre Interessen sich ändern, haben Sie
vielleicht irgendwann auch nicht mehr die Zeit, weiterhin
einige (oder alle) Ihrer Ports zu betreuen. Das ist
verständlich. Bitte lassen Sie es uns wissen, wenn Sie
keine Zeit oder kein Interesse mehr daran haben, Maintainer zu
sein oder einen Port selbst nicht mehr benutzen und deshalb
gerne abgeben wollen. Nur auf diese Art und Weise können
wir vorankommen und anderen anbieten, an diesen Ports zu
arbeiten, ohne dass diese auf Ihre Antworten warten müssen.
Denken Sie daran: &os; ist ein Freiwilligen-Projekt. Wenn Ihnen
eine Aufgabe keinen Spaß mehr macht, ist es wahrscheinlich
an der Zeit, jemand anderen an Ihre Ports zu lassen.</para>
<para>In jedem Fall behält sich das Ports Management
Team (<literal>portmgr</literal>) das Recht vor, Ihnen den
Maintainer-Status abzuerkennen, wenn Sie für längere
Zeit nicht aktiv sind (derzeit liegt diese Grenze bei drei
Monaten). Damit ist gemeint, dass ungelöste Probleme oder
ausstehende Aktualisierungen in diesem Zeitraum nicht bearbeitet
wurden.</para>
</sect1>
<sect1 xml:id="resources">
<title>Ressourcen für Ports-Maintainer und Committer</title>
<para>Das <link xlink:href="&url.books.porters-handbook;">Porter-Handbuch</link>
ist Ihr <quote>Ratgeber zum Ports-System</quote> und sollte
stets in Ihrer Reichweite sein!</para>
<para>Der Artikel <link xlink:href="&url.articles.problem-reports.en;">Writing FreeBSD Problem
Reports</link> beschreibt, wie PRs formuliert und eingereicht
werden sollen. Allein im Jahr 2005 wurden mehr als 11.000 PRs
zu verschiedenen Ports eingereicht! Wenn Sie die Anweisungen
dieses Artikels befolgen, werden wir weniger Zeit benötigen,
um Ihre PRs zu bearbeiten.</para>
<para>Die <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
Problem Report Database</link>.</para>
<para><link xlink:href="http://pointyhat.FreeBSD.org/">Pointyhat</link>
ist der Ports Build Cluster. Sie können Pointyhat nutzen,
um nach Port-Buildlogs über alle Architekturen und
Haupt-Releases zu suchen.</para>
<para>Das <link xlink:href="http://portsmon.FreeBSD.org/">FreeBSD Ports Monitoring
System </link> kann verschiedene Informationen über Ports
enthalten, beispielsweise Build-Fehler und Problemberichte.
Als Ports-Maintainer können Sie hier den Buildstatus Ihres
Ports in Erfahrung bringen. Als Committer können Sie dort
defekte und unbetreute Ports finden, die gefixt werden
müssten.</para>
<para>Der <link xlink:href="http://www.portscout.org">&os; Ports
Distfile-Scanner</link> kann Ihnen die Ports anzeigen, deren
Distfiles nicht erreichbar sind. Sie können damit Ihre eigenen
Ports prüfen oder auch herauszufinden, ob die
<varname>MASTER_SITES</varname>-Einträge bestimmter Ports
nicht mehr aktuell sind.</para>
<para>Der <application>tinderbox</application>-Port ist die
gründlichste Lösung, um den Port während des ganzen
Prozesses der Installation, Paketerstellung und Deinstallation
zu testen. Das Programm bietet sowohl eine Kommandozeilen- als
auch eine Web-Schnittstelle. Weitere Informationen zu diesem
Port finden Sie im Verzeichnis
<filename>ports/ports-mgmt/tinderbox</filename> sowie auf der
<link xlink:href="http://tinderbox.marcuscom.com/">Tinderbox
Homepage</link>.</para>
<para>Mit &man.portlint.1; können Sie einen Port auf die
Einhaltung von stilistischen und funktionellen Richtlinien hin
überprüfen. Da es sich bei
<application>portlint</application> um eine heuristische
Anwendung handelt, sollten Sie dessen Ausgaben <emphasis>nur als
einen Ratgeber verwenden</emphasis>. Wenn
<application>portlint</application> zu umfangreiche Änderungen
vorschlägt, lesen Sie nochmal das <link xlink:href="&url.books.porters-handbook;">Porter-Handbuch</link>
oder bitten Sie jemanden um Rat.</para>
<para>Die Mailingliste &a.ports; ist für allgemeine Diskussionen
über Ports vorgesehen. Wenn Sie Hilfe benötigen
können Sie dort nachfragen. Sie können einzelne
Mailinglisten <link xlink:href="http://lists.freebsd.org/mailman/listinfo">
auch abonnieren oder in deren Archiven suchen und lesen</link>.
Die Mailinglisten &a.ports-bugs; und &a.cvs-ports; könnten
für Sie ebenfalls von Interesse sein.</para>
</sect1>
<index/>
</article>

1
en_US.ISO8859-1/articles/Makefile
View file

@ -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

19
en_US.ISO8859-1/articles/contributing-ports/Makefile
View file

@ -1,19 +0,0 @@
#
# $FreeBSD$
#
# Article: Contributing to the FreeBSD Ports Collection
DOC?= article
FORMATS?= html
WITH_ARTICLE_TOC?= YES
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.xml
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

811
en_US.ISO8859-1/articles/contributing-ports/article.xml
View file

@ -1,811 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info><title>Contributing to the FreeBSD Ports Collection</title>
<abstract>
<title>Abstract</title>
<para>This article describes the ways in which an individual
can contribute to the FreeBSD Ports Collection.</para>
</abstract>
<authorgroup>
<author><personname><firstname>Sam</firstname><surname>Lawrance</surname></personname></author>
<author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author>
</authorgroup>
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
<pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
</info>
<indexterm><primary>contributing to ports</primary></indexterm>
<sect1>
<title>Introduction</title>
<para>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.</para>
<para>Anyone can get involved, and there are lots of different
ways to do so. Contributing to ports is an excellent way to
help <quote>give&nbsp;back</quote> 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!</para>
<para>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.</para>
</sect1>
<sect1 xml:id="what-contribute">
<title>What you can do to help</title>
<para>There are a number of easy ways you can contribute to
keeping the ports tree up to date and in good working
order:</para>
<itemizedlist>
<listitem>
<para>Find some cool or useful software and
<link linkend="create-port"> create a port</link> for
it.</para>
</listitem>
<listitem>
<para>There are a large number of ports that have no
maintainer. Become a maintainer and
<link linkend="adopt-port">adopt a port</link>.</para>
</listitem>
<listitem>
<para>If you have created or adopted a port, be
aware of <link linkend="maintain-port">what you need to do
as a maintainer</link>.</para>
</listitem>
<listitem>
<para>When you are looking for a quick challenge you
could <link linkend="fix-broken">fix a bug or a broken
port</link>.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="create-port">
<title>Creating a new port</title>
<para>There is a separate document available to help guide you
through creating (and upgrading) a port called the <link xlink:href="&url.books.porters-handbook;">Porter's Handbook</link>.
The Porter's Handbook is the best reference to working with the
ports system. It provides details about how the ports system
operates and discusses recommended practices.</para>
</sect1>
<sect1 xml:id="adopt-port">
<title>Adopting an unmaintained port</title>
<sect2>
<title>Choosing an unmaintained port</title>
<para>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.</para>
<para>Unmaintained ports have their
<varname>MAINTAINER</varname> set to
<literal>ports@FreeBSD.org</literal>. A list of unmaintained
ports and their current errors and problem reports can be seen
at the <link xlink:href="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">&os;
Ports Monitoring System</link>.</para>
<para>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.</para>
<para>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</filename>. (The name of the file varies
by release of &os;; for instance,
<filename>INDEX-8</filename>.) Some ports have conditional
dependencies that are not included in a default
<filename>INDEX</filename> build. We expect you to be able to
recognize such ports by looking through other ports'
<filename>Makefile</filename>s.</para>
</sect2>
<sect2>
<title>How to adopt the port</title>
<para>First make sure you understand your
<link linkend="maintain-port">responsibilities as a
maintainer</link>. Also read the
<link xlink:href="&url.books.porters-handbook;">Porter's
Handbook</link>. <emphasis>Please do not commit yourself
to more than you feel you can comfortably
handle.</emphasis></para>
<para>You may request maintainership of any unmaintained port
as soon as you wish. Simply set <varname>MAINTAINER</varname>
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.</para>
<para>File your PR with category <literal>ports</literal> and
class <literal>change-request</literal>. 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 :).</para>
</sect2>
</sect1>
<sect1 xml:id="maintain-port">
<title>The challenge for port maintainers</title>
<para>This section will give you an idea of why ports need to be
maintained and outline the responsibilities of a port
maintainer.</para>
<sect2 xml:id="why-maintenance">
<title>Why ports require maintenance</title>
<para>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.</para>
<para>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.</para>
<para>As a maintainer, you will need to manage the following
challenges:</para>
<itemizedlist>
<listitem>
<formalpara>
<title>New software versions and updates.</title>
<para>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.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Changes to dependencies.</title>
<para>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.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Changes affecting dependent ports.</title>
<para>If other ports depend on a port that you maintain,
changes to your port may require coordination with
other maintainers.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Interaction with other users, maintainers and
developers.</title>
<para>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.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Bug hunting.</title>
<para>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.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Changes to ports infrastructure and policy.</title>
<para>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.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Changes to the base system.</title>
<para>&os; is under constant development. Changes to
software, libraries, the kernel or even policy changes
can cause flow-on change requirements to ports.</para>
</formalpara>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Maintainer responsibilities</title>
<sect3>
<title>Keep your ports up to date</title>
<para>This section outlines the process to follow to keep your
ports up to date.</para>
<para>This is an overview. More information about upgrading a
port is available in the
<link xlink:href="&url.books.porters-handbook;">
Porter's Handbook</link>.</para>
<procedure>
<step>
<title>Watch for updates</title>
<para>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.</para>
<para>You may also receive automated email from the
<literal>&os; Ports Version Check</literal> 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.</para>
</step>
<step>
<title>Incorporate changes</title>
<para>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.</para>
</step>
<step>
<title>Review and test</title>
<para>Thoroughly review and test your changes:</para>
<itemizedlist>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>Make sure your port's dependencies are complete.
The recommended way of doing this is by installing
your own ports <application>tinderbox</application>.
See <link linkend="resources">resources</link>
for more information.</para>
</listitem>
<listitem>
<para>Check that the packing list is up to date. This
involves adding in any new files and directories and
removing unused entries.</para>
</listitem>
<listitem>
<para>Verify your port using &man.portlint.1; as a
guide. See <link linkend="resources">resources</link> for important
information about using
<application>portlint</application>.</para>
</listitem>
<listitem>
<para>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 <varname>PORTREVISION</varname> bump
so that they will automatically be upgraded by
automated tools such as
<application>portmaster</application> or
&man.portupgrade.1;.</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Submit changes</title>
<para>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 xlink:href="&url.articles.problem-reports;">Writing FreeBSD
Problem Reports</link> for information on how to
write a really good PR.</para>
<note>
<para>Please do not submit a &man.shar.1; archive of the
entire port; instead, use &man.diff.1;
<literal>-ruN</literal>. In this way, committers can
much more easily see exactly what changes are being
made. The Porter's Handbook section on <link xlink:href="&url.books.porters-handbook;/port-upgrading.html">Upgrading</link>
has more information.</para>
</note>
</step>
<step>
<title>Wait</title>
<para>At some stage a committer will deal with your PR.
It may take minutes, or it may take weeks &mdash; so
please be patient.</para>
</step>
<step>
<title>Give feedback</title>
<para>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.</para>
</step>
<step>
<title>And Finally</title>
<para>Your changes will be committed and your port will
have been updated. The PR will then be closed by the
committer. That's it!</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Ensure your ports continue to build correctly</title>
<para>This section is about discovering and fixing problems
that stop your ports from building correctly.</para>
<para>&os; only guarantees that the Ports Collection works on
the <literal>-STABLE</literal> branches. You should be
running <literal>7-STABLE</literal> or
<literal>8-STABLE</literal>, preferably the latter. 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.</para>
<para>Since the majority of &os; installations run on
PC-compatible machines (what is termed the
<literal>i386</literal> architecture), we expect you to keep
the port working on that architecture. We prefer that ports
also work on the <literal>amd64</literal> architecture
running native. It is completely fair to ask for help if
you do not have one of these machines.</para>
<note>
<para>The usual failure modes for
non-<literal>i386</literal> machines are that the original
programmers assumed that, for instance, pointers are
<literal>int</literal>s, or that a relatively lax older
<application>gcc</application> compiler was being used.
More and more, application authors are reworking their
code to remove these assumptions &mdash; but if the author
is not actively maintaining their code, you may need to do
this yourself.</para>
</note>
<para>These are the tasks you need to perform to ensure your
port is able to be built:</para>
<procedure>
<step>
<title>Watch for build failures</title>
<para>Regularly check the automated ports building
cluster, <link xlink:href="http://pointyhat.FreeBSD.org">pointyhat</link>,
and the <link xlink:href="http://portscout.FreeBSD.org">distfiles
scanner</link> to see if any of the ports you
maintain are failing to build or fetch (see <link linkend="resources">resources</link> for more
information about these systems). Reports of failures
may also come to you from other users or automated
systems via email.</para>
</step>
<step>
<title>Collect information</title>
<para>Once you are aware of a problem, collect information
to help you fix it. Build errors reported by
<literal>pointyhat</literal> 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:</para>
<itemizedlist>
<listitem>
<para>Build logs</para>
</listitem>
<listitem>
<para>The commands and options used to build the
port (including options set in
<filename>/etc/make.conf</filename>)</para>
</listitem>
<listitem>
<para>A list of packages installed on their system
as shown by &man.pkg.info.1;</para>
</listitem>
<listitem>
<para>The version of &os; they are running as
shown by &man.uname.1;<command> -a</command></para>
</listitem>
<listitem>
<para>When their ports collection was last
updated</para>
</listitem>
<listitem>
<para>When their <filename>INDEX</filename> file
was last updated</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Investigate and find a solution</title>
<para>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.</para>
</step>
<step>
<title>Submit changes</title>
<para>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.</para>
</step>
<step>
<title>Send patches to upstream authors</title>
<para>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.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Investigate bug reports and PRs related to your
port</title>
<para>This section is about discovering and fixing
bugs.</para>
<para>&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.</para>
<para>These are the tasks you need to perform to ensure your
port continues to work as intended:</para>
<procedure>
<step>
<title>Respond to bug reports</title>
<para>Bugs may be reported to you through email via the
<link xlink:href="https://bugs.FreeBSD.org/search/">
Problem Report database</link>. Bugs may also be
reported directly to you by users.</para>
<para>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.</para>
<para>If you have not responded after 14 days, any
committer may commit from a PR that you have not
responded to via a
<literal>maintainer-timeout</literal>.</para>
</step>
<step>
<title>Collect information</title>
<para>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.</para>
<para>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:</para>
<itemizedlist>
<listitem>
<para>A detailed description of their actions,
expected program behavior and actual behavior</para>
</listitem>
<listitem>
<para>Copies of input data used to trigger the
bug</para>
</listitem>
<listitem>
<para>Information about their build and execution
environment &mdash; for example, a list of installed
packages and the output of &man.env.1;</para>
</listitem>
<listitem>
<para>Core dumps</para>
</listitem>
<listitem>
<para>Stack traces</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Eliminate incorrect reports</title>
<para>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.</para>
</step>
<step>
<title>Find a solution</title>
<para>As with build errors, you will need to sort out a
fix to the problem. Again, remember to ask if you are
stuck!</para>
</step>
<step>
<title>Submit or approve changes</title>
<para>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.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Providing support</title>
<para>Part of being a maintainer is providing support &mdash;
not for the software in general &mdash; 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;.</para>
<para>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 <literal>RPM</literal>s
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;.</para>
<para>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:</para>
<itemizedlist>
<listitem>
<para>submit a PR or send you patches to update your
port,</para>
</listitem>
<listitem>
<para>investigate and perhaps provide a fix to a PR,
or</para>
</listitem>
<listitem>
<para>otherwise submit changes to your port.</para>
</listitem>
</itemizedlist>
<para>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.</para>
<para>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
<!-- smiley -->:-).</para>
</sect3>
</sect2>
</sect1>
<sect1 xml:id="fix-broken">
<title>Finding and fixing a broken port</title>
<para>There are two really good places to find a port that needs
some attention.</para>
<para>You can use the <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">web
interface</link> 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
<literal>sw-bug</literal> class is a good place to
start).</para>
<para>The other place is the <link xlink:href="http://portsmon.FreeBSD.org/">&os; Ports Monitoring
System</link>. In particular look for unmaintained ports
with build errors and ports that are marked
<varname>BROKEN</varname>. 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.</para>
<para>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.</para>
</sect1>
<sect1 xml:id="mortal-coil">
<title>When to call it quits</title>
<para>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!</para>
<para>In any case, the Ports Management Team
(<literal>portmgr</literal>) 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.</para>
</sect1>
<sect1 xml:id="resources">
<title>Resources for ports maintainers and contributors</title>
<para>The <link xlink:href="&url.books.porters-handbook;">Porter's
Handbook</link> is your hitchhiker's guide to the ports
system. Keep it handy!</para>
<para><link xlink:href="&url.articles.problem-reports;">Writing FreeBSD
Problem Reports</link> 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.</para>
<para>The <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
Problem Report database</link>.</para>
<para><link xlink:href="http://pointyhat.FreeBSD.org/">Pointyhat</link>
is the ports build cluster. You can use Pointyhat to check port
build logs across all architectures and major releases.</para>
<para>The <link xlink:href="http://portsmon.FreeBSD.org/">FreeBSD Ports
Monitoring System</link> 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.</para>
<para>The <link xlink:href="http://portscout.FreeBSD.org">FreeBSD Ports
distfile scanner</link> 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
<varname>MASTER_SITES</varname> updated.</para>
<para>The ports <application>tinderbox</application> is the most
thorough way to test a port through the entire cycle of
installation, packaging, and deinstallation. It features a
command-line interface but also can be controlled via a web
interface. Please see
<filename>ports/ports-mgmt/tinderbox</filename>. More
documentation is located at the <link xlink:href="http://tinderbox.marcuscom.com/">marcuscom tinderbox home
page</link>.</para>
<para>&man.portlint.1; is an application which can be used to
verify that your port conforms to many important stylistic and
functional guidelines. <application>portlint</application> is a
simple heuristic application, so you should use it
<emphasis>only as a guide</emphasis>. If
<application>portlint</application> suggests changes which seem
unreasonable, consult the <link xlink:href="&url.books.porters-handbook;">Porter's Handbook</link>
or ask for advice.</para>
<para>The &a.ports; is for general ports-related discussion. It
is a good place to ask for help. You can <link xlink:href="http://lists.freebsd.org/mailman/listinfo">subscribe, or
read and search the list archives</link>. Reading the
archives of the &a.ports-bugs; and the &a.cvs-ports; may also be
of interest.</para>
</sect1>
<index/>
</article>

779
en_US.ISO8859-1/articles/contributing/article.xml
View file

@ -12,7 +12,9 @@
</abstract>
<authorgroup>
<author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname><contrib>Contributed by </contrib></author>
<author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname></author>
<author><personname><firstname>Sam</firstname><surname>Lawrance</surname></personname></author>
<author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author>
</authorgroup>
<legalnotice xml:id="trademarks" role="trademarks">
@ -28,20 +30,22 @@
<indexterm><primary>contributing</primary></indexterm>
<para>So you want to contribute to FreeBSD? That is great! FreeBSD
<para>So you want to contribute to &os;? That is great! &os;
<emphasis>relies</emphasis> on the contributions of its user base
to survive. Your contributions are not only appreciated, they are
vital to FreeBSD's continued growth.</para>
vital to &os;'s continued growth.</para>
<para>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
<para>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.</para>
<para>The FreeBSD project is responsible for an entire operating
<para>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.</para>
<para>The &os; project is responsible for an entire operating
system environment, rather than just a kernel or a few scattered
utilities. As such, our <filename>TODO</filename> lists span a
very wide range of tasks: from documentation, beta testing and
@ -218,8 +222,53 @@
</sect2>
<sect2>
<title>Pick one of the items from the <quote>Ideas</quote>
page</title>
<title>Ongoing Ports Tasks</title>
<para>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.</para>
<para>Anyone can get involved, and there are lots of different
ways to do so. Contributing to ports is an excellent way to
help <quote>give&nbsp;back</quote> 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!</para>
<para>There are a number of easy ways you can contribute to
keeping the ports tree up to date and in good working
order:</para>
<itemizedlist>
<listitem>
<para>Find some cool or useful software and
<link xlink:href="&url.books.porters-handbook;">create a port</link>
for it.</para>
</listitem>
<listitem>
<para>There are a large number of ports that have no
maintainer. Become a maintainer and
<link linkend="adopt-port">adopt a port</link>.</para>
</listitem>
<listitem>
<para>If you have created or adopted a port, be
aware of <link linkend="maintain-port">what you need to do
as a maintainer</link>.</para>
</listitem>
<listitem>
<para>When you are looking for a quick challenge you
could <link linkend="fix-broken">fix a bug or a broken
port</link>.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Pick one of the items from the Ideas page</title>
<para>The <link xlink:href="http://wiki.freebsd.org/IdeasPage">&os;
list of projects and ideas for volunteers</link> is also
@ -441,5 +490,711 @@
</sect2>
</sect1>
<sect1 xml:id="ports-contributing">
<title>Contributing to ports</title>
<sect2 xml:id="adopt-port">
<title>Adopting an unmaintained port</title>
<sect3>
<title>Choosing an unmaintained port</title>
<para>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.</para>
<para>Unmaintained ports have their
<varname>MAINTAINER</varname> set to
<literal>ports@FreeBSD.org</literal>. A list of unmaintained
ports and their current errors and problem reports can be seen
at the <link xlink:href="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">&os;
Ports Monitoring System</link>.</para>
<para>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.</para>
<para>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</filename>. (The name of the file varies
by release of &os;; for instance,
<filename>INDEX-8</filename>.) Some ports have conditional
dependencies that are not included in a default
<filename>INDEX</filename> build. We expect you to be able to
recognize such ports by looking through other ports'
<filename>Makefile</filename>s.</para>
</sect3>
<sect3>
<title>How to adopt the port</title>
<para>First make sure you understand your
<link linkend="maintain-port">responsibilities as a
maintainer</link>. Also read the
<link xlink:href="&url.books.porters-handbook;">Porter's
Handbook</link>. <emphasis>Please do not commit yourself
to more than you feel you can comfortably
handle.</emphasis></para>
<para>You may request maintainership of any unmaintained port
as soon as you wish. Simply set <varname>MAINTAINER</varname>
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.</para>
<para>File your PR with category <literal>ports</literal> and
class <literal>change-request</literal>. 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 :).</para>
</sect3>
</sect2>
<sect2 xml:id="maintain-port">
<title>The challenge for port maintainers</title>
<para>This section will give you an idea of why ports need to be
maintained and outline the responsibilities of a port
maintainer.</para>
<sect3 xml:id="why-maintenance">
<title>Why ports require maintenance</title>
<para>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.</para>
<para>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.</para>
<para>As a maintainer, you will need to manage the following
challenges:</para>
<itemizedlist>
<listitem>
<formalpara>
<title>New software versions and updates.</title>
<para>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.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Changes to dependencies.</title>
<para>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.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Changes affecting dependent ports.</title>
<para>If other ports depend on a port that you maintain,
changes to your port may require coordination with
other maintainers.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Interaction with other users, maintainers and
developers.</title>
<para>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.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Bug hunting.</title>
<para>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.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Changes to ports infrastructure and policy.</title>
<para>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.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Changes to the base system.</title>
<para>&os; is under constant development. Changes to
software, libraries, the kernel or even policy changes
can cause flow-on change requirements to ports.</para>
</formalpara>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>Maintainer responsibilities</title>
<sect4>
<title>Keep your ports up to date</title>
<para>This section outlines the process to follow to keep your
ports up to date.</para>
<para>This is an overview. More information about upgrading a
port is available in the
<link xlink:href="&url.books.porters-handbook;">
Porter's Handbook</link>.</para>
<procedure>
<step>
<title>Watch for updates</title>
<para>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.</para>
<para>You may also receive automated email from the
<literal>&os; Ports Version Check</literal> 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.</para>
</step>
<step>
<title>Incorporate changes</title>
<para>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.</para>
</step>
<step>
<title>Review and test</title>
<para>Thoroughly review and test your changes:</para>
<itemizedlist>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>Make sure your port's dependencies are complete.
The recommended way of doing this is by installing
your own ports <application>tinderbox</application>.
See <link linkend="resources">resources</link>
for more information.</para>
</listitem>
<listitem>
<para>Check that the packing list is up to date. This
involves adding in any new files and directories and
removing unused entries.</para>
</listitem>
<listitem>
<para>Verify your port using &man.portlint.1; as a
guide. See <link linkend="resources">resources</link> for important
information about using
<application>portlint</application>.</para>
</listitem>
<listitem>
<para>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 <varname>PORTREVISION</varname> bump
so that they will automatically be upgraded by
automated tools such as
<application>portmaster</application> or
&man.portupgrade.1;.</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Submit changes</title>
<para>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 xlink:href="&url.articles.problem-reports;">Writing FreeBSD
Problem Reports</link> for information on how to
write a really good PR.</para>
<note>
<para>Please do not submit a &man.shar.1; archive of the
entire port; instead, use &man.diff.1;
<literal>-ruN</literal>. In this way, committers can
much more easily see exactly what changes are being
made. The Porter's Handbook section on <link xlink:href="&url.books.porters-handbook;/port-upgrading.html">Upgrading</link>
has more information.</para>
</note>
</step>
<step>
<title>Wait</title>
<para>At some stage a committer will deal with your PR.
It may take minutes, or it may take weeks &mdash; so
please be patient.</para>
</step>
<step>
<title>Give feedback</title>
<para>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.</para>
</step>
<step>
<title>And Finally</title>
<para>Your changes will be committed and your port will
have been updated. The PR will then be closed by the
committer. That's it!</para>
</step>
</procedure>
</sect4>
<sect4>
<title>Ensure your ports continue to build correctly</title>
<para>This section is about discovering and fixing problems
that stop your ports from building correctly.</para>
<para>&os; only guarantees that the Ports Collection works on
the <literal>-STABLE</literal> 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.</para>
<para>Since the majority of &os; installations run on
PC-compatible machines (what is termed the
<literal>i386</literal> architecture), we expect you to keep
the port working on that architecture. We prefer that ports
also work on the <literal>amd64</literal> architecture
running native. It is completely fair to ask for help if
you do not have one of these machines.</para>
<note>
<para>The usual failure modes for
non-<literal>x86</literal> machines are that the original
programmers assumed that, for instance, pointers are
<literal>int</literal>s, or that a relatively lax older
<application>gcc</application> compiler was being used.
More and more, application authors are reworking their
code to remove these assumptions &mdash; but if the author
is not actively maintaining their code, you may need to do
this yourself.</para>
</note>
<para>These are the tasks you need to perform to ensure your
port is able to be built:</para>
<procedure>
<step>
<title>Watch for build failures</title>
<para>Check your mail for mail from
<literal>pkg-fallout@FreeBSD.org</literal>
and the <link xlink:href="http://portscout.FreeBSD.org">distfiles scanner</link>
to see if any of the port which are failing to build
are out of date.</para>
</step>
<step>
<title>Collect information</title>
<para>Once you are aware of a problem, collect information
to help you fix it. Build errors reported by
<literal>pkg-fallout</literal> 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:</para>
<itemizedlist>
<listitem>
<para>Build logs</para>
</listitem>
<listitem>
<para>The commands and options used to build the
port (including options set in
<filename>/etc/make.conf</filename>)</para>
</listitem>
<listitem>
<para>A list of packages installed on their system
as shown by &man.pkg.info.1;</para>
</listitem>
<listitem>
<para>The version of &os; they are running as
shown by &man.uname.1;<command> -a</command></para>
</listitem>
<listitem>
<para>When their ports collection was last
updated</para>
</listitem>
<listitem>
<para>When their ports tree amd
<filename>INDEX</filename> was last updated</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Investigate and find a solution</title>
<para>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.</para>
</step>
<step>
<title>Submit changes</title>
<para>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.</para>
</step>
<step>
<title>Send patches to upstream authors</title>
<para>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.</para>
</step>
</procedure>
</sect4>
<sect4>
<title>Investigate bug reports and PRs related to your
port</title>
<para>This section is about discovering and fixing
bugs.</para>
<para>&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.</para>
<para>These are the tasks you need to perform to ensure your
port continues to work as intended:</para>
<procedure>
<step>
<title>Respond to bug reports</title>
<para>Bugs may be reported to you through email via the
<link xlink:href="https://bugs.FreeBSD.org/search/">
Problem Report database</link>. Bugs may also be
reported directly to you by users.</para>
<para>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.</para>
<para>If you have not responded after 14 days, any
committer may commit from a PR that you have not
responded to via a
<literal>maintainer-timeout</literal>.</para>
</step>
<step>
<title>Collect information</title>
<para>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.</para>
<para>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:</para>
<itemizedlist>
<listitem>
<para>A detailed description of their actions,
expected program behavior and actual behavior</para>
</listitem>
<listitem>
<para>Copies of input data used to trigger the
bug</para>
</listitem>
<listitem>
<para>Information about their build and execution
environment &mdash; for example, a list of installed
packages and the output of &man.env.1;</para>
</listitem>
<listitem>
<para>Core dumps</para>
</listitem>
<listitem>
<para>Stack traces</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Eliminate incorrect reports</title>
<para>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.</para>
</step>
<step>
<title>Find a solution</title>
<para>As with build errors, you will need to sort out a
fix to the problem. Again, remember to ask if you are
stuck!</para>
</step>
<step>
<title>Submit or approve changes</title>
<para>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.</para>
</step>
</procedure>
</sect4>
<sect4>
<title>Providing support</title>
<para>Part of being a maintainer is providing support &mdash;
not for the software in general &mdash; 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;.</para>
<para>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 <literal>RPM</literal>s
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;.</para>
<para>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:</para>
<itemizedlist>
<listitem>
<para>submit a PR or send you patches to update your
port,</para>
</listitem>
<listitem>
<para>investigate and perhaps provide a fix to a PR,
or</para>
</listitem>
<listitem>
<para>otherwise submit changes to your port.</para>
</listitem>
</itemizedlist>
<para>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.</para>
<para>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
<!-- smiley -->:-).</para>
</sect4>
</sect3>
</sect2>
<sect2 xml:id="fix-broken">
<title>Finding and fixing a broken port</title>
<para>There are two really good places to find a port that needs
some attention.</para>
<para>You can use the <link xlink:href="http://bugs.freebsd.org/search">web
interface</link> 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
<literal>sw-bug</literal> class is a good place to
start).</para>
<para>The other place is the <link xlink:href="http://portsmon.FreeBSD.org/">&os; Ports Monitoring
System</link>. In particular look for unmaintained ports
with build errors and ports that are marked
<varname>BROKEN</varname>. 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.</para>
<para>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.</para>
</sect2>
<sect2 xml:id="mortal-coil">
<title>When to call it quits</title>
<para>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!</para>
<para>In any case, the Ports Management Team
(<literal>portmgr</literal>) 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.</para>
</sect2>
<sect2 xml:id="resources">
<title>Resources for ports maintainers and contributors</title>
<para>The <link xlink:href="&url.books.porters-handbook;">Porter's
Handbook</link> is your hitchhiker's guide to the ports
system. Keep it handy!</para>
<para><link xlink:href="&url.articles.problem-reports;">Writing FreeBSD
Problem Reports</link> 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.</para>
<para>The <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
Problem Report database</link>.</para>
<para>The <link xlink:href="http://portsmon.FreeBSD.org/">FreeBSD Ports
Monitoring System</link> 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.</para>
<para>The <link xlink:href="http://portscout.FreeBSD.org">FreeBSD Ports
distfile scanner</link> 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
<varname>MASTER_SITES</varname> updated.</para>
<para><package>ports-mgmt/poudriere</package> is the most
thorough way to test a port through the entire cycle of
installation, packaging, and deinstallation.
documentation is located at the
<link xlink:href="https://fossil.etoilebsd.net/poudriere/">poudriere home page</link></para>
<para>&man.portlint.1; is an application which can be used to
verify that your port conforms to many important stylistic and
functional guidelines. <application>portlint</application> is a
simple heuristic application, so you should use it
<emphasis>only as a guide</emphasis>. If
<application>portlint</application> suggests changes which seem
unreasonable, consult the <link xlink:href="&url.books.porters-handbook;">Porter's Handbook</link>
or ask for advice.</para>
<para>The &a.ports; is for general ports-related discussion. It
is a good place to ask for help. You can <link xlink:href="http://lists.freebsd.org/mailman/listinfo">subscribe, or
read and search the list archives</link>. Reading the
archives of the &a.ports-bugs; and the &a.cvs-ports; may also be
of interest.</para>
</sect2>
</sect1>
<index/>
</article>

1
fr_FR.ISO8859-1/articles/Makefile
View file

@ -9,7 +9,6 @@
SUBDIR = building-products
SUBDIR+= committers-guide
SUBDIR+= contributing
SUBDIR+= contributing-ports
SUBDIR+= contributors
SUBDIR+= explaining-bsd
SUBDIR+= filtering-bridges

19
fr_FR.ISO8859-1/articles/contributing-ports/Makefile
View file

@ -1,19 +0,0 @@
#
# $FreeBSD$
#
# Article: Contributing to the FreeBSD Ports Collection
DOC?= article
FORMATS?= html
WITH_ARTICLE_TOC?= YES
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.xml
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

1026
fr_FR.ISO8859-1/articles/contributing-ports/article.xml
View file

File diff suppressed because it is too large Load diff

1
ja_JP.eucJP/articles/Makefile
View file

@ -7,7 +7,6 @@ SUBDIR =
#SUBDIR+= committers-guide
#SUBDIR+= console-server
SUBDIR+= contributing
#SUBDIR+= contributing-ports
SUBDIR+= contributors
#SUBDIR+= cups
#SUBDIR+= explaining-bsd

1
nl_NL.ISO8859-1/articles/Makefile
View file

@ -5,7 +5,6 @@
SUBDIR =
SUBDIR+= contributing
SUBDIR+= contributing-ports
SUBDIR+= explaining-bsd
SUBDIR+= problem-reports
SUBDIR+= solid-state

22
nl_NL.ISO8859-1/articles/contributing-ports/Makefile
View file

@ -1,22 +0,0 @@
#
# $FreeBSD$
#
# %SOURCE% en_US.ISO8859-1/articles/contributing-ports/Makefile
# %SRCID% 39631
#
# Article: Contributing to the FreeBSD Ports Collection
DOC?= article
FORMATS?= html
WITH_ARTICLE_TOC?= YES
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.xml
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

847
nl_NL.ISO8859-1/articles/contributing-ports/article.xml
View file

@ -1,847 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
<!--
$FreeBSD$
%SOURCE% en_US.ISO8859-1/articles/contributing-ports/article.xml
%SRCID% 41645
-->
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="nl">
<info><title>Bijdragen aan de &os; Portscollectie</title>
<abstract>
<title>Abstract</title>
<para>Dit artikel beschrijft de manieren waarop een individu kan
bijdragen aan de &os; Portscollectie.</para>
<para><emphasis>Vertaald door René Ladan</emphasis>.</para>
</abstract>
<authorgroup>
<author><personname><firstname>Sam</firstname><surname>Lawrance</surname></personname></author>
<author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author>
</authorgroup>
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
<pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
</info>
<indexterm><primary>bijdragen aan ports</primary></indexterm>
<sect1>
<title>Introductie</title>
<para>De Portscollectie is een eeuwig werk-in-uitvoering. We willen
onze gebruikers een reservoir van software van derde partijen
bieden dat gemakkelijk te gebruiken, bijgewerkt, en van hoge
kwaliteit is. We hebben mensen nodig die wat tijd en moeite
investeren om ons dit doel te helpen bereiken.</para>
<para>Iedereen kan erin betrokken raken, en er zijn vele manieren om
dat te doen. Bijdragen aan ports is een uitstekende manier om te
helpen om iets aan het project <quote>terug te geven</quote>. Of u nu op
zoek bent naar een blijvende rol, of naar een uitdaging voor een
regenachtige dag, wij stellen uw hulp zeer op prijs!</para>
<para>Als een vrijwilliger kunt u doen en laten wat u wilt. We
vragen echter wel dat u op de hoogte bent van wat andere leden van
de &os;-gemeenschap van u verwachten. U doet er goed aan om dit
te overwegen voordat u besluit om vrijwilliger te worden.</para>
</sect1>
<sect1 xml:id="what-contribute">
<title>Wat u kunt doen om te helpen</title>
<para>Er zijn een aantal gemakkelijke manieren waarop u bij kunt
dragen om de portsboom actueel en in een goede toestand te
houden:</para>
<itemizedlist>
<listitem>
<para>Zoek wat leuke of nuttige software en <link linkend="create-port">creëer er een port</link>
voor.</para>
</listitem>
<listitem>
<para>Er is een groot aantal niet-onderhouden ports. Wordt een
onderhouder en <link linkend="adopt-port">adopteer een
port</link>.</para>
</listitem>
<listitem>
<para>Als u een port gecreëerd of geadopteerd heeft, dient
u op de hoogte te zijn van <link linkend="maintain-port">wat
u als onderhouder moet doen</link>.</para>
</listitem>
<listitem>
<para>Als u op zoek bent naar een snelle uitdaging zou u <link linkend="fix-broken">een bug of een kapotte port kunnen
repareren</link>.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 xml:id="create-port">
<title>Een nieuwe port creëeren</title>
<para>Er is een apart document beschikbaar om u door het
creëeren (en bijwerken) van een port te loodsen genaamd het
<link xlink:href="&url.books.porters-handbook.en;">Porter's
Handbook</link>. Het Porter's Handbook is het beste naslagwerk
wat betreft het werken met het portssysteem. Het noemt details
over hoe het portssysteem werkt en bespreekt aangeraden
praktijken.</para>
</sect1>
<sect1 xml:id="adopt-port">
<title>Een niet-onderhouden port adopteren</title>
<sect2>
<title>Een niet-onderhouden port kiezen</title>
<para>Het beheer overnemen van ports die niet onderhouden worden
is een uitstekende manier om betrokken te raken.
Niet-onderhouden ports worden alleen bijgewerkt en gerepareerd
wanneer iemand zich aanbiedt om eraan te werken. Er is een
groot aantal ports dat niet onderhouden wordt. Het is een goed
idee om met het adopteren van een port te beginnen die u
regelmatig gebruikt.</para>
<para>Voor niet-onderhouden ports staat de
<varname>MAINTAINER</varname> op
<literal>ports@FreeBSD.org</literal>. Een lijst van ports die
niet onderhouden wordt en hun huidige fouten en
probleemrapporten kan worden bekeken op het <link xlink:href="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">
&os; Ports Monitoring System</link>.</para>
<para>Sommige ports beïnvloeden een groot aantal anderen
vanwege afhankelijkheden en relaties als slaafport. Over het
algemeen wensen we dat mensen wat ervaring hebben voordat ze
zulke ports onderhouden.</para>
<para>U kunt uitzoeken of een port wel of geen afhankelijkheden
of slaafpoorten heeft door in een hoofdindex van ports genaamd
<filename>INDEX</filename> te kijken. (De naam van het bestand
varieert naar gelang de uitgave van &os;; bijvoorbeeld
<filename>INDEX-8</filename>.) Sommige ports hebben
conditionele afhankelijkheden die niet standaard in een bouw van
<filename>INDEX</filename> worden opgenomen. We verwachten dat
u zulke ports kunt herkennen door naar de
<filename>Makefile</filename> van andere ports te kijken.</para>
</sect2>
<sect2>
<title>Hoe een port te adopteren</title>
<para>Zorg eerst dat u uw <link linkend="maintain-port">
verantwoordelijkheden als onderhouder</link> begrijpt. Lees
ook het <link xlink:href="&url.books.porters-handbook.en;">Porter's
Handbook</link>. <emphasis>Neem alstublieft niet meer werk
op u dan dat u op een comfortabele manier
aankunt.</emphasis></para>
<para>U kunt zo snel als u wilt het beheer van een
niet-onderhouden port aanvragen. Stel
<varname>MAINTAINER</varname> in op uw emailadres en stuur een
PR (probleemrapport) in met de verandering. Als de port
bouwfouten bevat of moet worden bijgewerkt, dan kunt u deze
veranderingen in hetzelfde PR opnemen. Dit helpt omdat veel
committers minder bereid zijn om beheer aan iemand toe te kennen
die geen bekende geschiedenis met &os; heeft. Het insturen van
PR's die bouwfouten repareren of ports bijwerken zijn de beste
manier om er een op te bouwen.</para>
<para>Stuur uw PR in met categorie <literal>ports</literal> en
klasse <literal>change-request</literal>. Een committer zal uw
PR nakijken, de veranderingen committen, en uiteindelijk het PR
sluiten. Soms kan dit proces even duren (committers zijn ook
vrijwilligers).</para>
</sect2>
</sect1>
<sect1 xml:id="maintain-port">
<title>De uitdaging voor port-onderhouders</title>
<para>Deze sectie geeft u een idee waarom ports onderhouden moeten
worden en schetst de verantwoordelijkheden van een onderhouder van
een port.</para>
<sect2 xml:id="why-maintenance">
<title>Waarom ports onderhoud nodig hebben</title>
<para>Een port creëeren is een eenmalige taak. Er zeker van
zijn dat een port actueel is en blijft bouwen en draaien is
een voortdurende inspanning. Onderhouders zijn mensen die
wat van hun tijd wijden aan het vervullen van deze
doelen.</para>
<para>De voornaamste reden waarom ports onderhoud nodig hebben is
om het nieuwste en beste van software van derde partijen aan de
&os;-gemeenschap te geven. Een aanvullende uitdaging is om
individuele ports werkend te houden binnen het evoluerende
raamwerk van de Portscollectie.</para>
<para>Als onderhouder zult u de volgende uitdagingen moeten
aangaan:</para>
<itemizedlist>
<listitem>
<formalpara>
<title>Nieuwe versies en updates van software.</title>
<para>Nieuwe versies en updates van bestaande geporteerde
software komen continu beschikbaar, en moeten in de
Portscollectie worden verwerkt om actuele software aan te
bieden.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Veranderingen aan afhankelijkheden.</title>
<para>Als er significante wijzigingen zijn gemaakt aan de
afhankelijkheden van uw port, kan het zijn dat de port
moet worden bijgewerkt zodat het correct blijft
werken.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Veranderingen die afhankelijke ports
beïnvloeden.</title>
<para>Als andere ports afhankelijk zijn van een port die u
onderhoudt, kan het zijn om veranderingen aan uw port met
andere onderhouders te coördineren.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Interactie met andere gebruikers, onderhouders, en
ontwikkelaars.</title>
<para>Een gedeelte van een onderhouder zijn is het vervullen
van een ondersteunende rol. Er wordt niet van u verwacht
dat u algemene ondersteuning biedt (maar we juichen het
toe als u dat doet). U dient een centraal punt voor
&os;-specifieke zaken met betrekking tot uw ports te
bieden.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Bugs oplossen.</title>
<para>Een port kan vatbaar zijn voor bugs die specifiek zijn
voor &os;. U dient deze bugs te onderzoeken en te
repareren wanneer ze worden gerapporteerd. Het grondig
testen van een port om problemen te identificeren voordat
ze in de Portscollectie terechtkomen is nog beter.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Veranderingen aan portsinfrastructuur en
beleid.</title>
<para>Af en toe worden die systemen die gebruikt worden om
ports en pakketten te bouwen bijgewerkt of wordt er een
nieuwe aanbeveling met betrekking tot de infrastructuur
gemaakt. U dient van deze veranderingen op de hoogte te
zijn indien ze betrekking hebben op uw ports en ze
bijgewerkt moeten worden.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>Veranderingen aan het basissysteem.</title>
<para>&os; is constant in ontwikkeling. Veranderingen aan
software, bibliotheken, de kernel, of zelfs
beleidsveranderingen kunnen noodzakelijke veranderingen
aan ports veroorzaken.</para>
</formalpara>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Verantwoordelijkheden als onderhouder</title>
<sect3>
<title>Houd uw ports actueel</title>
<para>Deze sectie schetst het proces dat gevolgd wordt om uw
ports actueel te houden.</para>
<para>Dit is een overzicht. Meer informatie over het bijwerken
van een port is beschikbaar in het <link xlink:href="&url.books.porters-handbook.en;">Porter's
Handbook</link>.</para>
<procedure>
<step>
<title>Kijk uit naar updates</title>
<para>Houd de stroomopwaartse leverancier in de gaten wat
betreft nieuwe versies, updates, en beveiligingsreparaties
voor de software. Mailinglijsten met aankondigingen of
webpagina's met nieuws zijn hiervoor handig. Soms zullen
gebruikers contact met u opnemen en vragen wanneer uw port
wordt bijgewerkt. Als u het druk hebt met andere dingen
of u het om enige andere reden niet nu kunt bijwerken,
vraag ze dan om u te helpen door een update te
sturen.</para>
<para>U kunt ook geautomatiseerde email van de <literal>&os;
Ports Version Check</literal> ontvangen die u informeert
of er een nieuwe versie van het distributiebestand van uw
port beschikbaar is. Meer informatie over dat systeem
(inclusief hoe toekomstige emails te stoppen) staat in het
bericht.</para>
</step>
<step>
<title>Verwerk veranderingen</title>
<para>Verwerk veranderingen in de port wanneer ze
beschikbaar komen. U dient een patch aan te kunnen maken
tussen de originele port en uw bijgewerkte port.</para>
</step>
<step>
<title>Herzie en test</title>
<para>Herzie en test uw veranderingen grondig:</para>
<itemizedlist>
<listitem>
<para>Bouw, installeer, en test uw port op zoveel
mogelijk platforms en architecturen. Het is
gebruikelijk dat een port op één tak of
platform werkt maar faalt op een ander.</para>
</listitem>
<listitem>
<para>Zorg dat de afhankelijkheden van uw port compleet
zijn. De aangeraden manier om dit te doen is door uw
eigen <application>tinderbox</application> voor ports
te installeren. Bekijk <link linkend="resources">bronnen</link> voor meer
informatie.</para>
</listitem>
<listitem>
<para>Controleer of de pakketlijst actueel is. Dit
omvat het toevoegen van nieuwe bestanden en mappen en
het verwijderen van ongebruikte regels.</para>
</listitem>
<listitem>
<para>Verifieer uw port met &man.portlint.1; als gids.
Bekijk <link linkend="resources">bronnen</link> voor
belangrijke informatie over het gebruik van
<application>portlint</application>.</para>
</listitem>
<listitem>
<para>Overweeg of veranderingen aan uw port andere ports
zouden kunnen kapotmaken. Bespreek de veranderingen
met de onderhouders van die ports als dit het geval
is. Dit is speciaal van belang als uw update de
versie van de gedeelde bibliotheek verandert; in dit
geval dienen de afhankelijke ports minstens een
verhoging van de <varname>PORTREVISION</varname> te
krijgen zodat ze automatisch worden bijgewerkt door
geautomatiseerde gereedschappen als
<application>portmaster</application> of
&man.portupgrade.1;.</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Stuur veranderingen in</title>
<para>Verzend uw update door een PR met een uitleg van de
veranderingen en een patch die de verschillen tussen de
originele port en de bijgewerkte port bevat in te sturen.
Bekijk alstublieft <link xlink:href="&url.articles.problem-reports;">Probleemrapporten
voor &os; schrijven</link> voor informatie over hoe
een echt goed PR te schrijven.</para>
<note>
<para>Stuur alstublieft geen &man.shar.1;-archief van de
gehele port; gebruik in plaats daarvan &man.diff.1;
<literal>-ruN</literal>. Op deze manier kunnen committers
veel gemakkelijker zien welke veranderingen er precies
gemaakt worden. De sectie in het Porter's Handbook over
<link xlink:href="&url.books.porters-handbook.en;/port-upgrading.html">
Upgrading</link> bevat meer informatie
hierover.</para>
</note>
</step>
<step>
<title>Wacht</title>
<para>Op een gegeven moment zal een committer uw PR
behandelen. Dit kan minuten, maar ook weken duren &mdash; ben
dus alstublieft geduldig.</para>
</step>
<step>
<title>Geef feedback</title>
<para>Als een committer een probleem vindt in uw
veranderingen zullen ze het waarschijnlijk aan u
terugkoppelen. Een snel antwoord helpt om uw PR sneller
gecommit te krijgen, en is beter voor het behouden van een
discussie wanneer er geprobeerd wordt om problemen op te
lossen.</para>
</step>
<step>
<title>En ten slotte</title>
<para>Uw veranderingen zullen gecommit worden en uw port zal
bijgewerkt zijn. Het PR wordt vervolgens door de
committer gesloten. Dat is alles!</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Zorg ervoor dat uw ports correct blijven bouwen</title>
<para>Deze sectie gaat over het ontdekken en oplossen van
problemen die verhinderen dat uw ports correct bouwen.</para>
<para>&os; garandeert alleen dat de Portscollectie op de
<literal>-STABLE</literal>-takken werkt. U dient
<literal>7-STABLE</literal> of <literal>8-STABLE</literal> te
draaien, bij voorkeur de laatste. In theorie zou het
voldoende moeten zijn om de nieuwste uitgave van elke
STABLE-tak te draaien (aangezien de ABI's niet horen te
veranderen), maar als u die tak kunt draaien is dat
beter.</para>
<para>Aangezien de meerderheid van &os;-installaties op
PC-compatibele machines draait (wat wordt aangeduid als de
<literal>i386</literal>-architectuur), verwachten wij van u
dat u de port op die architectuur werkend houdt. We prefereren dat
de ports ook op de <literal>amd64</literal>-architectuur draaien.
Het is prima om hulp te vragen als u een van deze machines niet
heeft.</para>
<note>
<para>De gebruikelijke manieren om te falen voor
niet-<literal>i386</literal> machines zijn dat de originele
programmeurs aannamen dat, bijvoorbeeld, pointers
<literal>int</literal>s zijn of dat een relatief lakse
oudere <application>gcc</application> compiler werd
gebruikt. Steeds meer reorganiseren applicatie-auteurs hun
code om deze aannames te verwijderen &mdash; maar als de
auteur de code niet actief onderhoudt, zult u dit zelf
moeten doen.</para>
</note>
<para>Deze taken moet u uitvoeren om ervoor te zorgen dat uw
port gebouwd kan worden:</para>
<procedure>
<step>
<title>Kijk uit naar bouwfouten</title>
<para>Controleer regelmatig het geautomatiseerde
portbouwcluster, <link xlink:href="http://pointyhat.FreeBSD.org">pointyhat</link>,
en de <link xlink:href="http://portscout.FreeBSD.org">scanner voor
distributiebestanden</link> om te zien
of er ports zijn die u onderhoudt die er niet in slagen om
gebouwd of opgehaald te worden (bekijk <link linkend="resources">bronnen</link> voor meer informatie
over deze systemen). Rapportages over mislukkingen kunnen
ook via email van andere gebruikers of geautomatiseerde
systemen tot u komen.</para>
</step>
<step>
<title>Verzamel informatie</title>
<para>Als u eenmaal op de hoogte bent van een probleem,
verzamel dan informatie die u helpt het op te lossen.
Bouwfouten die door <literal>pointyhat</literal> worden
gerapporteerd worden vergezeld door logs die aangeven waar
het bouwen mislukte. Als de mislukking door een gebruiker
aan u werd gerapporteerd, vraag ze dan om informatie te
verzenden die u helpt om het probleem te vast te stellen,
zoals:</para>
<itemizedlist>
<listitem>
<para>Bouwlogs</para>
</listitem>
<listitem>
<para>De commando's en opties die gebruikt werden om de
port te bouwen (inclusief opties die in
<filename>/etc/make.conf</filename> zijn
ingesteld)</para>
</listitem>
<listitem>
<para>Een lijst met op hun systeem geïnstalleerde
pakketten als aangegeven door &man.pkg.info.1;</para>
</listitem>
<listitem>
<para>De versie van &os; die ze draaien als aangegeven
door &man.uname.1;<command> -a</command></para>
</listitem>
<listitem>
<para>Wanneer hun Portscollectie voor het laatst was
bijgewerkt</para>
</listitem>
<listitem>
<para>Wanneer hun bestand <filename>INDEX</filename>
voor het laatst was bijgewerkt</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Onderzoek en zoek een oplossing</title>
<para>Helaas is er geen rechttoe-rechtaan proces dat gevolgd
kan worden om dit te doen. Herinner: vraag om hulp als u
vast zit! De &a.ports; is een goede plaats om te starten,
en de stroomopwaartse ontwikkelaars zijn vaak zeer
behulpzaam.</para>
</step>
<step>
<title>Stuur veranderingen in</title>
<para>Net zoals bij het bijwerken van een port, dient u nu
de veranderingen te integreren, te herzien en te testen,
uw veranderingen als een PR in te sturen, en feedback te
geven als dat nodig is.</para>
</step>
<step>
<title>Stuur patches naar de stroomopwaartse auteurs</title>
<para>In sommige gevallen moet u patches maken om de port op
&os; te laten draaien. Sommige (maar niet alle)
stroomopwaartse auteurs zullen zulke patches in hun code
accepteren voor de volgende uitgave. Als dit zo is, kan
dit zelfs hun gebruikers op andere op BSD-gebaseerde
systemen helpen en misschien dubbel werk besparen.
Overweeg alstublieft om geschikte patches naar de auteurs
te zenden als teken van goede wil.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Onderzoek foutrapporten en PR's die aan uw port
gerelateerd zijn</title>
<para>Deze sectie gaat over het ontdekken en repareren van
bugs.</para>
<para>&os;-specifieke bugs worden in het algemeen veroorzaakt
door aannames over de bouw- en draaiomgevingen die niet voor
&os; gelden. U zult zo'n soort fout minder snel aantreffen,
maar het kan subtieler en moeilijker zijn om het vast te
stellen.</para>
<para>De onderstaande taken moet u uitvoeren om ervoor te zorgen
dat uw port als bedoeld blijft werken:</para>
<procedure>
<step>
<title>Reageer op bugrapporten</title>
<para>Bugs kunnen per email via de <link xlink:href="&url.base;/cgi/query-pr-summary.cgi?query">
GNATS Probleemrapportendatabase</link> aan u worden
gerapporteerd. Bugs kunnen ook direct door gebruikers aan
u gerapporteerd worden.</para>
<para>U dient binnen 14 dagen op PR's en andere rapporten te
reageren, probeer hier alstublieft niet zo lang over te
doen. Probeer zo snel mogelijk te reageren, zelfs als het
alleen maar is om te zeggen dat u wat meer tijd nodig
heeft voordat u aan het PR kan werken.</para>
<para>Als u niet na 14 dagen heeft gereageerd, mag elke committer
via een <literal>maintainer-timeout</literal> uit een PR
committen waarop u niet heeft gereageerd.</para>
</step>
<step>
<title>Verzamel informatie</title>
<para>Als degene die de bug heeft gerapporteerd niet ook een
reparatie heeft aangeleverd, zult u informatie moeten
verzamelen die u in staat stelt om er een te
genereren.</para>
<para>Als de bug reproduceerbaar is, kunt u zelf de meeste
vereiste informatie verzamelen. Zo niet, vraag dan degene
die de bug rapporteerde om de informatie voor u te
verzamelen, zoals:</para>
<itemizedlist>
<listitem>
<para>Een gedetailleerde beschrijving van hun acties,
verwacht gedrag en eigenlijk gedrag van het
programma</para>
</listitem>
<listitem>
<para>Kopiën van invoergegevens die de bug
aanzwengelden</para>
</listitem>
<listitem>
<para>Informatie over hun bouw- en uitvoeromgeving &mdash;
bijvoorbeeld een lijst van geïnstalleerde
pakketten en de uitvoer van &man.env.1;</para>
</listitem>
<listitem>
<para>Coredumps</para>
</listitem>
<listitem>
<para>Stacktraces</para>
</listitem>
</itemizedlist>
</step>
<step>
<title>Elimineer onjuiste rapporten</title>
<para>Sommige bugrapporten kunnen onjuist zijn. De
gebruiker kan het programma simpelweg verkeerd gebruikt
hebben; of hun geïnstalleerde pakketten kunnen
verouderd zijn en bijgewerkt moeten worden. Soms is een
gerapporteerde fout niet specifiek voor &os;. Rapporteer
in dit geval de bug naar de stroomopwaartse ontwikkelaars.
Als u de bug kunt repareren, kunt u de port ook patchen
zodat de reparatie is toegepast voor de volgende
stroomopwaartse uitgave.</para>
</step>
<step>
<title>Vind een oplossing</title>
<para>Net als met bouwfouten dient u een oplossing voor het
probleem te vinden. Nogmaals, vraag om hulp als u
vastzit!</para>
</step>
<step>
<title>Stuur veranderingen in of keur ze goed</title>
<para>Net als bij het bijwerken van een port, dient u nu de
veranderingen te integreren, ze te herzien en te testen,
en ze in een PR op te sturen (of een vervolg te verzenden
als er al een PR voor het probleem bestaat). Als een
andere gebruiker veranderingen in het PR heeft ingezonden,
kunt u ook een vervolg sturen waarin u zegt of u de
veranderingen wel of niet goedkeurt.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Ondersteuning bieden</title>
<para>Deel van een onderhouder zijn is ondersteuning bieden
&mdash; niet noodzakelijk voor de software in het algemeen
&mdash; maar voor de port en alle &os;-specifieke rariteiten
en problemen. Gebruikers kunnen contact met u opnemen voor
vragen, suggesties, problemen, en patches. Meestal zal hun
correspondentie specifiek voor &os; zijn.</para>
<para>Af en toe zult u uw diplomatieke vaardigheden moeten
gebruiken, en gebruikers die algemene ondersteuning zoeken
vriendelijk naar de geschikte bronnen verwijzen. Minder vaak
zult u iemand tegenkomen die vraagt waarom de
<literal>RPM</literal>s niet actueel zijn of hoe ze de
software onder Foo Linux kunnen draaien. Grijp deze kans om
ze te vertellen dat uw port actueel is (als het dat is,
uiteraard!) en stel voor dat ze &os; uitproberen.</para>
<para>Soms zullen gebruikers en ontwikkelaars besluiten dat u
een druk persoon bent wiens tijd waardevol is en wat werk van
u overnemen. Ze kunnen bijvoorbeeld:</para>
<itemizedlist>
<listitem>
<para>een PR insturen of u patches toesturen om uw port bij
te werken,</para>
</listitem>
<listitem>
<para>een PR onderzoeken en er misschien een reparatie voor
aanleveren, of</para>
</listitem>
<listitem>
<para>op andere wijze veranderen aan uw port
insturen.</para>
</listitem>
</itemizedlist>
<para>In deze gevallen is uw hoofdplicht om op tijd te reageren.
Nogmaals, de timeout voor niet-reagerende onderhouders is 14 dagen.
Na deze periode mogen niet-goedgekeurde veranderingen gecommit
worden. Ze hebben de moeite genomen om dit voor u te doen;
dus probeer tenminste op tijd te reageren. Daarna dient u zo
snel mogelijk hun veranderingen te herzien, goed te keuren, te
wijzigen, of met hen te bediscussiëren.</para>
<para>Als u ervoor kunt zorgen dat ze het gevoel hebben dat hun
bijdrage gewaardeerd wordt (wat zo hoort te zijn), dan heeft u
een grotere kans om ze te overtuigen om in de toekomst meer
voor u te doen <!-- smiley -->:-).</para>
</sect3>
</sect2>
</sect1>
<sect1 xml:id="fix-broken">
<title>Een kapotte port vinden en repareren</title>
<para>Er zijn twee zeer goede plaatsen om een port te vinden die wat
aandacht nodig heeft.</para>
<para>U kunt de <link xlink:href="&url.base;/cgi/query-pr-summary.cgi?query">webinterface
</link> voor de probleemrapportdatabase gebruiken om
onopgeloste PR's te doorzoeken en ze te bekijken. De meerderheid
van port-PR's zijn updates, maar met een beetje zoeken door en
uitkammen van de samenvattingen zou u iets moeten kunnen vinden
wat interessant is om aan te werken (de klasse
<literal>sw-bug</literal> is een goede plaats om te
beginnen).</para>
<para>De andere plaats is het <link xlink:href="http://portsmon.FreeBSD.org/">&os; Ports Monitoring
System</link>. Zoek in het bijzonder naar niet-onderhouden
ports met bouwfouten en ports die als <varname>BROKEN</varname>
zijn gemerkt. Het is ook goed om veranderingen voor een
onderhouden port te versturen, maar denk eraan om de onderhouder
te vragen in het geval dat ze al aan het probleem werken.</para>
<para>Als u eenmaal een bug of probleem heeft gevonden, verzamel dan
informatie, onderzoek, en repareer het! Als er een bestaand PR
is, ga daar dan mee verder. Maak anders een nieuw PR aan. Uw
veranderingen zullen worden herzien en, als alles goed is,
gecommit.</para>
</sect1>
<sect1 xml:id="mortal-coil">
<title>Wanneer het tijd wordt om te stoppen</title>
<para>Wanneer uw interesses en toewijdingen veranderen, zult u
erachter komen dat u niet langer tijd heeft om sommige van (of al)
uw ports-bijdragen voort te zetten. Dat is prima! Laat ons weten
als u een port niet langer gebruikt of om andere redenen de tijd
of interesse heeft verloren om ports te onderhouden. Op deze
manier kunnen we verder gaan en andere mensen toestaan om te
proberen om aan bestaande problemen met de port te werken zonder
op uw antwoord te wachten. Herinner dat &os; een
vrijwilligersproject is, dus als het onderhouden van een port
niet langer leuk is, is het waarschijnlijk tijd om iemand anders
het te laten doen!</para>
<para>In elk geval houdt het Ports Management Team
(<literal>portmgr</literal>) zich het recht voor om u als
onderhouder te wissen als u uw port voor enige tijd niet actief
heeft onderhouden. (Momenteel is dit 3 maanden.) Hiermee
bedoelen we dat er onopgeloste problemen of wachtende updates zijn
waaraan binnen die tijd niet gewerkt is.</para>
</sect1>
<sect1 xml:id="resources">
<title>Bronnen voor onderhouders en vrijwilligers voor ports</title>
<para>Het <link xlink:href="&url.books.porters-handbook.en;">Porter's Handbook</link> is
uw overlevingsgids voor het portssysteem. Houd het in de
buurt!</para>
<para><link xlink:href="&url.articles.problem-reports;">Probleemrapporten
voor &os; schrijven</link> beschrijft hoe het beste een PR
geformuleerd en ingezonden kan worden. In 2005 werden er meer dan
elfduizend port-PR's ingestuurd! Het volgen van dit artikel helpt
ons enorm om de tijd te verkorten die nodig is om uw PR's te
behandelen.</para>
<para>De <link xlink:href="&url.base;/cgi/query-pr-summary.cgi?query">
Probleemrapportendatabase</link>.</para>
<para><link xlink:href="http://pointyhat.FreeBSD.org/">Pointyhat</link>
is het bouwcluster voor ports. U kunt Pointyhat gebruiken om
bouwlogs van ports over alle architecturen en grote uitgaven te
controleren.</para>
<para>Het <link xlink:href="http://portsmon.FreeBSD.org/">&os; Ports Monitoring
System </link> kan u kruislingse informatie over ports zoals
bouwfouten en probleemrapporten laten zien. Als u een onderhouder
bent kunt u het gebruiken om de bouwstatus van uw ports te
controleren. Als een vrijwilliger kunt u het gebruiken om kapotte
en niet-onderhouden ports te vinden die gerepareerd moeten
worden.</para>
<para>De <link xlink:href="http://portscout.FreeBSD.org">scanner voor distributiebestanden
voor &os; ports</link> kan u ports laten zien waarvoor
de distributiebestanden niet kunnen worden opgehaald. U kunt uw
eigen ports controleren of u kunt het gebruiken om ports te vinden
waarvan de <varname>MASTER_SITES</varname> moet worden
bijwerkt.</para>
<para>De <application>tinderbox</application> voor ports is de meest
grondige manier om een port door de gehele cyclus van installatie,
inpakken, en deïnstallatie te halen. Het biedt een
opdrachtregelinterface maar kan ook via een webinterface worden
beheerd. Meer informatie staat op de <link xlink:href="http://tinderbox.marcuscom.com/">marcuscom tinderbox
homepage</link>.</para>
<para>&man.portlint.1; is een applicatie die gebruikt kan worden om
te verifiëren dat uw port zich aan vele belangrijke
stilistische en functionele richtlijnen houdt.
<application>portlint</application> is een eenvoudige heuristieke
applicatie, dus dient u het <emphasis>alleen als gids</emphasis>
te gebruiken. Als <application>portlint</application>
veranderingen voorstelt die onredelijk lijken, raadpleeg dan het
<link xlink:href="&url.books.porters-handbook.en;">Porter's Handbook</link>
of vraag om advies.</para>
<para>De &a.ports; dient voor algemene ports-gerelateerde
discussies. Het is een goede plaats om hulp te vragen. U kunt
<link xlink:href="http://lists.freebsd.org/mailman/listinfo">zich
aanmelden, of de lijstarchieven lezen en doorzoeken</link>.
Het lezen van de archieven van de &a.ports-bugs; en de
&a.cvs-ports; kan ook interessant zijn.</para>
</sect1>
<index/>
</article>

1
pt_BR.ISO8859-1/articles/Makefile
View file

@ -11,7 +11,6 @@
SUBDIR =
SUBDIR+= building-products
SUBDIR+= contributing
SUBDIR+= contributing-ports
SUBDIR+= explaining-bsd
SUBDIR+= freebsd-questions
SUBDIR+= freebsd-update-server

24
pt_BR.ISO8859-1/articles/contributing-ports/Makefile
View file

@ -1,24 +0,0 @@
#
# The FreeBSD Documentation Project
# The FreeBSD Brazilian Portuguese Documentation Project
#
# $FreeBSD$
#
# Original revision: r38826
#
# Article: Contributing to the FreeBSD Ports Collection
DOC?= article
FORMATS?= html html-split
WITH_ARTICLE_TOC?= YES
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.xml
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

1054
pt_BR.ISO8859-1/articles/contributing-ports/article.xml
View file

File diff suppressed because it is too large Load diff