                    Probleemrapporten voor FreeBSD schrijven

  Dag-Erling Smo/rgrav

   Bijgedragen door  

  Mark Linimon

   Herziening: 43184

   FreeBSD is een geregistreerd handelsmerk van de FreeBSD Foundation.

   IBM, AIX, 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, en UltraSPARC zijn handelsmerken van SPARC International,
   Inc. in de Verenigde Staten en andere landen. SPARC International, Inc.
   bezit alle handelsmerken van SPARC en staat onder licentie het juiste
   gebruik van deze handelsmerken toe door zijn leden.

   Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM,
   Netra, OpenJDK, Solaris, StarOffice, SunOS 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)".

   2013-11-13 07:52:45 door hrs.
   Samenvatting

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

   Vertaald door Rene Ladan.

   [ Opgedeeld HTML bestand / Enkel HTML bestand ]

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

   Inhoudsopgave

   1. Introductie

   2. Wanneer een probleemrapport te versturen

   3. Voorbereidingen

   4. Het probleemrapport schrijven

   5. Vervolg

   6. Als u problemen heeft

   7. Verdere literatuur

   Register

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 nieuwe
   mogelijkheid.

   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:

     * 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://svnweb.freebsd.org/base/head/UPDATING?view=log 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://svnweb.freebsd.org/ports/head/UPDATING?view=log en
       http://svnweb.freebsd.org/ports/head/CHANGES?view=log zijn ook
       beschikbaar via svnweb.

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 Subversion wordt onderhouden
            (en zo ja, op welk revisienummer u zit). 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 http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query
       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 SVN 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 Subversion-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.

   Alleen in het email-sjabloon vindt u de volgende 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.

     * 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 bevroren
       computers; 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:

       Beveiligingsproblemen dienen niet naar GNATS gestuurd te worden, omdat
       alle GNATS-informatie publieke kennis is. Stuur zulke problemen
       alstublieft volgens onze richtlijnen voor beveilingsrapportages..

     * 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 betekenisloos is
       geworden.

   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.

     * 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(TM)-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://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories):

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

          * 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(TM) 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.

Register

  P

   probleemrapporten, Probleemrapporten voor FreeBSD schrijven
