                Probleemrapporten voor FreeBSD schrijven

  Dag-Erling Smo/rgrav

  Mark Linimon

   FreeBSD is een geregistreerd handelsmerk van de FreeBSD
   Foundation.

   CVSup is een geregistreerd handelsmerk van John D. Polstra.

   IBM, AIX, EtherJet, Netfinity, OS/2, PowerPC, PS/2, S/390, en
   ThinkPad zijn handelsmerken van International Business Machines
   Corporation in de Verenigde Staten, andere landen, of beide.

   Intel, Celeron, EtherExpress, i386, i486, Itanium, Pentium, en
   Xeon zijn handelsmerken of geregistreerde handelsmerken van Intel
   Corporation of haar dochterondernemingen in de Verenigde Staten en
   andere landen.

   SPARC, SPARC64, SPARCengine, and States and other countries. SPARC
   International, Inc owns all of the SPARC trademarks and under
   licensing agreements allows the proper use of these trademarks by
   its members.

   Sun, Sun Microsystems, Java, Java Virtual Machine, JavaServer
   Pages, JDK, JRE, JSP, JVM, Netra, OpenJDK, Solaris, StarOffice,
   Sun Blade, Sun Enterprise, Sun Fire, SunOS, Ultra en VirtualBox
   zijn handelsmerken of geregistreerde handelsmerken van Sun
   Microsystems, Inc. in de Verenigde Staten en andere landen.

   Veel van de termen die door fabrikanten en verkopers worden
   gebruikt om hun producten te onderscheiden worden geclaimd als
   handelsmerk. Op de plaatsen waar deze handelsmerken in dit
   document voorkomen, en het FreeBSD Project op de hoogte was van de
   claim op het handelsmerk, worden de termen gevolgd door het
   symbool "(TM)" of het symbool "(R)".

   Dit artikel beschrijft hoe een probleemrapport het beste
   geformuleerd en naar het FreeBSD Project verzonden kan worden.

   Vertaald door Rene Ladan.

     --------------------------------------------------------------

     --------------------------------------------------------------

1. Introductie

   Een van de meest frustrerende ervaringen die een gebruiker van
   software kan hebben is om een probleemrapport in te sturen om het
   vervolgens afgehandeld te zien met een korte en onbehulpzame
   uitleg als "geen bug" of "fout PR". Evenzo is een van de meest
   frustrerende ervaringen als ontwikkelaar van software om
   overspoeld te worden met probleemrapporten die niet echt een
   probleemrapport zijn maar ondersteuningsverzoeken, of die weinig
   tot geen informatie bevatten over wat het probleem is en hoe het
   te reproduceren.

   Dit document poogt te beschrijven hoe goede probleemrapporten te
   schrijven. Wat is een goed probleemrapport? Kort door de bocht is
   een goed probleemrapport een rapport dat geanalyseerd kan worden
   en waar snel mee kan worden omgegaan, voor de wederzijdse
   voldoening van zowel de gebruiker als de ontwikkelaar.

   Hoewel de nadruk van dit artikel ligt op probleemrapporten voor
   FreeBSD, zou het meeste ook in sterke mate op andere
   softwareprojecten van toepassing moeten zijn.

   Merk op dat dit artikel thematisch in plaats van chronologisch is
   ingedeeld, dus u dient het hele document te lezen alvorens een
   probleemrapport in te sturen, en het niet als een stapsgewijze
   tutorial te behandelen.

     --------------------------------------------------------------

