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