<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!--
The FreeBSD Documentation Project
The FreeBSD German Documentation Project
$FreeBSD$
$FreeBSDde: de-docproj/books/developers-handbook/policies/chapter.sgml,v 1.14 2011/12/24 13:42:24 bcr Exp $
basiert auf: 1.38
-->
<chapter id="policies">
<chapterinfo>
<authorgroup>
<author>
<firstname>Poul-Henning</firstname>
<surname>Kamp</surname>
<contrib>Beigesteuert von </contrib>
</author>
<author>
<firstname>Giorgos</firstname>
<surname>Keramidas</surname>
</author>
</authorgroup>
<!-- June 1996 -->
<authorgroup>
<author>
<firstname>Axel</firstname>
<surname>Gruner</surname>
<contrib>Übersetzt von </contrib>
</author>
</authorgroup>
</chapterinfo>
<title>Vorgaben und Richtlinien für das
Quelltextverzeichnis</title>
<para>Dieses Kapitel dokumentiert verschiedene Vorgaben und
Richtlinien für das FreeBSD-Quelltextverzeichnis.</para>
<sect1 id="policies-style">
<title>Stil-Richtlinien</title>
<indexterm><primary>style</primary></indexterm>
<para>Ein konsistenter Code-Stil ist extrem wichtig, besonders
in einem so grossen Projekt wie &os;. Der Code sollte dem
&os; Code-Stil entsprechen, welcher in &man.style.9; und
&man.style.Makefile.5; genauer beschrieben ist.</para>
</sect1>
<sect1 id="policies-maintainer">
<title><makevar>MAINTAINER</makevar> eines Makefiles</title>
<indexterm><primary>Ports-Maintainer</primary></indexterm>
<para>Wenn ein bestimmter Bereich der &os;
<filename>src/</filename>-Distribution von einer Person oder Gruppe
gepflegt wird, kann dies durch einen Eintrag in die Datei
<filename>src/MAINTAINERS</filename> der Öffentlichkeit
mitgeteilt werden. Maintainer eines Ports in der Ports-Sammlung
können ihre Verantwortung über den Port durch einen Eintrag in
die <makevar>MAINTAINER</makevar>-Zeile im <filename>Makefile</filename>
des Ports der Welt mitteilen.</para>
<programlisting><makevar>MAINTAINER</makevar>= <replaceable>email-addresses</replaceable></programlisting>
<tip>
<para>Für andere Teile des Repositories oder andere Abschnitte, die
noch keinen Maintainer aufweisen, oder falls Sie sich nicht sicher
sind, wer der Maintainer ist, sehen Sie sich die Commit-Historie des
betreffenden Ports an. Es ist recht häufig der Fall, dass ein
Maintainer nicht explizit aufgeführt ist, aber trotzdem diejenigen
Personen, die den Port seit den letzten paar Jahren aktiv betreuen,
daran interessiert sind, Änderungen zu begutachten. Selbst wenn
dies nicht explizit in der Dokumentation oder im Quellcode erwähnt
ist, wird es trotzdem als höfliche Geste angesehen, wenn man
nach einer Überprüfung der eigenen Änderungen
fragt.</para>
</tip>
<para>Die Rolle eines Maintainers ist die folgende:</para>
<itemizedlist>
<listitem>
<para>Der Maintainer ist verantwortlich für diesen Code. Er
oder sie muss einerseits für die Behebung von Fehlern und das
Beantworten von Problemberichten für diesen Code die
Verantwortung tragen und andererseits, falls es sich um beigesteuerte
Software handelt, neue Versionen verfolgen und bereitstellen.</para>
</listitem>
<listitem>
<para>Änderungen an Verzeichnissen, die ein Maintainer definiert
hat, sollten an den Maintainer für eine Überprüfung
gesendet werden, bevor diese committet werden. Nur wenn der
Maintainer in einer inakzeptablen Zeitspanne auf mehrere E-Mails
nicht antwortet, können die Änderungen, die mit dem Commit
in Kraft treten, auch ohne Überprüfung durch den Maintainer
vollzogen werden. Dennoch wird empfohlen, dass die Änderungen,
falls möglich, von jemand anderem überprüft
werden.</para>
</listitem>
<listitem>
<para>Es ist natürlich nicht akzeptabel, einer Person oder Gruppe
den Status eines Maintainers zu geben, so lange sie nicht zustimmt,
diese Pflicht auf sich zu nehmen. Andererseits muss es kein einzelner
Mensch sein. Eine Gruppe von Menschen ist genauso in Ordnung.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="policies-contributed">
<sect1info>
<authorgroup>
<author>
<firstname>Poul-Henning</firstname>
<surname>Kamp</surname>
<contrib>Beigesteuert von </contrib>
</author>
<author>
<firstname>David</firstname>
<surname>O'Brien</surname>
</author>
<author>
<firstname>Gavin</firstname>
<surname>Atkinson</surname>
</author>
</authorgroup>
<!-- June 1996 -->
</sect1info>
<title>Beigesteuerte Software</title>
<indexterm><primary>Beigesteuerte Software</primary></indexterm>
<para>Einige Teile der FreeBSD-Distribution enthalten Software,
die aktiv außerhalb des FreeBSD-Projektes gepflegt wird.
Aus historischen Gründen nennen wir dies
<emphasis>contributed</emphasis> Software. Beispiele dafür
sind <application>sendmail</application>,
<application>gcc</application> und
<application>patch</application>.</para>
<para>Über die Jahre wurden verschiedene Methoden genutzt,
um solche Software zu verwalten, und jede hat Vor-
wie auch Nachteile. So hat sich kein eindeutiger Gewinner
herauskristallisiert.</para>
<para>Es wurde viel über diesen Umstand diskutiert und
eine Methode als die <quote>offizielle</quote>
vorgestellt, um in Zukunft diese Art der Software zu
importieren. Ferner wird dringend geraten, dass sich
existierende, beigesteuerte Software diesem Modell
annähert, da es signifikante Vorteile gegenüber der
alten Methode gibt. Dazu gehört auch, dass jeder
einfach Diffs bezüglich der
<quote>offiziellen</quote> Quelltext-Versionen erzeugen kann
(auch ohne direkten Repository-Zugang). Dies wird es deutlich
vereinfachen, Änderungen an die Hauptentwickler
zurückfließen zu lassen.</para>
<para>Letztendlich kommt es jedoch auf die Menschen an, welche die
Arbeit leisten. Wenn die Durchführung dieses Modells bei
einem Paket mal nicht möglich ist, können Ausnahmen
dieser Regeln nur mit Genehmigung des Core-Teams und der
Übereinstimmung der anderen Entwickler gewährt werden.
Die Fähigkeit, dieses Paket auch in Zukunft pflegen zu
können, ist eine der Schlüsselfragen bei dieser
Entscheidung.</para>
<note>
<para>Durch einige bedauernswerte Einschränkungen des <acronym
role="Revision Control System">RCS</acronym>-Dateiformats und die
Handhabung von Herstellerzweigen ist von unwesentlichen, trivialen
und/oder kosmetischen Änderungen an Dateien <emphasis>dringend
abzuraten</emphasis>, die dem Herstellerzweig folgen.
<quote>Grammatikalische oder sprachliche
Fehlerbehebungen</quote> sind explizit unter der
<quote>Kosmetik</quote>-Kategorie einzuordnen und sollten vermieden
werden. Das Repository kann sich durch Änderungen einzelner
Zeichen dramatisch aufblähen.</para>
</note>
<sect2 id="vendor-imports-cvs">
<title>Herstellerimports mit CVS</title>
<para>Das <application>file</application>-Werkzeug soll als Beispiel
dienen, wie dieses Modell funktioniert:</para>
<para><filename>src/contrib/file</filename> enthält den
Quelltext so, wie vom Maintainer dieses Pakets bereitgestellt.
Teile, die unter &os; gänzlich unnutzbar sind, können entfernt
werden. Im Fall von &man.file.1; wurde u.a. das Unterverzeichnis
<filename>python</filename> und Dateien mit dem Präfix
<filename>lt</filename> vor dem Import entfernt.</para>
<para><filename>src/lib/libmagic</filename> enthält ein
<filename>Makefile</filename> im <application>bmake</application>-Stil,
das die Regeln des Standard-Makefiles <filename>bsd.lib.mk</filename>
nutzt, um die Bibliothek zu erstellen und die Dokumentation zu
installieren.</para>
<para><filename>src/usr.bin/file</filename> enthält ein
<filename>Makefile</filename> im <application>bmake</application>-Stil,
welches das <command>file</command>-Programm erstellt und installiert,
ebenso die dazugehörigen Manualpages, welche die Regeln von
<filename>bsd.prog.mk</filename> nutzen.</para>
<para>Das Entscheidende ist hier das
<filename>src/contrib/file</filename>-Verzeichnis, welches nach
den folgenden Regeln erstellt wird: Es muss den
Quelltext aus dem Original enthalten (ohne
<acronym>RCS</acronym>-Schlüsselworte und im korrekten
Herstellerzweig) mit so wenig FreeBSD-spezifischen Änderungen wie
möglich. Sollte es Zweifel geben, wie hier zu verfahren
ist, unbedingt zuerst nachfragen und nicht auf gut Glück etwas
probieren in der vagen Hoffnung, dass es
<quote>irgendwie funktioniert</quote>.</para>
<para>Aufgrund der eingangs schon erwähnten Einschränkungen
bei Herstellerzweigen ist es erforderlich, dass <quote>offizielle</quote>
Fehlerbehebungen vom Hersteller in die Originalquellen der Distribution
einfließen und als Resultat wieder in den Herstellerzweig
importiert werden. Offizielle Fehlerbehebungen sollten nie direkt in
FreeBSD eingepflegt und <quote>committet</quote> werden, da dies
den Herstellerzweig zerstören würde und der Import
von zukünftigen Versionen wäre um ein Vielfaches
schwerer, da es zu Konflikten kommen würde.</para>
<para>Da einige Pakete Dateien enthalten, die zur
Kompatibilität mit anderen Architekturen und Umgebungen
als FreeBSD gedacht sind, ist es zulässig, diese Teile zu
löschen, wenn sie für FreeBSD nicht von Interesse
sind, und so Speicherplatz zu sparen. Dateien, die ein
Copyright und Release-artige Informationen zu den vorhandenen
Dateien enthalten, sollten <emphasis>nicht</emphasis>
gelöscht werden.</para>
<para>Falls es einfacher erscheint, können die
<command>bmake</command>-<filename>Makefile</filename>s vom
Verzeichnisbaum durch einige Dienstprogramme automatisch
erstellt werden, was es hoffentlich sogar noch einfacher macht,
eine Version zu aktualisieren. Ist dies geschehen, so stellen
Sie bitte sicher, diese Werkzeuge in das Verzeichnis
<filename>src/tools</filename> gleich mit dem Port an sich
einzuchecken, sodass es für zukünftige Maintainer
verfügbar ist.</para>
<para>Im Verzeichnis <filename>src/contrib/file</filename> sollte
eine Datei mit dem Namen <filename>FREEBSD-upgrade</filename>
hinzugefügt werden und sie sollte den Stand wie folgt
anzeigen:</para>
<itemizedlist>
<listitem>
<para>Welche Dateien ausgelassen wurden.</para>
</listitem>
<listitem>
<para>Von wo die Original-Distribution stammt und/oder wo die
offizielle Hauptseite zu finden ist.</para>
</listitem>
<listitem>
<para>Wohin Fehlerbehebungen an den Originalautor gesendet
werden können.</para>
</listitem>
<listitem>
<para>Möglicherweise eine Übersicht, welche
FreeBSD-spezifischen Änderungen vorgenommen
wurden.</para>
</listitem>
</itemizedlist>
<para>Ein Beispielinhalt von
<filename>src/contrib/groff/FREEBSD-upgrade</filename> ist hier
aufgelistet:</para>
<programlisting>$FreeBSD: src/contrib/groff/FREEBSD-upgrade,v 1.5.12.1 2005/11/15 22:06:18 ru Exp $
This directory contains virgin sources of the original distribution files
on a "vendor" branch. Do not, under any circumstances, attempt to upgrade
the files in this directory via patches and a cvs commit.
To upgrade to a newer version of groff, when it is available:
1. Unpack the new version into an empty directory.
[Do not make ANY changes to the files.]
2. Use the command:
cvs import -m 'Virgin import of FSF groff v<version>' \
src/contrib/groff FSF v<version>
For example, to do the import of version 1.19.2, I typed:
cvs import -m 'Virgin import of FSF groff v1.19.2' \
src/contrib/groff FSF v1_19_2
3. Follow the instructions printed out in step 2 to resolve any
conflicts between local FreeBSD changes and the newer version.
Do not, under any circumstances, deviate from this procedure.
To make local changes to groff, simply patch and commit to the main
branch (aka HEAD). Never make local changes on the FSF branch.
All local changes should be submitted to Werner Lemberg <wl@gnu.org> or
Ted Harding <ted.harding@nessie.mcc.ac.uk> for inclusion in the next
vendor release.
ru@FreeBSD.org - 20 October 2005</programlisting>
<para>Eine weitere Möglichkeit ist es, eine Liste von Dateien, die
nicht enthalten sein sollen zu pflegen, was besonders dann sehr hilfreich
sein kann, wenn die Liste ziemlich gross oder kompliziert ist bzw.
Imports sehr häufig stattfinden. Durch erstellen einer Datei namens
<filename>FREEBSD-Xlist</filename> im gleichen Verzeichnis, in welches
das Herstellerverzeichnis importiert werden soll, die eine Liste von
auszuschliessenden Dateinamen-Mustern pro Zeile enthält, können
zukünftige Imports folgendermassen durchgeführt werden:</para>
<screen>&prompt.user; <userinput><command>tar</command> <option>-X</option> <filename>FREEBSD-Xlist</filename> <option>-xzf</option> <filename><replaceable>vendor-source.tgz</replaceable></filename></userinput></screen>
<para>Als Beispiel einer <filename>FREEBSD-Xlist</filename>-Datei wird
hier diejenige von <filename>src/contrib/tcsh</filename> gezeigt:</para>
<programlisting>*/BUGS
*/config/a*
*/config/bs2000
*/config/bsd
*/config/bsdreno
*/config/[c-z]*
*/tests
*/win32</programlisting>
<note>
<para>Bitte importieren Sie weder <filename>FREEBSD-upgrade</filename>
noch <filename>FREEBSD-Xlist</filename> mit den beigesteuerten
Quellen. Stattdessen sollten Sie diese Dateien nach dem initialen
Import hinzufügen.</para>
</note>
</sect2>
<sect2 id="vendor-import-svn">
<sect2info>
<authorgroup>
<author>
<firstname>Dag-Erling</firstname>
<surname>Smørgrav</surname>
<contrib>Beigetragen von </contrib>
</author>
</authorgroup>
</sect2info>
<title>Herstellerimports mit SVN</title>
<para>Dieser Abschnitt beschreibt die Prozedur für Herstellerimports
mit <application>Subversion</application> im Detail.</para>
<procedure>
<step>
<title>Vorbereiten des Quellbaums</title>
<para>Wenn dies Ihr erster Import nach dem Wechsel zu
<acronym>SVN</acronym> ist, sollen Sie den Herstellerbaum
aufräumen, verflachen und die Merge-Historie in den Hauptzweig
vorbereiten. Falls das nicht Ihr erster Import ist, können
Sie diesen Schritt ohne Probleme überspringen.</para>
<para>Während der Konvertierung von <acronym>CVS</acronym> zu
<acronym>SVN</acronym> wurden Herstellerzweige mit der gleichen
Struktur wie der Hauptzweig importiert. Beispielsweise wurden die
<application>foo</application> Herstellerquellen in
<filename>vendor/<replaceable>foo</replaceable>/dist/contrib/<replaceable>foo</replaceable></filename>
abgelegt, jedoch ist dies unpraktisch und zwecklos. Was wir wirklich
wollen, ist dass die Herstellerquellen direkt in
<filename>vendor/<replaceable>foo</replaceable>/dist</filename>
liegen, beispielsweise so:</para>
<screen>&prompt.user; <userinput><command>cd</command> <filename class="directory">vendor/<replaceable>foo</replaceable>/dist/contrib/<replaceable>foo</replaceable></filename></userinput>
&prompt.user; <userinput><command>svn move</command> $(svn list) <filename>../..</filename></userinput>
&prompt.user; <userinput><command>cd</command> <filename>../..</filename></userinput>
&prompt.user; <userinput><command>svn remove</command> <filename>contrib</filename></userinput>
&prompt.user; <userinput><command>svn propdel</command> <option>-R</option> svn:mergeinfo</userinput>
&prompt.user; <userinput><command>svn commit</command></userinput></screen>
<para>Beachten Sie, dass das <literal>propdel</literal>-Bit notwendig
ist, da mit Subversion 1.5 automatisch
<literal>svn:mergeinfo</literal> zu jedem Verzeichnis
hinzugefügt wird, das Sie kopieren oder verschieben. In diesem
Fall brauchen Sie diese Informationen nicht, da Sie nichts in den
Zweig mergen werden, den Sie gelöscht haben.</para>
<note>
<para>Sie werden wahrscheinlich die Tags genauso verflachen wollen.
Die Prozedur dafür ist die selbe. Wenn Sie dies tun, sollten
Sie den Commit bis zum Schluss aufschieben.</para>
</note>
<para>Prüfen Sie den <filename>dist</filename>-Baum und
führen Sie alle nötigen Aufräumarbeiten durch, die Sie
für sinnvoll erachten. Sie werden möglicherweise die
Erweiterung von Schlüsselwörtern deaktivieren wollen, da
dies auf unmodifizierten Quellen keinen Sinn ergibt. In machen
Fällen kann dies sogar schädlich sein.</para>
<screen>&prompt.user; <userinput><command>svn propdel</command> svn:keywords <option>-R</option> <filename>.</filename></userinput>
&prompt.user; <userinput><command>svn commit</command></userinput></screen>
<para>Bootstrappen der <literal>svn:mergeinfo</literal> auf dem
Zielverzeichnis (des Hauptzweiges) auf die Revision die mit der
letzten Änderung, die im Herstellerzweig vor dem Import der
neuen Quellen durchgeführt wurde, korrespondiert, wird ebenso
benötigt:</para>
<screen>&prompt.user; <userinput><command>cd</command> <filename>head/contrib/<replaceable>foo</replaceable></filename></userinput>
&prompt.user; <userinput><command>svn merge</command> <option>--record-only</option> <replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist@<replaceable>12345678</replaceable> <filename>.</filename></userinput>
&prompt.user; <userinput><command>svn commit</command></userinput></screen>
<para>Dabei entspricht <replaceable>svn_base</replaceable> dem
Basisverzeichnis Ihres <acronym>SVN</acronym>-Repositories, z.B.
<literal>svn+ssh://svn.FreeBSD.org/base</literal>.</para>
</step>
<step>
<title>Neue Quellen importieren</title>
<para>Bereiten Sie einen kompletten, sauberen Baum mit
Herstellerquellen vor. Mit <acronym>SVN</acronym> können wir
eine komplette Distribution in dem Herstellerzweig aufbewahren, ohne
den Hauptzweig aufzublähen. Importieren Sie alles, aber mergen
Sie nur das, was wirklich benötigt wird.</para>
<para>Beachten Sie, dass Sie alle Dateien, die seit dem letzten
Herstellerimport hinzugefügt wurden, auch einbeziehen und
diejenigen, welche entfernt wurden, auch löschen
müssen. Um dies zu bewerkstelligen, sollten Sie sortierte
Listen der Bestandteile des Herstellerbaums und von den Quellen,
Sie die vorhaben zu importieren, vorbereiten:</para>
<screen>&prompt.user; <userinput><command>cd</command> <filename>vendor/<replaceable>foo</replaceable>/dist</filename></userinput>
&prompt.user; <userinput><command>svn list</command> <option>-R</option> | <command>grep</command> <option>-v</option> '/$' | <command>sort</command> > <filename>../<replaceable>old</replaceable></filename></userinput>
&prompt.user; <userinput><command>cd</command> <filename>../<replaceable>foo-9.9</replaceable></filename></userinput>
&prompt.user; <userinput><command>find</command> <filename>.</filename> <option>-type</option> f | <command>cut</command> <option>-c</option> 3- | <command>sort</command> > <filename>../<replaceable>new</replaceable></filename></userinput></screen>
<para>Mit diesen beiden Dateien, wird Ihnen das folgende Kommando alle
Dateien auflisten, die entfernt wurden (nur die Dateien in
<filename><replaceable>old</replaceable></filename>):</para>
<screen>&prompt.user; <userinput><command>comm <option>-23</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename></command></userinput></screen>
<para>Der folgende Befehl wird die hinzugefügten Dateien auflisten
(nur diejenigen Dateien in
<filename><replaceable>new</replaceable></filename>):</para>
<screen>&prompt.user; <userinput><command>comm <option>-13</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename></command></userinput></screen>
<para>Wir führen dies nun zusammen:</para>
<screen>&prompt.user; <userinput><command>cd</command> <filename class="directory">vendor/<replaceable>foo</replaceable>/<replaceable>foo-9.9</replaceable></filename></userinput>
&prompt.user; <userinput><command>tar</command> cf - <filename>.</filename> | <command>tar</command> xf - <option>-C</option> <filename>../dist</filename></userinput>
&prompt.user; <userinput><command>cd</command> <filename class="directory">../dist</filename></userinput>
&prompt.user; <userinput><command>comm</command> <option>-23</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename> | <command>xargs</command> svn remove</userinput>
&prompt.user; <userinput><command>comm</command> <option>-13</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename> | <command>xargs</command> svn add</userinput></screen>
<warning>
<para>Wenn in der neuen Version neue Verzeichnisse hinzugekommen
sind, wird dieser letzte Befehl fehlschlagen. Sie müssen
diese Verzeichnisse hinzufügen und anschliessend den Befehl
erneut ausführen. Genauso müssen Sie Verzeichnisse, die
entfernt wurden, händisch löschen.</para>
</warning>
<para>Prüfen Sie die Eigenschaften jeder neuen Datei:</para>
<itemizedlist>
<listitem>
<para>Alle Textdateien sollten <literal>svn:eol-style</literal> auf
den Wert <literal>native</literal> gesetzt haben.</para>
</listitem>
<listitem>
<para>Alle Binärdateien sollten
<literal>svn:mime-type</literal> auf
<literal>application/octet-stream</literal> gesetzt haben,
ausser es existiert ein passenderer Medientyp.</para>
</listitem>
<listitem>
<para>Ausführbare Dateien sollten
<literal>svn:executable</literal> auf <literal>*</literal>
gesetzt haben.</para>
</listitem>
<listitem>
<para>Es sollten keine anderen Eigenschaften auf den Dateien im
Baum gesetzt sein.</para>
</listitem>
</itemizedlist>
<note>
<para>Sie sind bereit, zu committen, jedoch sollten Sie zuerst die
Ausgabe von <command>svn stat</command> und <command>svn
diff</command> überprüfen, um sicher zu gehen, dass alles
in Ordnung ist.</para>
</note>
<para>Sobald Sie den die neue Release-Version des Herstellers
committed haben, sollten Sie Ihn für zukünftige Referenzen
taggen. Die beste und schnellste Methode ist, dies direkt im
Repository zu tun:</para>
<screen>&prompt.user; <userinput><command>svn copy</command> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/<replaceable>9.9</replaceable></filename></userinput></screen>
<para>Um den neuen Tag zu bekommen, brauchen Sie nur ihre Arbeitskopie
von <filename>vendor/<replaceable>foo</replaceable></filename> zu
aktualisieren.</para>
<note>
<para>Wenn Sie lieber die Kopie in der ausgecheckten Kopie
durchführen wollen, vergessen Sie nicht, die generierte
<literal>svn:mergeinfo</literal> wie oben beschrieben zu
entfernen.</para>
</note>
</step>
<step>
<title>Mit <emphasis>-HEAD</emphasis> mergen</title>
<para>Nachdem Sie Ihren Import vorbereitet haben, wird es Zeit zu
mergen. Die Option <option>--accept=postpone</option> weist
<acronym>SVN</acronym> an, noch keine merge-Konflikte
aufzulösen, weil wir uns um diese manuell kümmern
werden:</para>
<screen>&prompt.user; <userinput><command>cd</command> <filename class="directory">head/contrib/<replaceable>foo</replaceable></filename></userinput>
&prompt.user; <userinput><command>svn update</command></userinput>
&prompt.user; <userinput><command>svn merge</command> <option>--accept=postpone</option> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename></userinput></screen>
<para>Lösen Sie die Konflikte und stellen Sie sicher, dass alle
Dateien, die im Herstellerzweig hinzugefügt oder entfernt
wurden, auch sauber im Hauptzweig hinzugefügt bzw. gelöscht
wurden. Es ist immer ratsam, diese Unterschiede gegen den
Herstellerbaum zu prüfen:</para>
<screen>&prompt.user; <userinput><command>svn diff</command> <option>--no-diff-deleted</option> <option>--old=</option><filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename> <option>--new=</option><filename>.</filename></userinput></screen>
<para>Die Option <option>--no-diff-deleted</option> weist
<acronym>SVN</acronym> an, keine Dateien zu prüfen, die sich
zwar im Herstellerbaum, aber nicht im Hauptzweig befinden.</para>
<note>
<para>Bei <acronym>SVN</acronym> gibt es das Konzept von innerhalb
und ausserhalb des Herstellerbaums nicht. Wenn eine Datei, die
zuvor eine lokale Änderung hatte, aber nun keine mehr
besitzt, entfernen Sie einfach das was übrig ist, wie &os;
Versionstags, damit diese nicht länger in den diffs gegen
den Herstellerbaum erscheinen.</para>
</note>
<para>Wenn irgendwelche Änderungen notwendig sind, um die Welt
mit den neuen Quellen zu bauen, machen Sie diese jetzt und testen
Sie diese bis Sie sicher sind, dass alles korrekt gebaut wird und
richtig funktionert.</para>
</step>
<step>
<title>Commit</title>
<para>Nun sind Sie bereit für den Commit. Stellen Sie sicher,
dass Sie alles in einem einzigen Schritt durchführen.
Idealerweise sollten Sie alle diese Schritte in einem sauberen Baum
durchgeführt haben. Falls dies der Fall ist, können Sie
einfach aus dem obersten Verzeichnis dieses Baums committen. Dies
ist der beste Weg, um Überraschungen zu vermeiden. Wenn Sie
dies korrekt durchführen, wird der Baum atomar von einem
konsistenten Zustand mit dem alten Code in einen neuen konsistenten
Zustand mit dem neuen Code überführt.</para>
</step>
</procedure>
</sect2>
</sect1>
<sect1 id="policies-encumbered">
<title>Belastende Dateien</title>
<para>Es kann gelegentlich notwendig sein, belastende Dateien
in den FreeBSD-Quelltextbaum zu integrieren. Braucht ein
Gerät zum Beispiel ein Stück binären Code, der
zuerst geladen werden muss, bevor das Gerät funktioniert,
und wir haben keine Quellen zu diesem Code, dann wird die
binäre Datei als belastend bezeichnet. Die folgenden
Richtlinien sind beim Aufnehmen von belastenden Dateien in den
FreeBSD-Quelltextbaum zu beachten.</para>
<orderedlist>
<listitem>
<para>Jede Datei, die durch die System-CPU(s) ausgeführt
wird und nicht als Quelltext vorliegt, ist belastend.</para>
</listitem>
<listitem>
<para>Jede Datei, deren Lizenz restriktiver ist als die BSD-
oder GNU-Lizenz, ist belastend.</para>
</listitem>
<listitem>
<para>Eine Datei, die herunterladbare Binär-Daten
enthält, ist nur belastend, wenn (1) oder (2)
zutreffen. Sie muss in einem ASCII-Format
gespeichert werden, das Architektur-neutral ist (file2c
oder uuencoding wird empfohlen).</para>
</listitem>
<listitem>
<para>Jede belastende Datei braucht eine spezielle
Genehmigung vom <ulink
url="&url.base;/administration.html#t-core">Core-Team</ulink>,
bevor diese in das Repository aufgenommen werden darf.</para>
</listitem>
<listitem>
<para>Belastende Dateien liegen unter
<filename>src/contrib</filename> oder
<filename>src/sys/contrib</filename>.</para>
</listitem>
<listitem>
<para>Das komplette Modul sollte auch am Stück
aufbewahrt werden. Es gibt keinen Grund, dieses zu teilen,
außer es gibt einen Code-Austausch mit Quelltext, der
nicht belastend ist.</para>
</listitem>
<listitem>
<para>Objekt-Dateien werden wie folgt benannt:
<filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para>
</listitem>
<listitem>
<para>Kernel-Dateien:</para>
<orderedlist>
<listitem>
<para>Sollten immer nach
<filename>conf/files.*</filename> verweisen (um den Bau
einfach zu halten).</para>
</listitem>
<listitem>
<para>Sollten sich immer in <filename>LINT</filename>
befinden, jedoch entscheidet das <ulink
url="&url.base;/administration.html#t-core">Core-Team</ulink>
je nach Fall, ob es
auskommentiert wird oder nicht. Das <ulink
url="&url.base;/administration.html#t-core">Core-Team</ulink>
kann sich zu einem späteren Zeitpunkt
immer noch anders entscheiden.</para>
</listitem>
<listitem>
<para>Der <firstterm>Release-Engineer</firstterm>
entscheidet, ob es in ein Release aufgenommen wird oder
nicht.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Userland-Dateien:</para>
<orderedlist>
<listitem>
<indexterm><primary>Core-Team</primary></indexterm>
<para>Das <ulink
url="&url.base;/administration.html#t-core">Core-Team</ulink>
entscheidet, ob der Code von
<command>make world</command> gebaut wird oder nicht.</para>
</listitem>
<listitem>
<indexterm><primary>Release-Engineer</primary></indexterm>
<para>Der <ulink
url="&url.base;/administration.html#t-re">Release-Engineer</ulink>
entscheidet, ob es in das Release
aufgenommen wird oder nicht.</para>
</listitem>
</orderedlist>
</listitem>
</orderedlist>
</sect1>
<sect1 id="policies-shlib">
<sect1info>
<authorgroup>
<author>
<firstname>Satoshi</firstname>
<surname>Asami</surname>
<contrib>Beigesteuert von </contrib>
</author>
<author>
<firstname>Peter</firstname>
<surname>Wemm</surname>
</author>
<author>
<firstname>David</firstname>
<surname>O'Brien</surname>
</author>
</authorgroup>
<!-- 9 Dec 1996 -->
</sect1info>
<title>Shared-Libraries</title>
<para>Sollten Sie die Unterstützung für
Shared-Libraries bei einem Port oder einem Stück Software,
das dies nicht hat, hinzufügen, sollten die Versionsnummern
dessen Regeln folgen. Im Allgemeinen hat die sich daraus
resultierende Nummer nichts mit der Release-Version der Software
zu tun.</para>
<para>Die drei Grundsätze zum Erstellen von Shared-Libraries
sind:</para>
<itemizedlist>
<listitem>
<para>Sie beginnen mit <literal>1.0</literal>.</para>
</listitem>
<listitem>
<para>Gibt es eine Änderung, die
abwärtskompatibel ist, so springen Sie zur
nächsten Minor-Version (beachten Sie, dass ELF-Systeme
die Minor-Version ignorieren).</para>
</listitem>
<listitem>
<para>Gibt es eine inkompatible Änderung, so springen
Sie bitte zur nächsten Major-Version.</para>
</listitem>
</itemizedlist>
<para>Zum Beispiel wird beim Hinzufügen von Funktionen und
oder Fehlerbehebungen zur nächsten Minor-Version
gesprungen, beim Löschen einer Funktion, Ändern
von Funktionsaufrufen usw. ändert sich die Major-Version.</para>
<para>Bleiben Sie bei Versionsnummern in der Form major.minor
(<replaceable>x</replaceable>.<replaceable>y</replaceable>).
Unser dynamischer Linker a.out kann mit Versionsnummern
in der Form
<replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
nicht gut umgehen.
Jede Versionsnummer nach dem <replaceable>y</replaceable>
(die dritte Zahl) wird völlig ignoriert, wenn
Versionsnummern der Shared-Libraries verglichen werden, um
zu bestimmen, mit welcher Bibliothek eine Anwendung verlinkt wird.
Sind zwei Shared-Libraries vorhanden, die sich nur in der
<quote>micro</quote>-Revision unterscheiden, so wird
<command>ld.so</command> zu der höheren verlinken.
Dies bedeutet, dass wenn Sie mit <filename>libfoo.so.3.3.3</filename>
verlinken, der Linker nur <literal>3.3</literal> in den
Header aufnimmt und alles linkt, was mit
<replaceable>libfoo.so.3</replaceable>
.<replaceable>(irgendetwas
>= 3)</replaceable>.<replaceable>(höchste
verfügbare Nummer)</replaceable> beginnt.</para>
<note>
<para><command>ld.so</command> wird immer die höchste
<quote>Minor</quote>-Revision benutzen. Beispielsweise wird
es die <filename>libc.so.2.2</filename> bevorzugen
gegenüber der <filename>libc.so.2.0</filename>, auch
dann, wenn das Programm ursprünglich mit
<filename>libc.so.2.0</filename> verlinkt war.</para>
</note>
<para>Unser dynamischer ELF-Linker kann keine Minor-Versionen
handhaben. Dennoch sollten die Major- und Minor-Versionen genutzt
werden, da unsere <filename>Makefile</filename>s <quote>das
Richtige machen</quote> bezogen auf den Systemtyp.</para>
<para>Für nicht-Port-Bibliotheken lautet die Richtlinie,
die Shared-Library-Versionsnummer nur einmal zwischen den
Releases zu ändern. Weiterhin ist es vorgeschrieben, die
Major-Version der Shared-Libraries nur bei Major-OS-Releases zu
ändern (beispielsweise von 6.0 auf 7.0). Wenn Sie also eine
Änderung an einer Systembibliothek vornehmen, die eine neue
Versionsnummer benötigt, überprüfen Sie die
Commit-Logs des <filename>Makefile</filename>s. Es liegt in der
Verantwortung des Committers, dass sich eine erste solche
Änderung seit dem letzten Release in der aktualisierten
Versionsnummer der Shared-Library im
<filename>Makefile</filename> äußert, folgende
Änderungen werden nicht berücksichtigt.</para>
</sect1>
</chapter>