2. Wanneer een probleemrapport te versturen

   Er zijn vele soorten problemen, die niet allemaal geschikt zijn
   voor een probleemrapport. Natuurlijk is niemand perfect dus zal
   het soms voorkomen dat u overtuigd bent dat u een bug in een
   programma heeft gevonden terwijl u in feite de syntaxis voor een
   commando verkeerd begrepen heeft of een typefout in een
   instellingenbestand gemaakt heeft (hoewel dat soms zelf al op
   slechte documentatie of slechte foutafhandeling in de applicatie
   kan wijzen). Er zijn nog steeds veel gevallen waarin het insturen
   van een probleemrapport duidelijk niet de juiste handeling is, en
   het alleen tot frustratie bij uzelf en de ontwikkelaars leidt.
   Omgekeerd zijn er gevallen waarin het juist kan zijn om een
   probleemrapport in te sturen over iets anders dan een
   bug--bijvoorbeeld voor een verbetering of een
   mogelijkheidsverzoek.

   Dus hoe wordt bepaald of iets wel of niet een bug is? Een
   eenvoudige vuistregel is dat uw probleem geen bug is als het als
   een vraag kan worden uitgedrukt (meestal van de vorm "Hoe doe ik
   X?" of "Waar kan ik Y vinden?"). Het is niet altijd zo zwart-wit,
   maar de vraagregel gaat in de meeste gevallen op. Overweeg, als u
   een antwoord zoekt, om uw vraag aan de FreeBSD algemene vragen
   mailinglijst te stellen.

   Enkele gevallen waar het juist kan zijn om een probleemrapport in
   te sturen over iets dat geen bug is zijn:

     * Verzoeken om verbetering van mogelijkheden. Het is over het
       algemeen een goed idee om deze op de mailinglijsten te uiten
       alvorens een probleemrapport in te sturen.

     * Meldingen van updates aan extern onderhouden software (over
       het algemeen ports, maar ook extern onderhouden componenten
       van het basissysteem zoals BIND of verscheidene gereedschappen
       van GNU).

       Voor onbeheerde ports (MAINTAINER bevat ports@FreeBSD.org) kan
       zo'n updatemelding opgepakt worden door een geinteresseerde
       committer, of u kunt gevraagd worden om een patch aan te
       leveren om de port bij te werken; door dit van te voren aan te
       bieden verhoogt u in sterke mate de kans dat de port binnen
       een redelijk tijdsbestek wordt bijgewerkt.

       Als de port beheerd wordt, zijn PR's die nieuwe
       stroomopwaartse uitgaven aankondigen niet erg nuttig aangezien
       ze aanvullend werk voor de committers genereren, en
       waarschijnlijk weet de beheerder al dat er een nieuwe versie
       uit is, ze hebben er waarschijnlijk met de ontwikkelaars aan
       gewerkt, ze zijn waarschijnlijk regressietesten aan het
       uitvoeren, enzovoorts.

       In beide gevallen zal het volgen van het proces zoals
       beschreven in het Porters Handboek tot de beste resultaten
       leiden. (U bent misschien ook geinteresseerd in Bijdragen aan
       de FreeBSD Portscollectie.)

   Een bug die niet reproduceerbaar is kan zelden gerepareerd worden.
   Als een bug slechts eenmalig voorkwam en u deze niet kunt
   reproduceren, en het bij niemand anders lijkt voor te komen, dan
   bestaat de kans dat geen van de ontwikkelaars het kan reproduceren
   of kan uitzoeken wat er mis is. Dit betekent niet dat het niet
   gebeurde, maar wel dat de kans dat uw probleemrapport ooit tot een
   reparatie leidt erg klein is. Om het allemaal erger te maken,
   worden dit soort bugs vaak veroorzaakt door falende harde schijven
   of oververhitte processoren -- u dient altijd te proberen om deze
   oorzaken, indien mogelijk, uit te sluiten voordat u een PR
   instuurt.

   Vervolgens, om te besluiten aan wie u uw probleemrapport dient te
   sturen, moet u weten dat de software waaruit FreeBSD bestaat uit
   verschillende elementen is opgebouwd:

     * Code in het basissysteem die geschreven is en onderhouden
       wordt door FreeBSD-vrijwilligers, zoals de kernel, de
       C-bibliotheek, en de apparaatstuurprogramma's (gecategoriseerd
       als kern); de binaire hulpmiddelen (bin); de
       handleidingpagina's en documentatie (docs); en de webpagina's
       (www). Alle bugs in deze gebieden dienen aan de
       FreeBSD-ontwikkelaars gerapporteerd te worden.

     * Code in het basissysteem die geschreven is en onderhouden
       wordt door anderen, en in FreeBSD is geimporteerd en
       aangepast. Voorbeelden zijn bind, gcc(1), en sendmail(8). De
       meeste bugs in deze gebieden dienen aan de
       FreeBSD-ontwikkelaars gerapporteerd te worden; maar in sommige
       gevallen kan het zijn dat ze aan de originele auteurs
       gerapporteerd moeten worden als de problemen niet specifiek
       voor FreeBSD zijn. Gewoonlijk vallen deze bugs in ofwel de
       categorie bin ofwel de categorie gnu.

     * Individuele applicaties die niet in het basissysteem zitten
       maar in plaats daarvan deel zijn van de Portscollectie van
       FreeBSD (categorie ports). De meeste van deze applicaties zijn
       niet geschreven door FreeBSD-ontwikkelaars; wat FreeBSD biedt
       is slechts een raamwerk om de applicatie te installeren.
       Daarom dient u alleen een probleem aan de
       FreeBSD-ontwikkelaars te rapporteren als u gelooft dat het
       probleem specifiek voor FreeBSD is; anders dient u het aan de
       auteurs van de software te rapporteren.

   Daarna dient u vast te stellen of het probleem actueel is. Er zijn
   maar weinig dingen die een ontwikkelaar meer irriteren dan het
   ontvangen van een probleemrapport over een bug die reeds
   gerepareerd is.

   Als het probleem in het basissysteem zit, dient u eerst het
   FAQ-gedeelte over FreeBSD-versies te lezen als u niet reeds bekend
   bent met het onderwerp. Het is niet mogelijk voor FreeBSD om
   problemen in iets anders dan bepaalde recente takken van het
   basissysteem op te lossen, dus leidt het insturen van een
   bug-rapport over een oudere versie waarschijnlijk alleen tot het
   advies van een ontwikkelaar om naar een ondersteunde versie bij te
   werken om te kijken of het probleem nog steeds voorkomt. Het
   Security Officer Team onderhoudt de lijst van ondersteunde
   versies.

   Als het probleem in een port zit, moet u uw Portscollectie eerst
   naar de laatste versie bijwerken en kijken of het probleem nog
   steeds van toepassing is. Wegens de hoge snelheid waarmee deze
   applicaties veranderen, is het onhaalbaar voor FreeBSD om iets
   anders dan de allernieuwste versies te ondersteunen, problemen met
   oudere versies van applicaties kunnen simpelweg niet worden
   opgelost.

     --------------------------------------------------------------

3. Voorbereidingen

   Een goede regel is om altijd een vooronderzoek te doen voordat u
   een probleemrapport ingestuurd. Misschien is uw probleem reeds
   gerapporteerd; misschien wordt het besproken op de mailinglijsten,
   of gebeurde dat recentelijk; misschien is het al gerepareerd in
   een nieuwere versie dan die u draait. Om deze redenen dient u alle
   voor de hand liggende plaatsen te controleren voordat u uw
   probleemrapport instuurt. Voor FreeBSD betekent dit:

     * De FreeBSD-lijst van Veelgestelde Vragen (FAQ). De FAQ
       probeert antwoord te geven op een breed scala aan vragen,
       zoals vragen die betrekking hebben op compatibiliteit van
       hardware, gebruikersapplicaties, en kernelconfiguratie.

     * De mailinglijsten--als u niet geabonneerd bent, gebruik dan de
       doorzoekbare archieven op de FreeBSD-website. Als uw probleem
       niet op de lijsten bediscussieerd is, kunt u proberen om er
       een bericht over te posten en enkele dagen wachten om te zien
       of iemand iets kan zien wat u misschien over het hoofd heeft
       gezien.

     * Optioneel, het gehele web--gebruik uw favoriete zoekmachine om
       referenties naar uw probleem te vinden. U kunt zelfs hits
       krijgen van gearchiveerde mailinglijsten of nieuwsgroepen die
       u niet kende of waarvan u er niet aan had gedacht om die te
       doorzoeken.

     * Vervolgens, de doorzoekbare FreeBSD PR-database (GNATS).
       Tenzij uw probleem recent of obscuur is, bestaat er een
       redelijke kans dat het reeds gerapporteerd is.

     * Het belangrijkste is dat u probeert te controleren of
       bestaande documentatie in de bronnen uw probleem bespreekt.

       Voor de basis-FreeBSD-code dient u zorgvuldig de inhoud van
       het bestand /usr/src/UPDATING op uw systeem of de laatste
       versie ervan op
       http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING te
       bestuderen. (Dit is essentiele informatie als u van de ene
       naar een andere versie bijwerkt--in het bijzonder als u naar
       de tak FreeBSD-CURRENT bijwerkt.)

       Als het probleem echter zit in iets wat als deel van de
       FreeBSD Portscollectie was geinstalleerd, dan dient u
       /usr/ports/UPDATING (voor individuele ports) of
       /usr/ports/CHANGES (voor veranderingen die de gehele
       Portscollectie beinvloeden) te raadplegen.
       http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING en
       http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES zijn ook
       beschikbaar via CVSweb.

     --------------------------------------------------------------

