A FreeBSD Dokumentációs Projekt: Dokumentáció beküldése
Hogyan lehet beküldeni dokumentációt?
Először is szeretnénk megköszönni, hogy erre fordítottuk az időnket!
Az elkészített dokumentációt valamilyen módon elérhetővé kell tenni. Amennyiben lehetséges, helyezzünk el egy FTP oldalon vagy webcímen.
Ezt követően írjunk levelet a freebsd-doc levelezési listára, amelyben röviden ismertetjük a dokumentációt és hivatkozunk a pontos helyére, majd várjunk a visszajelzésre.
Amennyiben valamilyen okból kifolyólag nem áll módunkban elhelyezni a dokumentációt FTP vagy webhelyen, közvetlenül is elküldhetjük a freebsd-doc levelezési lista címére is. Ebben az esetben viszont lehetőleg csak egyszerű szöveges dokumentumokat küldjünk.
Előfordulhat, hogy más levelezési listákon is megvitatnák a dokumentációt, tehát érdemes azokra is elküldeni egy másolatot belőle. Például egy olyan cikk, amely arról szól, hogy a CVSup hogyan tarthatjuk a forrásainkat frissen, további érdeklődésre tarthat számot a freebsd-current és a freebsd-stable listákon is.
Miután a dokumentációt átnézték, tegyünk eleget a vele kapcsolatban beérkezett javaslatoknak, és már készen is áll a közzétételre.
Ehhez nem kell mást tennünk, csak csomagoljuk be egy tar állományba. Ha például tehát a dokumentáció három állományból áll, mint az elso, masodik, illetve harmadik, és ezekből szeretnénk egyetlen doc.tar állományt készíteni, akkor adjuk ki az ehhez szükséges parancsot:
% tar cf doc.tar elso masodik harmadik
Ezután tömörítsük az így kapott tar állományt az alábbi paranccsal:
% gzip -9 doc.tar
Így előáll a doc.tar.gz tömörített állomány.
Végül pedig kódoljuk az állományt, nehogy véletlenül egy levelezőprogram szétcincálja.
% uuencode doc.tar.gz doc.tar.gz > doc.uue
Ezt követően tudatnunk kell a Dokumentációs Projekttel az új dokumentáció létezését. Ennek megfelelő módja a send-pr parancs használata, amely valószínűleg már el is érhető a számítógépünkön. Erre viszont a hibajelentő űrlapot is használhatjuk.
Erre azért van szükség, hogy a munka követhető legyen. Mikor jelentünk egy problémát, az egy egyedi azonosítót kap. Valamelyik committer ezt követően magához rendeli a hibajelentést és a részletek tisztázása érdekében felveszi velünk a kapcsolatot. Erre vonatkozóan olvassuk el a FreeBSD hibajelentések írása című cikket.
A send-pr program meglehetősen egyszerű. Feladata, hogy egy megfelelő formátumú e-mailt küldjön a megfelelő címre. Mikor elindítjuk a send-pr programot, az alapértelmezett szövegszerkesztő (a vi vagy az emacs) kerül betöltésre egy kitöltendő formanyomtatvánnyal és a kitöltést elősegítő kevés leírással.
Győződjünk meg róla, hogy a "Category" mezőben a "docs", a "Class" mezőben pedig a "change-request" szerepel, továbbá szükséges, hogy az előzőleg elkészített .uue állomány tartalmát is beillesszünk a hibajelentésbe.
A szövegszerkesztőből kilépve a hibajelentést a program e-mailként elküldi a megfelelő helyre. Rövid idővel ezután értesítést fog kapni a hibajelentés egyedi azonosítójáról, amivel nyomon tudjuk követni a beküldés hibajelentés állapotát.
Hova lehet küldeni a már létező dokumentációkon végzett módosításokat?
Először is ismét megköszönnénk, hogy erre fordítottuk az időt.
Ebben az esetben készíteni kell egy speciális diff állományt, amely csak az általunk javasolt változtatásokat tartalmazza. Ez leegyszerűsíti a committer dolgát, mivel így könnyebben átlátja, hogy mit szeretnénk változtatni, és nekünk sem kell hosszasan magyaráznunk, hogy milyen részleteket írtunk át (amellett természetesen, hogy megindokoljuk, miért van szükség a javasolt változtatások elvégzésére).
A 'diff' állomány készítéséhez a következőket kell tennünk:
-
Készítsünk másolatot az eredeti állományról. Mielőtt az ize.xml állományt módosítanánk, végezzük el a következő műveletet:
% cp ize.xml ize.xml.eredeti
-
Ezt követően végezzük el a kívánt módosításokat az ize.xml állományon.
% vi foo.xml ... tap tap tap ... ... teszteljük a módosításokat, nézzük át, nehogy elírás maradjon benne stb. ...
-
Készítsük el a diffet. Ehhez a következő parancsot kell kiadnunk:
% diff -u ize.xml.eredeti ize.xml > ize.diff
A program megvizsgálja a két állomány közti eltéréseket, és az ize.diff állományba írja azokat.
Ezután már küldhetjük is az ize.diff állományt a projektnek. Az előzőleg tárgyaltaknak megfelelően írjunk egy hibajelentést, de a levél törzsébe az ize.diff tartalmát illesszük.
A FreeBSD Dokumentációs Projekt kezdőlap