4. Het probleemrapport schrijven

   Nu u besloten heeft dat uw probleem een probleemrapport verdiend,
   en het een probleem met FreeBSD is, is het tijd om het eigenlijke
   probleemrapport te schrijven. Voordat het mechanisme van het
   programma dat gebruikt wordt om PR's aan te maken en in te sturen
   wordt behandeld, zijn hier wat tips en trucs die ervoor zorgen dat
   uw PR het meest effectief is.

     --------------------------------------------------------------

  4.1. Tips en trucs voor het schrijven van een goed probleemrapport

     * Laat de regel "Synopsis" niet leeg. De PR's gaan zowel naar
       een mailinglijst die over de gehele wereld wordt verspreid
       (waar de "Synopsis" wordt gebruikt voor de Onderwerp:-regel),
       als in een database. Iedereen die later de database op
       samenvatting doorzoekt, en een PR met een lege onderwerpsregel
       aantreft, zal het waarschijnlijk gewoon overslaan. Onthoud dat
       PR's in deze database blijven staan totdat iemand ze sluit;
       een anoniem PR zal slechts in de massa opgaan.

     * Voorkom het gebruik van een zwakke "Synopsis"-regel. U mag
       niet aannemen dat iemand die uw PR leest enige
       achtergrondkennis van uw inzending heeft, dus des meer u
       biedt, des te beter. Op welk deel van het systeem heeft het
       probleem betrekking? Ziet u het probleem alleen tijdens het
       installeren, of tijdens het draaien? Ter illustratie, in
       plaats van Synopsis: portupgrade is broken, zie hoeveel
       informatiever dit lijkt: Synopsis: port pors-mgmt/portupgrade
       coredumps on -current. (In het geval van ports is het
       bijzonder behulpzaam om zowel de categorie als de portnaam in
       de "Synopsis"-regel te vermelden.)

     * Als u een patch heeft, zeg dat dan. Het is veel
       waarschijnlijker dat een PR met daarin een patch bekeken wordt
       dan een PR zonder patch. Als u een patch bijsluit, plaats dan
       de tekst [patch] (inclusief de haken) aan het begin van de
       "Synopsis". (Alhoewel het niet verplicht is om die exacte
       tekst te gebruiken, is dat per conventie degene die gebruikt
       wordt.)

     * Als u een onderhouder bent, zeg dat dan. Als u een deel van de
       broncode onderhoudt (bijvoorbeeld een port), kunt u overwegen
       om de tekst [maintainer update] (inclusief de haken) aan het
       begin van de onderwerpsregel te plaatsen, en dient u zeker de
       "Class" van uw PR op maintainer-update te zetten. Op deze
       manier hoeft de committer die uw PR behandelt dit niet te
       controleren.

     * Ben specifiek. Des te meer informatie u aanlevert over wat
       voor probleem u heeft, des te groter is de kans dat u een
       antwoord krijgt.

          * Vermeld de versie van FreeBSD die u draait (hier is een
            plaats voor, zie hieronder) en op welke architectuur dat
            is. U dient aan te geven of u een uitgave draait
            (bijvoorbeeld een CD-ROM of een download), of een systeem
            dat met cvsup(1) wordt onderhouden (en zo ja, hoe
            recentelijk u dat heeft bijgewerkt). Als u de tak
            FreeBSD-CURRENT volgt, is dat het allereerste wat iemand
            zal vragen, omdat reparaties (in het bijzonder voor
            opvallende problemen) de neiging hebben om snel gecommit
            te worden, en gebruikers van FreeBSD-CURRENT worden
            geacht om hun zaken bij te houden.

          * Vermeld welke globale opties u in uw make.conf heeft
            gespecificeerd. Noot: het specificeren van -O2 en hoger
            aan gcc(1) staat in veel situaties als bug-gevoelig
            bekend. Hoewel de FreeBSD-ontwikkelaars patches zullen
            accepteren, zijn ze over het algemeen niet bereid om
            zulke gevallen te onderzoeken vanwege een simpel gebrek
            aan tijd en vrijwilligers, en zullen ze in plaats hiervan
            antwoorden met dat dit gewoon niet ondersteund is.

          * Als het probleem eenvoudig gereproduceerd kan worden,
            neem dan informatie op die een ontwikkelaar helpt om het
            probleem zelf te reproduceren. Al een probleem kan worden
            gedemonstreerd met specifieke invoer, neem dan een
            voorbeeld van die invoer op indien mogelijk, en neem
            zowel de eigenlijke als de verwachte uitvoer op. Als deze
            gegevens groot zijn of niet gepubliceerd kunnen worden,
            probeer dan om een minimaal bestand te maken dat
            hetzelfde probleem vertoont en dat in het PR kan worden
            opgenomen.

          * Als het een probleem met de kernel betreft, reken er dan
            op om de volgende informatie aan te leveren. (U hoeft
            deze niet standaard bij te sluiten, wat alleen de
            database opvult, maar u dient uittreksel bij te sluiten
            die u relevant acht):

               * uw kernelconfiguratie (inclusief welke
                 hardware-apparaten u heeft geinstalleerd)

               * of u wel of niet debug-opties aan heeft staan (zoals
                 WITNESS), en zo ja, of het probleem zich blijft
                 voordoen als u de optie omkeert

               * de volledige tekst van elke backtrace, panic of
                 andere console-uitvoer, of regels in
                 /var/log/messages als die waren gegenereerd

               * De uitvoer van pciconf -l en relevante gedeelten van
                 uw uitvoer van dmesg als uw probleem te maken heeft
                 met een bepaald stuk hardware.

               * het feit dat u /usr/src/UPDATING heeft gelezen en
                 dat uw probleem daar niet staat vermeld (iemand gaat
                 er geheid naar vragen)

               * of u wel of niet op het draaien van een andere
                 kernel kunt terugvallen (dit is om problemen
                 gerelateerd aan hardware zoals falende schijven en
                 oververhitte CPU's uit te sluiten, welke zich als
                 kernelprobleem kunnen vermommen)

          * Als het een probleem met de ports betreft, reken er dan
            op om de volgende informatie aan te leveren. (U hoeft
            deze niet standaard bij te sluiten, wat alleen de
            database opvult, maar u dient uittreksels bij te sluiten
            die u relevant acht):

               * welke ports u heeft geinstalleerd

               * alle omgevingsvariabelen die de standaardwaarden in
                 bsd.port.mk overschrijven, zoals PORTSDIR

               * het feit dat u /usr/ports/UPDATING heeft gelezen en
                 dat uw probleem daar niet staat vermeld (iemand gaat
                 er geheid naar vragen)

     * Voorkom vage verzoeken voor mogelijkheden. PR's van de vorm
       "iemand moet echt iets dat zus-en-zo doet implementeren"
       leveren minder waarschijnlijk resultaat op dan zeer specifieke
       verzoeken. Onthoud dat de broncode voor iedereen beschikbaar
       is, dus als u een mogelijkheid wilt is de beste manier om het
       erin te krijgen aan het werk te gaan! Neem ook het feit in
       overweging dat veel van dit soort dingen beter op
       freebsd-questions besproken kunnen worden dan als een regel in
       de PR-database, zoals hierboven besproken.

     * Verzeker u ervan dat niemand anders reeds een soortgelijk PR
       heeft ingestuurd. Alhoewel dit al hierboven genoemd is, is het
       het herhalen hier waard. Het duurt slechts een minuut of twee
       om de webgebaseerde zoekmachine op  te gebruiken. (Natuurlijk
       vergeet iedereen dit zo nu en dan.)

     * Rapporteer slechts een zaak per Probleemrapport. Voorkom het
       bijsluiten van twee of meer problemen in hetzelfde rapport
       tenzij ze gerelateerd zijn. Voorkom, wanneer patches worden
       bijgevoegd, het toevoegen van meerdere mogelijkheden of het
       repareren van meerdere bugs in hetzelfde PR tenzij ze sterk
       gerelateerd zijn--het oplossen van zulke PR's duurt vaak
       langer.

     * Voorkom controversiele verzoeken. Als uw PR een gebied
       behandelt dat in het verleden controversieel was, dient u
       waarschijnlijk bereid te zijn om niet alleen patches, maar ook
       een verklaring waarom de patches "Het Juiste Ding Om Te Doen"
       zijn aan te leveren. Zoals hierboven vermeld, is het
       zorgvuldig doorzoeken van de mailinglijsten door gebruik te
       maken van de archieven op
       http://www.FreeBSD.org/search/search.html#mailinglists altijd
       een goede voorbereiding.

     * Ben beleefd. Bijna iedereen die aan uw PR zal werken is een
       vrijwilliger. Niemand houdt ervan om te horen dat ze iets
       moeten doen wat ze al aan het doen zijn voor een andere
       motivatie dan geld. Dit is iets goeds om altijd in de gaten te
       houden bij Open Source projecten.

     --------------------------------------------------------------

  4.2. Voordat u begint

   Als u het programma send-pr(1) gebruikt, zorg er dan voor dat uw
   omgevingsvariabele VISUAL (of EDITOR als VISUAL niet is ingesteld)
   op iets zinnigs is ingesteld.

   U dient er ook zeker van te zijn dat het afleveren van mail goed
   werkt. send-pr(1) gebruikt mailberichten voor het insturen en
   volgen van probleemrapporten. Als u geen mailberichten kunt posten
   op de machine waarop u send-pr(1) draait, zal uw probleemrapport
   de GNATS-database niet bereiken. Zie voor details over het
   opzetten van mail op FreeBSD het hoofdstuk "Elektronische post"
   van het FreeBSD Handboek op
   http://www.FreeBSD.org/doc/nl_NL.ISO8859-1/books/handbook/mail.html.

   Verzeker u ervan dat uw mailprogramma het bericht onderweg naar
   GNATS niet vermangelt. In het bijzonder zal elke patch die u
   instuurt onbruikbaar worden, als uw mailer automatisch regels
   afbreekt, tabs in spaties verandert, of nieuwe-regel-tekens
   escapet. Voor de tekstgedeelten vragen wij u echter om handmatig
   regels rond de 70 tekens af te breken, zodat de webversie van het
   PR leesbaar is.

   Dezelfde soort overwegingen gelden als u het webgebaseerde
   PR-instuurformulier in plaats van send-pr(1) gebruikt. Merk op dat
   knip-en-plakbewerkingen hun eigen bijwerkingen op tekstopmaak
   kunnen hebben. In bepaalde gevallen kan het nodig zijn om
   uuencode(1) te gebruiken om er zeker van te zijn dat patches
   ongewijzigd aankomen.

   Ten slotte, als uw inzending lang is, dient u uw werk offline voor
   te bereiden zodat er niets verloren gaat indien er zich een
   probleem met het inzenden ervan voordoet. Dit kan in het bijzonder
   een probleem zijn met het webformulier.

     --------------------------------------------------------------

  4.3. Patches of bestanden bijvoegen

   Het volgende geldt voor het versturen van PR's via email:

   Het programma send-pr(1) heeft voorzieningen voor het bijvoegen
   van bestanden aan een probleemrapport. U kunt zoveel bestanden
   bijvoegen als u wilt op voorwaarde dat elk bestand een unieke
   basisnaam (i.e., de naam van het bestand zelf, zonder het pad)
   heeft. Gebruik de opdrachtregeloptie -a om de namen van de bij te
   voegen bestanden te specificeren:

 % send-pr -a /var/run/dmesg -a /tmp/fouten

   Maakt u zich geen zorgen over binaire bestanden, deze worden
   automatisch gecodeerd zodat ze de mail-agent niet verontrusten.

   Als u een patch bijvoegt, gebruik dan de optie -c of -u van
   diff(1) om een context- of verenigde diff (verenigd is
   geprefereerd) aan te maken, en zorg ervoor dat u de exacte
   revisienummers uit CVS specificeert van de bestanden die u heeft
   gewijzigd zodat de ontwikkelaars die uw rapport lezen ze
   gemakkelijk kunnen toepassen. Voor problemen met de kernel of de
   basisgereedschappen is een patch tegen FreeBSD-CURRENT (de CVS-tak
   HEAD) geprefereerd aangezien alle nieuwe code eerst daar toegepast
   en getest dient te worden. Nadat het voldoende of substantieel is
   getest, wordt de code samengevoegd of gemigreerd naar de tak
   FreeBSD-STABLE.

   Als u een patch inline in plaats van als bijlage bijvoegt, merk
   dan op dat het meest voorkomende probleem de neiging is van
   sommige email-programma's om tabs als spaties weer te geven, wat
   alles dat bedoeld was als deel van een Makefile volledig ruineert.

   Stuur geen patches als bijlagen door gebruik te maken van
   Content-Transfer-Encoding: quoted-printable. Dit zal
   karakter-escaping uitvoeren en de gehele patch waardeloos maken.

   Merk ook op dat hoewel het over het algemeen goed is om kleine
   patches in een PR op te nemen--in het bijzonder als ze het
   probleem dat in het PR beschreven is oplossen--grote patches en in
   het bijzonder nieuwe code waarvoor substantiele review nodig kan
   zijn voordat het gecommit wordt op een web- of FTP-server
   geplaatst dient te worden, en de URL in plaats van de patch bij
   het PR gevoegd dient te worden. Patches in email hebben de neiging
   om gemangeld te worden, in het bijzonder wanneer GNATS erbij
   betrokken is, en hoe groter de patch, des te moeilijker het is
   voor geinteresseerde partijen om het te ontrafelen. Ook stelt het
   posten van een patch op het web u in staat om het te wijzigen
   zonder dat het nodig is om de gehele patch opnieuw in te zenden
   als een vervolgbericht op het originele PR. Ten slotte vergroten
   grote patches simpelweg de omvang van de database, aangezien
   gesloten PR's niet worden verwijderd maar in plaats daarvan worden
   bewaard en simpelweg als closed worden gemarkeerd.

   U dient ook te weten dat tenzij u het expliciet in uw PR of in de
   patch zelf vermeld, dat van alle patches die u instuurt wordt
   aangenomen dat ze onder dezelfde licentietermen vallen als het
   originele bestand dat u heeft gewijzigd.

     --------------------------------------------------------------

  4.4. Het sjabloon invullen

   De volgende sectie heeft alleen betrekking op de email-methode:

   Wanneer u send-pr(1) draait, wordt er een sjabloon aan u
   gepresenteerd. Het sjabloon bestaat uit een lijst met velden,
   waarvan sommige al zijn ingevuld, en waarvan bij anderen staat
   uitgelegd wat de bedoeling is of wat acceptabele waarden zijn.
   Maakt u zich geen zorgen over het commentaar, deze worden
   automatisch verwijderd wanneer u ze niet wijzigt of ze zelf
   verwijdert.

   Bovenaan het sjabloon, onder de regels met SEND-PR:, staan de
   email-koppen. U hoeft deze normaalgesproken niet te wijzigen,
   tenzij u het probleemrapport vanaf een machine of account
   verstuurt die wel mail kan versturen maar niet kan ontvangen; in
   dat geval wilt u waarschijnlijk de velden From: en Reply-To: op uw
   echte emailadres instellen. U kunt uzelf (of iemand anders) een
   carbonkopie van het probleemrapport versturen door een of meer
   emailadressen aan de kop Cc: toe te voegen.

   In het email-sjabloon vindt u de volgende twee velden van een
   regel:

     * Submitter-Id: Verander dit niet. De standaardwaarde
       current-users is juist, zelfs als u FreeBSD-STABLE draait.

     * Confidential: Dit is vooraf ingevuld met no. Het heeft geen
       zin om dit te veranderen aangezien er geen vertrouwelijk
       FreeBSD probleemrapport bestaat--de PR-database wordt
       wereldwijd gedistribueerd door CVSup.

   De volgende sectie beschrijft velden die zowel in de
   email-interface als in de webinterface voorkomen:

     * Originator: Specificeer hier alstublieft uw echte naam,
       eventueel gevolgd door uw emailadres in punthaken. In de
       email-interface wordt dit normaalgesproken vooraf ingevuld met
       het gecos-veld van de huidige aangemelde gebruiker.

         Opmerking: Het emailadres dat u gebruikt wordt publieke
         informatie en kan in de handen van spammers vallen. U dient
         ofwel maatregelen te treffen om spam af te handelen, of een
         tijdelijk emailaccount te gebruiken. Merk op dat als u een
         in het geheel ongeldig emailaccount gebruikt, wij u geen
         vragen over uw PR kunnen stellen.

     * Organization: Alles waarvan u vrolijk wordt. Dit veld wordt
       niet voor iets significants gebruikt.

     * Synopsis: Vul hier een korte en accurate beschrijving van het
       probleem in. De samenvatting wordt gebruikt als het onderwerp
       van de email van het probleemrapport, en wordt gebruikt in
       lijsten en samenvattingen van probleemrapporten;
       probleemrapporten met een obscure samenvatting hebben de
       neiging om genegeerd te worden.

       Zoals hierboven vermeld, als uw probleemrapport een patch
       bevat, begin dan alstublieft de samenvatting met [patch]
       (inclusief de haken); als het een ports-PR is en u de port
       onderhoudt, overweeg dan om [maintainer update] (inclusief de
       haken) toe te voegen en de "Class" van uw PR op
       maintainer-update te zetten.

     * Severity: Een van non-critical, serious of critical. Overdrijf
       niet, bestempel uw probleem niet als critical tenzij het dat
       echt is (bijvoorbeeld gevallen van gegevenscorruptie, serieuze
       functionele regressie ten opzichte van een vorige -CURRENT) of
       als serious tenzij het iets is dat vele gebruikers aangaat
       (kernelpanics of bevriezingen; problemen met bepaalde
       apparaatstuurprogramma's of systeemgereedschappen).
       FreeBSD-ontwikkelaars zullen niet noodzakelijk sneller aan uw
       probleem werken als u de belangrijkheid ervan opblaast
       aangezien er vele anderen zijn die precies hetzelfde gedaan
       hebben -- in feite schenken sommige ontwikkelaars weinig
       aandacht aan dit veld vanwege deze redenen.

         Opmerking: Grote beveiligingsproblemen dienen niet naar
         GNATS gestuurd te worden, omdat alle GNATS-informatie
         publieke kennis is. Stuur zulke problemen alstublieft per
         prive-mail naar het Beveiligingsbeambtenteam
         <security-officer@FreeBSD.org>.

     * Priority: Een van low, medium of high. high dient te worden
       gereserveerd voor problemen die bijna iedere gebruiker van
       FreeBSD aangaan en medium voor iets dat vele gebruikers
       aangaat.

         Opmerking: Dit veld is zo vaak misbruikt dat het bijna
         volledig zinloos is geworden.

     * Category: Kies een geschikte categorie.

       Het eerste wat u moet doen is beslissen in welk gebied van het
       systeem uw probleem ligt. Onthoud dat FreeBSD een compleet
       besturingssysteem is, dat zowel een kernel, de
       standaardbibliotheken, vele hulpstuurprogramma's, en een groot
       aantal gereedschappen (het "basissysteem") installeert. Er
       zijn echter duizenden aanvullende applicaties in de
       Portscollectie. U dient eerst te beslissen of het probleem in
       het basissysteem zit of dat het in iets dat via de
       Portscollectie geinstalleerd is zit.

       Hier volgt een beschrijving van de grote categorien:

          * Als er een probleem met de kernel, de bibliotheken (zoals
            de standaard C-bibliotheek libc), of een
            hulpstuurprogramma is, gebruikt u in het algemeen de
            categorie kern. (Er zijn enkele uitzonderingen die
            hieronder vermeld staan). In het algemeen zijn dat dingen
            die in sectie 2, 3, of 4 van de handleidingpagina's staan
            beschreven.

          * Als er een probleem met een binair programma zoals sh(1)
            of mount(8) is, dient u eerst te bepalen of deze
            programma's deel zijn van het basissysteem of dat ze via
            de Portscollectie zijn toegevoegd. Als u het niet zeker
            weet, kunt u whereis programmanaam uitvoeren. De
            conventie van FreeBSD voor de Portscollectie is om alles
            onder /usr/local te installeren, alhoewel dit door een
            systeembeheerder veranderd kan worden. Voor dezen
            gebruikt u de categorie ports (zelfs als de categorie van
            de port www is; zie hieronder). Als de locatie /bin,
            /usr/bin, /sbin, of /usr/sbin is, dan is het een
            onderdeel van het basissysteem, en dient u de categorie
            bin te gebruiken. (Enkele programma's, zoals gcc(1),
            gebruiken eigenlijk de categorie gnu, maar daarover hoeft
            u zich nu geen zorgen te maken.) Dit zijn allemaal
            programma's die in sectie 1 of 8 van de
            handleidingpagina's worden beschreven.

          * Als u denkt dat de fout in de opstartscripts (rc) zit, of
            in een ander type onuitvoerbaar configuratiebestand, dan
            is de juiste categorie conf (configuratie). Deze dingen
            worden in sectie 5 van de handleidingpagina's beschreven.

          * Als u een probleem in de documentatie (artikelen, boeken,
            handleidingpagina's) heeft gevonden, dan is de juiste
            keuze docs.

          * Als u een probleem heeft met de FreeBSD webpagina's, dan
            is de juiste www.

              Opmerking: Als u problemen heeft met iets dat van een
              port genaamd www/portnaam afkomt, dan hoort dit
              desalniettemin in de categorie ports thuis.

       Er zijn nog enkele gespecialiseerde categorien:

          * Als het probleem in kern gestopt zou worden maar met het
            USB-subsysteem te maken heeft, dan is de juiste keuze
            usb.

          * Als het probleem in kern gestopt zou worden maar het met
            de threading-bibliotheken te maken heeft, dan is de
            juiste keuze threads.

          * Als het probleem in het basissysteem zit, maar het met
            onze naleving van standaarden zoals POSIX(R) te maken
            heeft, dan is de juiste keuze standards.

          * Als het probleem te maken heeft met interne fouten van de
            Java Virtual Machine(TM) (JVM(TM)), dan dient u de
            categorie java te kiezen, zelfs als was Java(TM) vanuit
            de Portscollectie geinstalleerd. Meer algemene problemen
            met Java-ports horen nog steeds onder ports thuis.

       Dit laat al het andere achter.

          * Als u ervan overtuigd bent dat het probleem zich alleen
            voordoet onder de processorarchitectuur die u gebruikt,
            kies dan een van de architectuurspecifieke categorien:
            gewoonlijk i386 voor Intel-compatibele machines in
            32-bit-modus; amd64 voor AMD-machines die in 64-bit-modus
            draaien (dit omvat ook Intel-compatibele machines die in
            EMT64-modus draaien); en minder gewoonlijk arm, ia64,
            powerpc, en sparc64.

              Opmerking: Deze categorien worden vaak misbruikt voor
              "Ik weet het niet"-problemen. Gebruik alstublieft misc,
              in plaats van te raden.

            Voorbeeld 1. Correct gebruik van een arch-specifieke
            categorie

            U heeft een gewone PC-gebaseerde machine, en denkt dat u
            een probleem bent tegengekomen dat specifiek is voor een
            bepaalde chipset of een bepaald moederbord: i386 is de
            juiste categorie.

            Voorbeeld 2. Onjuist gebruik van een arch-specifieke
            categorie

            U heeft een probleem met een insteekkaart op een
            veelvoorkomende bus, of een probleem met een bepaald type
            harde schijfstation: in dit geval is het waarschijnlijk
            op meer dan een architectuur van toepassing, en is kern
            de juiste categorie.

          * Als u echt niet weet waar het probleem zich bevindt (of
            als de uitleg niet bij een van de bovenstaanden lijkt te
            passen), gebruik dan de categorie misc. Voordat u dit
            doet, kunt u eerst hulp vragen aan de FreeBSD algemene
            vragen mailinglijst. U krijgt dan misschien het advies
            dat een bestaande categorie echt een betere keuze is.

       Hier is een actuele lijst van categorien (van
       http://www.FreeBSD.org/cgi/cvsweb.cgi/src/gnu/usr.bin/send-pr/categories):

          * advocacy: problemen gerelateerd aan het publieke imago
            van FreeBSD. Overbodig.

          * alpha: problemen specifiek aan het platform Alpha.

          * amd64: problemen specifiek aan het platform AMD64.

          * arm: problemen specifiek aan het platform ARM.

          * bin: problemen met gebruikersprogramma's in het
            basissysteem.

          * conf: problemen met configuratiebestanden,
            standaardwaarden, enzovoorts.

          * docs: problemen met handleidingpagina's of online
            documentatie.

          * gnu: problemen met geimporteerde GNU-software zoals
            gcc(1) of grep(1).

          * i386: problemen specifiek aan het i386(TM)-platform.

          * ia64: problemen specifiek aan het ia64-platform.

          * java: problemen gerelateerd aan de Java Virtual Machine.

          * kern: problemen met de kernel, (platforminspecifieke)
            apparaatstuurprogramma's, of de basisbibliotheken.

          * misc: alles wat niet in een van de andere categorien
            past. (Merk op dat er bijna niets is wat echt in deze
            categorie past, behalve problemen met de uitgave- en
            bouwinfrastructuur. Tijdelijke bouwfouten op HEAD horen
            hier niet thuis. Merk ook op dat dingen in deze categorie
            gemakkelijk kwijtraken).

          * ports: problemen gerelateerd aan de Portscollectie.

          * powerpc: problemen specifiek voor het
            PowerPC(R)-platform.

          * sparc64: problemen specifiek voor het
            SPARC64(R)-platform.

          * standards: Zaken met betrekking tot conformatie aan
            standaarden.

          * threads: problemen gerelateerd aan de implementatie van
            threads op FreeBSD (in het bijzonder op FreeBSD-CURRENT).

          * usb: problemen gerelateerd aan de implementatie van USB
            op FreeBSD.

          * www: Veranderingen of verbeteringen aan de website van
            FreeBSD.

     * Class: Kies een van de volgenden:

          * sw-bug: softwarebugs.

          * doc-bug: fouten in documentatie.

          * change-request: verzoeken voor aanvullende mogelijkheden
            of veranderingen in bestaande mogelijkheden.

          * update: updates aan ports of andere bijgedragen software.

          * maintainer-update: updates aan ports die u onderhoudt.

     * Release: De versie van FreeBSD die u draait. Dit wordt
       automatisch ingevuld als u send-pr(1) gebruikt en hoeft alleen
       veranderd te worden als u een probleemrapport verstuurt vanaf
       een ander systeem dan van hetgene waarop het probleem zich
       voordoet.

   Ten slotte zijn er een aantal meerregelige velden:

     * Environment: Dit dient zou nauwkeurig mogelijk de omgeving te
       beschrijven waarin het probleem is waargenomen. Dit omvat de
       versie van het besturingssysteem, de versie van het specifieke
       programma of bestand dat het probleem bevat, en alle andere
       relevante zaken zoals systeemconfiguratie, andere
       geinstalleerde software dat het probleem beinvloedt,
       enzovoorts-- eigenlijk alles wat een ontwikkelaar moet weten
       om de omgeving te reconstrueren waarin het probleem optreedt.

     * Description: Een complete en nauwkeurige beschrijving van het
       probleem dat u ondervindt. Probeer speculaties over de
       oorzaken van het probleem te vermijden tenzij u zeker weet dat
       u op het juiste spoor zit, aangezien een ontwikkelaar hierdoor
       onjuiste aannames over het probleem kan maken.

     * How-To-Repeat: Een samenvatting van de acties die nodig waren
       om het probleem te reproduceren.

     * Fix: Bij voorkeur een patch, of op zijn minst een tijdelijke
       oplossing (wat niet alleen andere mensen helpt om het probleem
       te omzeilen, maar mogelijk ook een ontwikkelaar de oorzaak van
       het probleem helpt te begrijpen), maar als u hier ook geen
       echte ideeen over heeft is het beter om dit veld open te laten
       dan om te speculeren.

     --------------------------------------------------------------

  4.5. Het probleemrapport versturen

   Als u send-pr(1) gebruikt:

   Als u klaar bent met het invullen van het sjabloon, het heeft
   opgeslagen, en uw tekstverwerker verlaten heeft, zal send-pr(1) u
   de prompt s)end, e)dit or a)bort? tonen. U kunt dan s aanslaan om
   het probleemrapport in te sturen, e aanslaan om de tekstverwerker
   te herstarten en verdere wijzigingen te maken, of a aanslaan om te
   stoppen. Als u het laatste kiest, blijft uw probleemrapport
   bewaard op schijf (send-pr(1) vertelt u de bestandsnaam voordat
   het eindigt), zodat u het rustig kunt bewerken, of het misschien
   over kunt plaatsen naar een systeem met een betere netverbinding,
   voordat u het met de optie -f van send-pr(1) verstuurt:

 % send-pr -f ~/mijn-probleemrapport

   Dit leest het gespecificeerde bestand, controleert de geldigheid
   van de inhoud, verwijdert commentaar en verstuurt het.

   Als u het webformulier gebruikt:

   Voordat u op submit drukt, moet u een veld invullen waarin tekst
   staat dat als afbeelding op de pagina wordt weergegeven. Deze
   ongelukkige maatregel moest worden genomen vanwege het misbruik
   door geautomatiseerde systemen en enkele kwaadwillige gebruikers.
   Het is noodzakelijk kwaad dat niemand leuk vindt; vraag ons
   alstublieft niet om het te verwijderen.

   Merk op dat u ten zeerste wordt aangeraden om uw werk ergens op te
   slaan voordat u op submit drukt. Een veelvoorkomend probleem voor
   gebruikers is dat hun webbrowser een verouderde afbeelding uit de
   cache laat zien. Als u dit overkomt, wordt uw inzending geweigerd
   en kan u uw werk verliezen.

   Als u om een bepaalde reden geen afbeeldingen kunt bekijken, en u
   ook send-pr(1) niet kunt gebruiken, accepteer dan alstublieft onze
   verontschuldigingen voor het ongemak en email uw probleemrapport
   naar het bugbuster-team op <freebsd-bugbusters@FreeBSD.org>.

     --------------------------------------------------------------

5. Vervolg

   Als uw probleemrapport eenmaal is ingestuurd, ontvangt u een
   bevestiging per email waarin het volgnummer dat aan uw
   probleemrapport was toegewezen en een URL dat u kunt gebruiken om
   de status te controleren zijn opgenomen. Met een beetje geluk zal
   iemand interesse in uw probleem tonen en proberen het op te
   lossen, of, wat het geval kan zijn, uitleggen waarom het geen
   probleem is. U wordt automatisch op de hoogte gehouden van alle
   toestandsveranderingen, en u ontvangt kopien van al het commentaar
   en patches die iemand aan het controletraject van uw
   probleemrapport kan koppelen.

   Als iemand aanvullende informatie van u vraagt, of als u zich iets
   herinnert of iets ontdekt dat u niet in het initiele rapport
   noemde, gebruik dan alstublieft een van de twee methoden om uw
   vervolg in te sturen:

     * De gemakkelijkste manier is om de vervolgkoppeling op de
       webpagina van het individuele PR te gebruiken, welke u kunt
       bereiken vanuit de PR-zoekpagina. Het klikken op deze
       koppeling brengt een email-venster naar voren met daarin de
       juiste regels voor Aan: en Onderwerp: ingevuld (als uw browser
       is ingesteld om dit te doen).

     * Als alternatief kunt u het naar <bug-followup@FreeBSD.org>
       mailen, waarbij het volgnummer in het onderwerp is opgenomen
       zodat het foutenvolgsysteem weet aan welk probleemrapport het
       vervolg gekoppeld moet worden.

         Opmerking: Als u het volgnummer niet opgeeft, raakt GNATS in
         de war en maakt het een geheel nieuw PR aan welke het
         vervolgens aan de GNATS-beheerder toekent, en vervolgens
         raakt uw PR kwijt totdat iemand de rommel opruimt, wat dagen
         of weken later kan zijn.

         Verkeerde manier:

 Onderwerp: that PR I sent

         Juiste manier:

 Onderwerp: Re: ports/12345: compilation problem with foo/bar

   Als het probleemrapport open blijft nadat het probleem is
   opgelost, stuur dan een vervolg (op de bovenstaande manier) waarin
   u vertelt dat het probleemrapport gesloten kan worden, en indien
   mogelijk, uitlegt hoe of wanneer het probleem was opgelost.

     --------------------------------------------------------------

6. Als u problemen heeft

   De meeste PR's gaan door het systeem en worden snel geaccepteerd;
   soms loopt GNATS echter achter en kan het zijn dat u uw
   email-bevestiging pas na 10 minuten of zelfs later ontvangt. Wees
   alstublieft geduldig.

   Tevens geldt, omdat GNATS alle invoer via email ontvangt, dat het
   absoluut noodzakelijk is dat FreeBSD alle inzendingen door
   spam-filters haalt. Als u binnen een uur of twee geen antwoord
   krijgt, kan uw PR misschien zijn opgeslokt; als dit zo is, neem
   dan alstublieft contact op met de GNATS-beheerders op
   <bugmeister@FreeBSD.org> en vraag om hulp.

     Opmerking: Een veelvoorkomende anti-spam-maatregel is het
     vergelijken met vele vormen van misbruik die in HTML-gebaseerde
     email voorkomen (alhoewel niet noodzakelijk het slechts opnemen
     van HTML in een PR). We raden het gebruik van HTML-gebaseerde
     email voor het versturen van PR's sterk af: niet alleen is het
     waarschijnlijker dat het niet door de filters komt, het heeft
     ook de neiging om de database te verstoppen. Oude platte email
     wordt sterk geprefereerd.

   In zeldzame gevallen zult een bug in GNATS tegenkomen waarbij een
   PR geaccepteerd is en een volgnummer toegewezen heeft gekregen
   maar waarbij het niet op de lijst van PR's van een van de
   opvraag-webpagina's staat. Het kan zijn gebeurd dat de index van
   database niet meer met de database zelf is gesynchroniseerd. De
   manier waarop u dit kunt testen is door de webpagina bekijk een
   enkel PR op te roepen en te kijken of het PR wordt vermeld. Als
   dat zo is, stel dan alstublieft de GNATS-beheerders op
   <bugmeister@FreeBSD.org> op de hoogte. Merk op dat er een
   cron-taak is die de database periodiek herbouwt, dus u hoeft geen
   actie te ondernemen tenzij u haast heeft.

     --------------------------------------------------------------

7. Verdere literatuur

   Er is een lijst met bronnen die relevant is voor het juist
   schrijven en verwerken van probleemrapporten. Het is in geen geval
   compleet.

     * Effectief softwarestoringen melden--een uitstekend essay door
       Simon G. Tatham over het samenstellen van nuttige
       (niet-FreeBSD-specifieke) probleemrapporten.

     * Problem Report Handling Guidelines--waardevolle inzichten in
       hoe probleemrapporten worden afgehandeld door de
       FreeBSD-ontwikkelaars.

     --------------------------------------------------------------
