Infrastruktura techniczna
Projekty wolnego oprogramowania wykorzystują technologie wspierające
gromadzenie i integrację informacji. Im więcej doświadczenia posiadasz w ich
użyciu, i przekonywaniu do tego innych, tym większe szanse, że twój projekt
będzie udany. Ta zasada jest tym ważniejsza, im bardziej projekt rośnie.
Dobre zarządzanie informacjami sprawia, że projekt nie zapada się pod
ciężarem prawa BrooksaZ książki Mityczny
osobomiesiąc - eseje o inżynierii oprogramowania, 1975. Patrz
i ., które
mówi, że dodanie ludzi do projektu programistycznego, który jest opóźniony,
sprawia jedynie, że będzie on jeszcze bardziej opóźniony. Fred Brooks
zauważył, że złożoność projektu zwiększa się z
kwadratem liczby uczestników. Gdy zaangażowanych jest
jedynie kilka osób, każdy może porozumieć się z każdym, ale gdy nad
projektem pracują setki osób, nikt nie jest w stanie ogarnąć tego, co robią
wszyscy inni. Jeśli dobrym zarządzaniem wolnymi projektami nazwiemy takie,
które sprawia, że wszyscy mają wrażenie wspólnej pracy w jednym pokoju,
nasuwa się pytanie, co gdy w zatłoczonym pokoju wszyscy usiłują mówić w tym
samym czasie?
To nie nowy problem. W dosłownie rozumianych zatłoczonych pokojach,
rozwiązaniem jest proces parlamentarny: formalne
wytyczne regulujące dyskusje w dużych grupach, uniemożliwiające zagubienie
istotnych uwag w zalewie głupich komentarzy, opisujące jak tworzyć komisje,
kiedy decyzje można uznać za podjęte, i tak dalej. Istotnym elementem
procesu parlamentarnego jest ustalenie, jak grupa korzysta ze swojego
systemu gromadzenia informacji. Niektóre uwagi są wpisywane "do stenogramu",
inne nie. Sam zapis może ulec zmianie, nie jest traktowany jako dosłowny
ślad tego, co się faktycznie wydarzyło, ale jako deklaracja tego, co
wydarzyło się według decyzji grupy. Taki zapis nie jest
jednorodny, dla różnych celów przyjmuje różną postać. Mogą to być notatki z
poszczególnych spotkań, zbiór notatek wszystkich spotkań, podsumowania,
agendy i komentarze do nich, raporty komitetów, raporty od nieobecnych
korespondentów, listy zadań, i tak dalej.
Tak naprawdę Internet to nie pokój, więc nie musimy matwić się o te
elementy procesu parlamentarnego, które zapewniają ciszę, gdy inni mówią.
Jednak gdy chodzi o techniki zarządzania informacjami, dobrze prowadzone
projekty otwartego oprogramowania to "procedura parlamentarna na sterydach".
Jako że praktycznie cała komunikacja w projektach wolnego oprogramowania
odbywa się na piśmie, stworzone zostały skomplikowane systemy ułatwiające
przekazywanie i etykietowanie informacji, minimalizowanie powtórzeń i
niepotrzebnych rozbieżności, przechowywanie i odzyskiwanie danych,
korygowanie złych i przestarzałych informacji, łączenie poszczególnych
informacji pomiędzy sobą. Aktywni uczestnicy sami zdają sobie sprawę z
użyteczności tych technik, i potrafią poradzić sobie z nimi ręcznie. Jednak
na dłuższą metę jedyną drogą jest użycie odpowiedniego oprogramowania. Jeśli
to tylko możliwe, samo medium wymiany informacji powinno zapewniać jej
przekazywanie, etykietowanie czy rejestrowanie, i udostępniać informacje
ludziom w najdogodniejszej dla nich postaci. W praktyce interwencja
człowieka w tym procesie wciąż będzie czasem konieczna, a więc samo
oprogramowanie powinno ułatwiać taką interwencję. Jednak w większości
wypadków jeśli człowiek odpowiednio opisze informację wprowadzając ją do
systemu, oprogramowanie powinno skorzystać z tych metadanych tak dobrze, jak
to tylko możliwe.
Porady w tym rozdziale są mocno praktyczne, oparte na doświadczeniach
z opisanym oprogramowaniem i różnymi scenariuszami użycia. Jednak głównym
celem nie jest jedynie przekazanie pewnego zestawu technik. Chodzi także o
wskazanie (na wielu małych przykładach) dobrego podejścia, który zachęci do
skutecznego zarządzania informacjami w projekcie. To podejście składa się
zarówno z umiejętności technicznych, jak i tych miękkich. Umiejętności
techniczne są konieczne, ponieważ oprogramowanie do zarządzania informacjami
zawsze wymaga konfiguracji, a także pewnego wysiłku w utrzymaniu i
dostosowywaniu do nowych potrzeb (na przykład patrz dyskusja o tym, jak
radzić sobie z wzrostem projektu w dalej w tym rozdziale). Umiejętności miękkie są
niezbędne, ponieważ ludzka społeczność także wymaga opieki. Nie zawsze
oczywiste jest, jak w pełni wykorzystać stosowane narzędzia, a czasem
projekty stosują sprzeczne konwencje (na przykład patrz dyskusja o nagłówku
Reply-to w wiadomościach na listach dyskusyjnych, w
). Każdy uczestnik projektu powinien być
zachęcany, w odpowiednim czasie i w odpowiedni sposób, do dbania o porządek
w informacjach projektu. Im większe zaangażowanie uczestnika w projekt, tym
bardziej złożonych i wyspecjalizowanych technik będzie musiał się
nauczyć.
Zarządzanie informacjami to problem, na który nie ma podręcznikowej
odpowiedzi. Występuje tu zbyt wiele zmiennych. Może się zdarzyć, że wszystko
jest skonfigurowane tak, jak sobie tego życzysz, a większość społeczności
współpracuje, ale rozwój projektu sprawi, że niektóre praktyki przestaną się
skalować. W projekcie, którego wzrost osiągnął stabilny poziom, a
programiści i użytkownicy przywykli do stosowanej infrastruktury, nowi
uczestnicy mogą dziwić się, dlaczego nie stosuje się jakiegoś nowopowstałego
systemu zarządzania informacjami. To obecnie dość powszechne zjawisko w
projektach, które powstały przed wynalezieniem wiki (patrz ). Odpowiedź na wiele pytań to
sprawa względna, zależna od kompromisu pomiędzy wygodą tych, którzy
wprowadzają informację, a tych, do których jest ona kierowana, lub pomiędzy
czasem koniecznym na skonfigurowanie systemu zarządzania informacjami, a
jego pożytkiem dla projektu.
Wystrzegaj się pokusy nadmiernej automatyzacji, czyli automatyzacji
procesów, które w rzeczywistości wymagają ludzkiej uwagi. Infrastruktura
techniczna jest istotna, ale tym co sprawia, że projekty wolnego
oprogramowania żyją, jest troska ludzi w nie zaangażowanych. Infrastruktura
techniczna powinna przede wszystkim być w tym pomocą dla człowieka.
Czego projekt potrzebuje
Większośc projektów otwartego oprogramowania posiada przynajmniej
następujący minimalny, standardowy zestaw narzędzi zarządzania
informacjami:
Strona WWW
To przede wszystki scentralizowany, jednokierunkowy kanał
przekazu informacji z projektu do opinii publicznej. Strona WWW może
też stanowić panel administracyjny dla pozostałych narzędzi
projektu.
Listy dyskusyjne
Na ogół to najbardziej aktywne forum komunikacyjne projektu,
pełniące rolę "stenogramu".
Kontrola wersji
Pozwala programistom na wygodne zarządzanie zmianami w kodzie,
włączając odwracanie zmian i ich "portowanie". Pozwala wszystkim
śledzić, co dzieje się w kodzie.
Śledzenie błędów
Pozwala programistom śledzić nad czym akutualnie pracują,
koordynować się wzajemnie i planować wydania. Udostępnia wszystkim
informacje o stanie zgłoszeń i dodatkowych informacjach (np. jak
odtworzyć błąd) o nich. Może zostać wykorzystany do śledzenia nie
tylko błędów, ale i informacji o zadaniach, wydaniach, nowych
pomysłach, itd.
Czat na żywo
Miejsce na szybkie, mniej istotne dyskusje oraz wymianę pytań i
odpowiedzi. Nie zawsze w pełni archiwizowane.
Każde narzędzie w tym zestawie zaspokaja inne potrzeby, ale ich
działanie jest ze sobą powiązane, powinny więc dobrze za sobą współpracować.
Poniżej opiszemy, jak tego dokonać i, co ważniejsze, jak zachęcić ludzi do
korzystania z nich. Strona WWW zostanie omówiona na końcu, gdyż stanowi
raczej klej dla wszystkich pozostałych elementów, niż narzędzie samo w
sobie.
Można uniknąć wielu problemów z wyborem i konfiguracją tych narzędzi,
korzystając z serwisów oferujących pakiet hostingowy:
serwer z preinstalowanymi wszystkim narzędziami, przydatnymi w projekcie
wolnego oprogramowania. Patrz
dalej
w tym rozdziale aby poczytać o zaletach i wadach pakietów
hostingowych.
Listy dyskusyjne
Listy dyskusyjne to chleb powszedni jeśli chodzi o komunikację w
projekcie. Jeśli użytkownik ma dostęp do jakiegoś innego medium niż tylko
strona WWW, na ogół jest to jedna z list dyskusyjnych projektu. Jednak zanim
będą oni mieli kontakt z samą listą, muszą poznać interfejs dla list
dyskusyjnych—czyli mechanizm, za pomocą którego dołączają do listy
(subskrybują ją). To prowadzi nas do zasady numer 1 prowadzenia list
dyskusyjnych:
Nie próbuj prowadzić list dyskusyjnych
ręcznie—skorzystaj z oprogramowania do zarządzania
listami.
Istnieje pokusa, żeby odłożyć to na później. Instalacja oprogramowania
do zarządzania listami dyskusyjnymi może wydawać się przesadą na samym
początku. Zarządzanie niewielkimi i mało ruchliwymi listami ręcznie może
wydawać się kusząco proste: wystarczy skonfigurować alias, który
przekierowuje do ciebie, a następnie gdy ktoś na niego napisze, dodajesz
jego email do (lub usuwasz z) pliku tekstowego gromadzącego adrsy ludzi
zapisanych na listę. Czy może być coś prostszego?
Problem w tym, że porządne zarządzanie listą dyskusyjną—do
którego ludzie już przywykli—wcale nie jest proste. To nie tylko
zapisywanie i wypisywanie uczestników na ich życzenie. To także moderacja
pozwalająca uniknąć spamu, serwowanie listy w formie dziennego streszczenia
zamiast osobnych wiadomości, automatyczne przesyłanie standardowych
informacji o liście i projekcie, i wiele innych. Człowiek ręcznie obsługując
maile może zapewnić jedynie podstawową funkcjonalność, i to nie tak
niezawodnie i szybko jak oprogramowanie.
Nowoczesne oprogramowanie do zarządzania listami dyskusyjnymi na ogół
oferuje przynajmniej następujące możliwości:
Subskrypcja przez email i interfejs WWW
Gdy użytkownik zapisze się na listę, powinien
natychmiast otrzymać powitalną wiadomość zwrotną
informującą o tym, na jakś grupę został zapisany, jak korzystać z
oprogramowania obsługującego listę i (co najważniejsze) jak się z niej
wypisać. Ta automatyczna odpowiedź oczywiście może być dostosowana do
potrzeb danego projektu, zawierając informacje takie jak adres strony
WWW, lokalizacja odpowiedzi na najczęstsze pytania (FAQ) itd.
Subskrypcja streszczenia lub pojedynczych
wiadomości
W trybie streszczenia użytkownik otrzymuje jeden email dziennie,
zawierający cały ruch na liście danego dnia. Jest to wygodne dla
ludzi, którzy pobieżnie śledzą listę, nie uczestnicząc w niej,
ponieważ pozwala im przeglądać wszystkie tematy w tym samym czasie i
uniknąć odciągania uwagi przez pojedyncze maile.
Możliwości moderacji
"Moderacja" oznacza weryfikację wiadomości aby upewnić się, że
a) nie są spamem, i b) są na temat,
zanim pojawią się na liście. Moderacja wymaga uczestnictwa człowieka,
choć oprogramowanie może bardzo ułatwić ten proces. Więcej o moderacji
powiemy później.
Interfejs administratora
Między innymi pozwala on administratorowi na łatwe usuwanie
nieaktualnych adresów email. To może być konieczne gdy serwer odbiorcy
zacznie odpowiadać automatycznymi wiadomościami "Nie ma mnie pod tym
adresem" w odpowiedzi na każdą wiadomości z listy. (Niektóre systemy
list dyskusyjnych potrafią nawet samodzielnie wykryć takie zachowanie,
i wypisać daną osobę z listy).
Modyfikacja nagłówków
Wiele osób korzysta ze skomplikowanych filtrów w swoich
czytnikach poczty. Oprogramowanie zarządzające listą dyskusyjną
potrafi modyfikować pewne standardowe nagłówki wiadomości tak, aby
łatwiej było z nich skorzystać (więcej o tym dalej).
Archiwizacja
Wszystkie wiadomości na liście są przechowywane i publikowane w
Internecie. Ewentualnie niektóre programy zarządzające listami
umożliwiają współpracę z zewnętrznymi narzędziami archiwizującymi, jak
MHonArc (). Jak mówi w archiwizacja jest
konieczna.
Chodzi przede wszystkim o to, aby pokazać, że zarządzanie listami
dyskusyjnymi to skomplikowany problem, nad którym wiele myślano, i który
został praktycznie rozwiązany. Zdecydowanie nie musisz być w tym ekspertem.
Powinieneś jednak być świadom, że zawsze pozostaje pole do nauki, a
zarządzanie listami od czasu do czasu zajmie twoją uwagę podczas prowadzenia
projektu wolnego oprogramowania. Dalej omówimy kilka najpowszechniejszych
problemów podczas konfiguracji listy dyskusyjnej.
Unikanie spamu
Do czasu, gdy te słowa zostaną opublikowane, problem spamu w
Internecie zapewne urośnie dwukrotnie—lub przynajmniej można będzie
odnieść takie wrażenie. Jeszcze nie tak dawno temu można było prowadzić
listę dyskusyjną bez żadnych filtrów antyspamowych. Od czasu do czasu
zagubiona wiadomość pojawiła się na liście, ale działo się to na tyle
rzadko, że nie sprawiało większego kłopotu. Te czasy już minęły. Dziś lista
dyskusyjna, która nie stosuje zabezpieczeń antyspamowych, zostanie szybko
zalana śmieciowymi mailami tak, że stanie się nieużywalna. Ochrona
antyspamowa jest koniecznością.
Ochronę antyspamową można podzielić na dwa rodzaje: zapobieganie
pojawianiu się spamu na liście i uniemożliwianie spamerom uzyskiwania nowych
adresów email z listy. Pierwsza z nich jest bardziej istotna, więc zajmiemy
się nią najpierw.
Filtrowanie wiadomości
Istnieją trzy podstawowe techniki unikania spamu, większość
oprogramowania do zarządzania listą oferuje wszystkie z nich. Najlepiej
działają razem:
Umożliwianie wysyłania wiadomości
jedynie subskrybentom.
To bardzo efektywna metoda, w dodatku niezbyt prachłonna,
gdyż głównie sprowadza się do zmiany jednej opcji
konfiguracyjnej. Pamiętaj jednak, że wiadomości które nie
zostały zaakceptowane, nie powinny być po prostu odrzucane.
Zamiast tego powinny zostać przekazane do moderacji, z dwóch
powodów. Po pierwsze, użytkownicy nie zapisani na listę powinni
mieć prawo głosu. Osoba mająca pytanie lub sugestię nie powinna
być zmuszana do zapisania się na listę tylko po to, żeby posłać
pojedynczą wiadomość. Po drugie, nawet zapisani użytkownicy mogą
czasem korzystać z innego adresu niż ten, pod którym są zapisani
na listę. Adres email nie jest dobrym sposobem identyfikacji
człowieka, i nie powinien być za taki uznawany.
Filtrowanie wiadomości za pomocą
oprogramowania antyspamowego.
Jeśli oprogramowanie zarządzające listą daje taką
możliwość (większość daje), można filtrować wiadomości za pomocą
filtrów antyspamowych. Automatyczne kategoryzownie nie jest
doskonałe, i nigdy nie będzie, gdyż trwa nieustający wyścig
zbrojeń pomiędzy spamerami i twórcami filtrów. Jednak może ono
znacznie zredukować ilość spamu docierającą do kolejki
moderacyjnej. Im większa długość kolejki, tym więcej ludzkiego
czasu trzeba poświęcić na jej przejrzenie, więc każde
automatyczne filtrowanie jest bardzo przydatne.
To nie miejsce na szczegółowe omówienie konfiguracji
filtrów antyspamowych. W tym celu warto spojrzeć do dokumetacji
wybranego systemu zarządzania listami dyskusyjnymi (patrz dalej
w tym rozdziale). Oprogramowanie na ogół dostarczane
jest z jakimiś wbudowanymi możliwościami antyspamowymi, ale
czasem warto dodatkowo zainstalować zewnętrzne filtry. Mam dobre
doświadczenie z następującymi: SpamAssassin () i SpamProbe (). Nie chcę się
wypowiadać na temat innych dostępnych filtrów antyspamowych, z
których z pewnością wiele jest bardzo dobrych. Po prostu sam
korzystałem akurat z tych dwóch, i jestem z nich
zadowolony.
Moderacja.
Dla maili, które nie zostały dopuszone automatycznie, jako
pochodzące od subskrybentów, i przeszły przez filtry
antyspamowe, ostatnim krokiem jest
moderacja: email zostaje przekierowany na
specjalny adres, pod którym człowiek jest w stanie przejrzeć
jego treść i zaakceptować lub odrzucić wiadomość.
Akceptacja wiadomości może odbywać się na dwa sposoby:
można zaakceptować daną wiadomość jednorazowo, lub zezwolić na
publikowanie wszystkich dalszych wiadomości od danego nadawcy.
Na ogół stosowana jest ta druga metoda, poniważ pozwala
zmniejszyć obciążenie moderatora. Szczegóły tego, jak
zatwierdzać wiadomości, różnią się pomiędzy systemami, ale na
ogół sprowadza się to do odpowiedzi na pewien adres z komendą
"accept" (aby zaakceptować tę jedną wiadomość) lub "allow" (aby
zaakceptować daną wiadomość i wszystkie następne od tego
nadawcy).
Odrzucenie wiadomości na ogół sprowadza się do
zignorowania maila moderacyjnego. Jeśli oprogramowanie
zarządzające listą nie otrzyma potwierdzenia, nie opublikuje
wiadomości na liście, a więc aby odrzucić wiadomość wystarczy
usunąć mail z prośbą o moderację. Czasem można odpowiedzieć
komendą "reject" lub "deny", aby automatycznie odrzucać
wszystkie przyszłe maile od danego nadawcy, nie dopuszczając ich
nawet do moderacji. Jednak rzadko kiedy ma to sens, gdyż
moderacja przede wszystkim dotyczy spamu, a spamerzy rzadko
kiedy korzystają z tego samego adresu więcej niż raz.
Upewnij się, że korzystasz z moderacji jedynie do
filtrowania spamu i wiadomości ewidentnie nie na temat, chociażby
przesłanych przypadkowo na złą listę dyskusyjną. System moderacji na ogół
daje możliwość nawiązania bezpośredniego kontaktu z nadawcą, ale nie
korzystaj z niej aby odpowiadać na kwestie, które powinny zostać poruszone
na liście, nawet jeśli doskonale znasz odpowiedź. Jeśli będziesz to robić,
społeczność skupiona wokół projektu nie będzie miała jasnego obrazu tego,
jakiego rodzaju pytania są zadawane przez użytkowników, a inni nie będą
mieli szansy odpowiedzieć na nie, ani zobaczyć odpowiedzi innych. W
moderacji listy dyskusyjnej chodzi tylko i wyłącznie o ochronę przed spamem
i wiadomościami nie na temat.
Ukrywanie adresów w archiwach
Aby twoja lista dyskusyjna nie stała się źródłem adresów dla spamerów,
powszechną metodą jest zaciemnianie adresów email w archiwach listy, na
przykład zamieniając
jlosowy@jakasdomena.com
na
jlosowy_AT_jakasdomena.com
lub
jlosowyNOSPAM@jakasdomena.com
lub w jakiś inny zrozumiały (dla człowieka) sposób. Roboty zbierające
adresy dla spamerów często po prostu przeszukują strony WWW—włączając
w to archiwum twojej listy—w poszukiwaniu ciągów zawierających znak
"@". Zaciemnienie adresów to sposób na ukrycie adresów przed spamerami.
Oczywiście nie zapobiega to w żaden sposób przed wysyłaniem spamu na samą
listę, ale pomaga ograniczyć ilość spamu trafiającego na prywatne adresy
uczestników listy.
Ukrywanie adresów bywa kontrowersyjne. Niektórzy bardzo lubią tę
technikę i bywają zaskoczeni, jeśli nie jest ona stosowana w archiwum. Inni
uważają to za niepotrzebne utrudnienie (gdyż ludzie muszą odkodować adres,
zanim mogą z niego skorzystać). Niektórzy zakładają, że nie daje ona
spodziewanych efektów, ponieważ robot zbierający adresy może w teorii
odkodować każdy adres zaciemniony prostym algorytmem. Warto jednak zauważyć,
że istnieją empiryczne dowody tego, że ukrywanie adresów
jest efektywne, patrz .
Najlepiej gdyby oprogramowanie zarządzające listą dawało wybór każdemu
użytkownikowi, albo poprzez specjalny nagłówek, albo konfigurowalną opcję
związaną z kontem użytkownika. Nie znam jednak żadnego oprogramowania, które
oferowało by taką możliwość, więc na chwilę obecną administrator listy musi
podjąć tę decyzję za wszystkich (zakładając, że lista jest w ogóle
archiwizowana, co nie jest zasadą). Skłaniam się nieśmiało w stronę
ukrywania adresów. Niektórzy są bardzo ostrożni jeśli chodzi o ujawnianie
ich adresu email na stronach WWW lub gdziekolwiek, gdzie przechwycić je mogą
automaty zbierające adresy, i byliby bardzo zawiedzeni, gdyby cały ten
wysiłek poszedł na marne z momencie publikacji ich adresu w archiwum. Z
kolei niedogodności dla pozostałych użytkowników nie są wielkie, ponieważ
przekształcenie zaciemnionego adresu na postać oryginalną jest trywialne.
Pamiętaj jednak, że wciąż trwa wyścig zbrojeń. W momencie gdy czytasz te
słowa automaty zbierające adresy mogły już mauczyć się większości
popularnych wzorców zaciemniania, i będzie trzeba zastanowić się nad innym
rozwiązaniem.
Wielka debata o nagłówek Reply-to
Wcześniej, w , podkreślałem
wagę tego, aby dyskusje pozostawały na forum publicznym, i omówiłem sposoby
na to, aby unikać przenoszenia dyskusji do prywatnych wątków. Ten rozdział
poświęcony jest konfiguracji oprogramowania mającego zaoszczędzić nam pracy.
Tak więc jeśli oprogramowanie zarządzające listą dyskusyjną ma opcję
ułatwiającą utrzymanie rozmowy na liście, mogłoby się wydawać, że
wlączenie jest będzie oczywystą deyzją.
Jednak nie do końca. Istnieje taka opcja, ma ona jednak dość istotne
wady. Pytanie czy z niej korzystać, czy nie, to jedna z najgorętszych debat
w temacie zarządzania listami dyskusyjnymi—może nie ma tyle, aby można
było o tym usłyszeć w wieczornych wiadomościach, ale jest to problem, który
pojawia się od czasu do czasu w projektach wolnego oprogramowania. Dalej
opiszę, w czym rzecz, podam argumenty obu stron i postaram się
pomóc w podjęciu decyzji.
Opcja, o której mowa, jest bardzo prosta: oprogramowanie listy
dyskusyjnej może, jeśli chcesz, automatycznie ustawiać nagłówek Reply-to
każdej wiadomości tak, aby wskazywał na listę dyskusyjną. Innymi słowy, nie
ważne jaką wartość autor wstawi w nagłówek Reply-to (może nawet nie podawać
żadnej), w momencie gdy wiadomość dotrze do subskrybentów, wspomniany
nagłówek będzie zawierał adres listy:
Reply-to: discuss@lists.example.org
Z pozoru wygląda to na dobre rozwiązanie. W zasadzie każdy program
pocztowy rozpoznaje nagłówek Reply-to, więc każdy, kto odpisze na wiadomość
z listy, automatycznie zaadresuje ją do całej listy, a nie tylko nadawcy
danej wiadomości. Oczywiście wciąż można ręcznie zmienić adresata, jednak
najważniejsze, że domyślnie odpowiedzi są kierowane na
listę. To doskonały przykład zastosowania technologii aby zachęcić do
współpracy.
Niestety istnieje kilka wad tego rozwiązania. Pierwsza z nich nazywana
bywa problemem "nie mogę znaleźć drogi do domu":
czasem nadawca podaje swój "prawdziwy" adres email w polu Reply-to, gdyż z
jakiegoś powodu wysyła wiadomości z innego adresu email niż ten, na który
chciałby otrzymać odpowiedź. Osoby, które zawsze wysyłają i odbierają pocztę
z tego samego adresu nie mają tego problemu, i bywają zaskoczeni, gdy o tym
słyszą. Jednak dla tych, którzy posiadają niestandardową konfigurację
poczty, lub nie mają wpływu na to, jaką wartość ma nagłówek From wysyłanych
przez nich wiadomości (na przykład dlatego, że wysyłają pocztę z pracy, i
nie mają dobrych układów z administratorami), korzystanie z pola Reply-to
może być jedynym sposobem na podanie poprawnego adresu zwrotnego. Gdy taka
osoba wysyła wiadomość na listę, na którą nie jest zapisana, wartość pola
Reply-to staje się ważną informacją. Jeśli oprogramowanie listy nadpisze to
pole, odpowiedzi mogą do niej w ogóle nie dotrzeć.
Drugi problem dotyczy oczekiwań, i moim zdaniem to najpoważniejszy
argument przeciwko modyfikowaniu pola Reply-to. Większość doświadczonych
użytkowników poczty elektronicznej jest przyzwyczajona do dwóch podstawowych
rodzajów odpowiedzi: "odpowiedz wszystkim" i
"odpowiedz autorowi". Współczesne oprogramowanie
pocztowe posiada osobne polecenia dla każdej z tych akcji. Użytkownicy
spodziewają się, że aby odpowiedzieć wszystkim (a więc także na listę),
powinni wybrać opcję "odpowiedz wszystkim", a żeby odpowiedzieć prywatnie
autorowi, powinni wybrać "odpowiedz autorowi". Wprawdzie chcemy zachęcać
ludzi do odpowiadania na listę, zdarzają się jednak sytuacje, w których
prywatna odpowiedź jest konieczna—na przykład, gdy chcemy wysłać
autorowi wiadomości jakieś niepubliczne informacje, które nie powinny
pojawić się na liście.
Zastanówmy się teraz, co się stanie, gdy lista nadpisze pole Reply-to.
Użytkownik wybiera polecenie "odpowiedz autorowi", chcąc odpowiedzieć
prywatnie autorowi wiadomości. Spodziewa się takiego efektu, więc być może
nie spojrzy uważnie na pole odbiorcy nowej wiadomości. Następnie wprowadzi
prywatną i poufną treść, na przykład jakąś obraźliwą opinię na temat jednej
z osób na liście, i wyśle wiadomość. Niespodziewanie chwilę później jego
wiadomość pojawia się na liście dyskusyjnej!
Faktycznie, w teorii powinien spojrzeć na pole odbiorcy i nie zakładać nic
na temat zawartości pola Reply-to. Jednak pole Reply-to prawie zawsze
ustawiane jest (najczęściej automatycznie przez sam program pocztowy) na
adres prywatny nadawcy, i wielu użytkowników poczty jest do tego
przyzwyczajonych. Gdy ktoś celowo ustawia pole Reply-to na jakiś inny adres,
jak lista dyskusyjna, na ogół wspomina o tym w treści wiadomości, aby nikt
nie był tym zaskoczony.
Ze względu na możliwość takich nieprzewidzianych komplikacji, na ogół
konfiguruję oprogramowanie zarządzające listą tak, aby nie ruszało nagłówka
Reply-to. To przykład sytuacji, w której użycie technologii w celu
ułatwienia komunikacji ma, a przynajmniej tak mi się zdaje, potencjanie
niebezpieczne efekty uboczne. Jednak druga strona debaty na także silne
argumenty. Którekolwiek rozwiązanie wybierzesz, na pewno od czasu do czasu
ludzie będą wysyłali wiadomości na listę z pytaniem, dlaczego nie podjęłeś
innej decyzji. To nie jest temat, który powinien być głównym wątkiem na
liście, więc warto przygotować sobie gotową odpowiedź, najlepiej taką, która
zakończy dyskusję, zamiast ją zaognić. Przede wszystkim
nie upieraj się, że twoja decyzja, jakakolwiek by nie
była, jest jedyną logiczną i właściwą (nawet jeśli sądzisz, że tak
rzeczywiście jest). Zamiast tego zwróć uwagę, że to stara dyskusja, każda ze
stron ma dobre argumenty, a ty dokonałeś najlepszej możliwej decyzji.
Uprzejmie poproś o to, żeby nie wracać więcej do tego tematu, chyba że ktoś
rzeczywiście ma coś nowego do powiedzenia, a następnie nie angażuj się
więcej w wątek i poczekaj, aż umrze śmiercią naturalną.
Ktoś może zaproponować głosowanie, aby wybrać jedną z alternatyw.
Jeśli chcesz, możesz się na to zgodzić, choć ja osobiście nie uważam, żeby w
tym przypadku liczenie głosów było dobrym rozwiązaniem. Konsekwencje dla
kogoś, kto nie zdaje sobie sprawy z działania listy są poważne (przypadkowe
wysłanie prywatnej wiadomości na publiczną listę), a kłopot dla pozostałych
niewielki (konieczność przypomnienia komuś od czasu do czasu, żeby odpisał
na listę a nie na prywatny adres), że nie jestem przekonany, czy większość
powinna mieć możliwość wystawienia mniejszości na takie ryzyko.
Nie przedstawiłem tutaj wszystkich aspektów problemu, a jedynie te,
które wydawały się najważniejsze. Aby dowiedzieć się więcej, warto
przeczytać następujące dwa klasyczne artykuły, cytowane na ogół w trakcie
takich dyskusji:
Leave Reply-to alone,
Chip Rosenthal
Set Reply-to to list,
Simon Hill
Mimo sugestii, które podałem powyżej, nie uważam, że istnieje jedyne
właściwe rozwiązanie tego problemu, i sam uczestniczę w wielu listach, które
nadpisują pole Reply-to. Najważniejsze, żeby jak
najszybciej zdecydować się na którąś z alternatyw, a następnie starać się
nie wplątywać w dyskusje na ten temat.
Dwie fantazje
Pewnego dnia ktoś wpadnie na genialny pomysł, i zaimplementuje w
programie pocztowym polecenie "odpowiedz na listę".
Mogłaby ona opierać się na nagłówkach dołączanych przez listę, opisywanych
wcześniej, aby skierować odpowiedź bezpośrednio na listę, z wyłączeniem
wszystkich pozostałych adresatów (gdyż najprawdopodobniej i tak są zapisani
na listę). Być może inne programy pocztowe podchwycą ten pomysł, i cała
dyskusja związana z polem Reply-to będzie niepotrzebna. (W zasadzie program
pocztowy Mutt posiada taką
opcję.Wkrótce po publikacji tej książki Michael Bernstein napisał do mnie: "Także inne programy
pocztowe oprócz Mutta posiadają opcję odpowiedzi na listę. Na przykład
Evolution posiada odpowiedni skrót klawiszowy (Ctrl-L), choć nie ma takiego
przycisku.")
Nawet lepszym rozwiązaniem byłoby wprowadzenie opcji konfiguracyjnej
dla każdego użytkownika. Wtedy ci, którzy chcą, aby lista dyskusyjna
modyfikowała pole Reply-to wiadomości docierających do nich (zarówno ich
własnych, jak i pochodzących od innych użytkowników), mogą wybrać taką
opcję, a pozostali mogą z niej nie korzystać. Jednak nie znam żadnego
oprogramowania do obsługi listy, które oferowałoby taką opcję dla
poszczególnych użytkowników. Na razie musimy więc pozostać przy ustawieniu
globalnym.
Archiwizacja
Techniczne szczegóły archiwizacji listy dyskusyjnej są mocno zależne
od oprogramowania, zarządzającego listą, tym samym wykraczają poza zakres
tej książki. Wybierając lub konfigurując rozwiązanie archiwizacyjne, weź pod
uwagę następujące czynniki:
Szybkość aktualizacji
Użytkownicy często będą chcieli odwołać się do zarchiwizowanej
wersji wiadomości wysłanej w ciągu ostatniej godziny czy dwóch. Jeśli
to tylko możliwe, wiadomości powinny pojawiać się w archiwum
natychmiast—tak, aby w chwili gdy wiadomość pojawi się na
liście, była także dostępna w archiwum. Jeśli to niemożliwe,
powinieneś skonfigurować archiwum tak, aby było uaktualniane
najrzadziej co godzinę. Domyślnie niektóre archiwizatory wykonują
proces aktualizacji co noc, ale w praktyce to zdecydowanie za rzadko
dla potrzeb aktywnej listy dyskusyjnej.
Stabilność odnośników
Gdy wiadomość została zarchiwizowana pod danym adresem URL,
powina być pod nim dostępna na zawsze, czy raczej na tyle długo, na
ile to możliwe. Nawet gdy archiwa zostaną przebudowane, odtworzone z
kopii zapasowej czy w inny sposób zmodyfikowane, wszystkie adresy URL,
które zostały opublikowane powinny pozostać bez zmian. Stabilne
odnośniki umożliwiają wyszukiwarkom internetowym indeksowanie
archiwów, co bardzo pomaga osobom szukającym odpowiedzi. Stabilne
odnośniki są ważne także dlatego, że linki do wiadomości w archiwum są
często umieszczane w systemie śledzenia błędów (patrz ) dalej w tym
rozdziale czy innych dokumentach projektu.
Najlepiej gdyby oprogramowanie zarządzające listą dołączało w
nagłówkach rozsyłanych wiadomości jej adres URL w archiwum (albo
chociaż unikalną dla niej część tego adresu). Dzięki temu osoby, które
posiadają kopię wiadomości mogłyby łatwo sprawdzić jej adres w
archiwum bez konieczności odwiedzania samego archiwum. To byłoby
pomocne, gdyż czynności wymagające użycia przeglądarki mogą zająć
sporo czasu. Nie wiem czy jakiekolwiek oprogramowanie zarządzające
listą oferuje taką możliwość—niestety te, z których korzystałem
nie posiadają jej. Jednak to coś, o czym warto pomyśleć (lub, jeśli
piszesz oprogramowanie do obsługi list dyskusyjnych, co warto
zaimplementować).
Kopie zapasowe
Tworzenie kopii zapasowych archiwów nie powinno być zbyt
trudne, a proces odtwarzania z kopii zbyt skomplikowany. Nie
powinieneś traktować oprogramowania archiwum na zasadzie czarnej
skrzynki. Sam powinieneś wiedzieć (lub powinien to wiedzieć inny
uczestnik projektu) gdzie przechowywane są wiadomości, i w jaki
sposób wygenerować ponownie strony archiwum na podstawie bazy
wiadomości, jeśli zajdzie taka konieczność. Archiwum to cenne
dane—projekt, który je straci, traci zarazem część swojej
zbiorowej pamięci.
Wsparcie dla wątków
Powinna istnieć możliwość przejścia od każdej wiadomości do
wątku (grupy powiązanych wiadomości), do
którego należy. Każdy wątek powinien także posiadać swój adres
URL, niezależny od adresów poszczególnych wiadomości w
wątku.
Wyszukiwanie
Archiwum, które nie pozwala na wyszukiwanie (zarówno po treści
wiadomośc, jak i ich autorach i tematach) jest prawie
bezużyteczne. Niektóre programy archiwizujące umożliwiają
wyszukiwanie tylko poprzez zewnętrzną wyszukiwarkę, jak na
przykład Google. To
zawsze coś, jednak wbudowana wyszukiwarka na ogół jest lepiej
dostosowana do potrzeb archiwum, na przykład pozwala na
wyszukiwanie słów w kluczowych tylko w temacie, albo tylko w
treści.
To jedynie lista technicznych kwestii ważnych w trakcie wyboru i
konfiguracji archiwum. Do tego. jak skłonić ludzi do
korzystania z archiwum, aby poprawić komunikację w
projekcie, wrócimy w dalszych rozdziałach, w szczególności w .
Oprogramowanie
Poniżej znajduje się lista wolnego oprogramowania do zarządzania listą
i archiwizacji. Jeśli serwer, na którym ulokowany jest twój projekt, ma
już działające oprogramowanie do obsługi list dyskusyjnych, być może
nawet nie będziesz musiał podejmować decyzji. Jeśli jednak musisz
zainstalować je sam, masz sporo możliwości. Ja sam korzystałem z
Mailman, Ezmlm, MHonArc i Hypermail, ale nie znaczy to, że inne nie są
dobre (oczywiście są jeszcze inne narzędzia, na które nie trafiłem, więc
nie uznawaj tej listy za kompletną).
Oprogramowanie do zarządzania listami dyskusyjnymi:
Mailman —
(Posiada wbudowany archiwizator, i możliwość podpięcia zewnętrznych
archiwizatorów.)
SmartList —
(Przeznaczony do użycia z systemem przetwarzania poczty Procmail.)
Ecartis —
ListProc —
Ezmlm —
(Zaprojektowany do współpracy z serwerem pocztowym Qmail).
Dada —
(Mimo prób ukrycia tego faktu przez autorów strony, to wolne
oprogramowanie, wydane na licencji GNU General Public License. Posiada
też wbudowany archiwizator.)
Oprogramowanie do archiwizacji list:
MHonArc —
Hypermail —
Lurker —
Procmail —
(Oprogramowanie towarzyszące SmartList, system przetwarzania poczty
ogólnego przeznaczenia, który można skonfigurować jako
archiwizator.)
Kontrola wersji
System kontroli wersji (ang.
version control system lub revision
control system) to zestaw narzędzi do śledzenia i
kontrolowania zmian w plikach projektu, w szczególności w kodzie
źródłowym, dokumentacji i stronach WWW. Jeśli nigdy nie korzystałeś z
kontroli wersji, powinieneś jak najprędzej znaleźć kogoś, kto korzystał,
i przekonać go, aby dołączył do projektu. W dzisiejszych czasach każdy
spodziewa się, że przynajmniej kod źródłowy projektu znajduje się pod
kontrolą wersji, i nie traktuje poważnie projektów, które nie korzystają
z niej przynajmniej minimalnie umiejętnie.
Kontrola wersji jest tak uniwersalna, ponieważ pomaga praktycznie w
każdym aspekcie projektu: komunikacji między programistami, zarządzaniu
wydaniami, śledzeniu błędów, stabilizacji kodu czy eksperymentowaniu,
może także służyć do uwierzyteniania i przypisywania zasług
poszczególnym programistom. System kontroli wersji stanowi centralny
punkt we wszystkich wspomnianych obszarach. Sercem kontroli wersji jest
zarządzanie zmianami, pozwalające odróżnić każdą
atomową zmianę w plikach projektu, metadane z nią związane (jak data i
autor danej zmiany) i przekazać ją do innych użytkowników w sposób, w
jaki sobie tego zażyczą. To kanał komunikacyjny, w którym podstawową
jednostką informacji jest pojedyncza zmiana.
Ten rozdział nie omawia wszystkich aspektów korzystania z systemu
kontroli wersji. To tak rozległy temat, że przy okazji omawiania innych
kwestii będziemy do niego wracali jeszcze nie raz w tej książce. Tutaj
skupimy się na wybraniu i konfiguracji systemu kontroli wersji w taki
sposób, który wspiera współpracę nad rozwojem projektu.
Słownictwo kontroli wersji
Ta książka nie może nauczyć cię kontroli wersji, jeśli nigdy wcześniej
z niej nie korzystałeś. Z drugiej strony trudno byłoby rozmawiać o niej
bez wprowadzenia kilku podstawowych pojęć. Te pojęcia są niezależne od
konkretnego systemu kontroli wersji, to podstawowe rzeczowniki i
przymiotniki gdy współpracujemy w sieci, i będą często stosowane w
dalszej części książki. Nawet gdyby nie wymyślono systemów kontroli
wersji, problem zarządzania zmianami ciągle by istniał—a więc
potrzebujemy języka, pozwalającego mówić o problemie w zwięzły sposób.
commit
Dokonać zmiany w projekcie. Bardziej formalnie, zapisać
zmianę w bazie danych systemu kontroli wersji w taki sposób, że
może zostać włączona do przyszłych wydań projektu. "Commit" można
stosować jako czasownik lub rzeczownikW języku polskim
nie ma dobrego odpowiednika, więc zachowane zostało angielskie
słowo "commit" w formie rzeczownikowej. Warto jednak dodać, że
niektórzy programiści mówią slangowo "zkommitować" czy
"kommitnąć" (przyp. tłum.), jako rzeczownik to w
zasadzie synonim "zmiany". Na przykład: "Właśnie zrobiłem commit
poprawki dla błędu powodującego problemy ze stabilnością serwera,
zgłaszanego przez użytkowników Mac OS X. Jay, mógłbyś przejrzeć
commit i sprawdzić, czy dobrze używam w niej
alokatora?"
komentarz do zmiany (ang.
log message)
Krótka wiadomość dołączona do każdego commita,
opisująca jego naturę i cel. Komentarze do zmian to jedne z
najważniejszych dokumentów każdego projektu, stanowią most
pomiędzy bardzo technicznym językiem samego kodu, a bardziej
zorientowanym na użytkownika językiem mówiącym o zadaniach,
poprawkach błędów i postępie projektu. Dalej w tym rozdziale
omówimy sposoby dystrybucji komentarzy zmian do odpowiednich
odbiorców. Co więcej, w
mówi o tym, jak
zachęcić uczestników projektu do pisania zwięzłych i
użytecznych komentarzy do zmian.
aktualizacja (ang.
update)
Aktualizacja to dołączenie zmian dokonanych przez
innych do lokalnej kopii projektu, a więc sprawienie, aby kopia
stała się aktualna. To bardzo częsta czynność, większość
programistów aktualizuje swój kod wiele razy dziennie, aby mieć
pewność, że pracują mniej-więcej na tej samej wersji kodu, co
pozostali. Co więcej, gdy znajdą błąd, mogą być niemal pewni, że
nie został on jeszcze naprawiony. Na przykład: "Hej,
zauważyłem, że kod indeksujący zawsze wyrzuca ostatni bajt. Czy
to nowy błąd?" "Tak, ale został już naprawiony tydzień
temu—zrób aktualizację, powinien
zniknąć."
repozytorium (ang.
repository)
Baza danych, w której zapisywane są zmiany. Niektóre
systemy wersji są zcentralizowane: istnieje jedno główne
repozytorium, przechowujące wszystkie zmiany. Inne są
zdecentralizowane: każdy programista ma swoje własne
repozytorium, a zmiany mogą być dowolnie przenoszone pomiędzy
repozytoriami. System kontroli wersji śledzi zależności
pomiędzy zmianami, i gdy nadejdzie czas wydania, odpowiedni
zestaw zmian zostaje zaakceptowany do nowej wersji. Pytanie czy
lepsze są systemy zcentralizowane czy rozproszone to jedna z
wciąż żywych programistycznych świętych wojen, postaraj się
unikać kłótni na ten temat na listach dyskusyjnych
projektu.
checkout
Proces pobierania kopii projektu z repozytorium.
CheckoutW języku polskim nie ma dobrego odpowiednika,
więc zachowane zostało angielskie słowo "checkout" (przyp.
tłum.) zazwyczaj tworzy drzewo podkatalogów,
nazywane "kopią roboczą" (patrz niżej), w której zmiany mogą być
wysyłane do repozytorium (jako commit). W niektórych
zdecentralizowanych systemach kontroli wersji każda kopia robocza
jest zarazem repozytorium, a zmiany mogą być wypychane z (lub
wciągane do) każdego repozytorium, które je
zaakceptuje.
kopia robocza (ang. working
copy)
Prywatne drzewo katalogów każdego programisty,
zawierające kod źródłowy projektu i być może jego stronę WWW,
czy inne dokumenty. Kopia robocza zawiera także pewną ilość
metadanych, zarządzanych przez system kontroli wersji,
określających z jakiego repozytorium pochodzi, jakie "wersje"
(patrz niżej) plików są obecne, itd. Na ogół każdy programista
ma swoją własną kopię roboczą, w której dokonuje zmian i je
testuje, i z której wykonuje commit.
wersja (ang.
revision), zmiana
(ang. change), zbiór
zmian (ang.
changeset)
"Wersja" to na ogół konkretne wcielenie danego pliku
lub katalogu. Na przykład plik F może być najpierw w wersji 6,
następnie ktoś wykonuje commit zmieniający plik F, tworząc
wersję 7 pliku F. Niektóre systemy stosują pojęcia "wersja",
"zmiana" czy "zbiór zmian" aby opisać zbiór zmian, wysłanych w
jednym commicie jako jedna abstrakcyjna operacja.
Niekiedy te pojęcia mają różne znaczenia w poszczególnych
systemach kontroli wersji, ale sama idea pozostaje bez zmian:
pozwalają one mówić precyzyjnie o pewnych punktach w czasie
historii pliku lub zbioru plików (na przykład przed i po
poprawce jakiegoś błędu). Na przykład: "Tak, naprawiła to w
wersji 10" lub "Naprawiła to w wersji 10 pliku foo.c".
Gdy ktoś mówi o pliku lub grupie plików bez wspominania o
konkretnej wersji, na ogół zakłada się, że ma na myśli jego
(ich) najnowszą wersję dostępną w
repozytorium.
Wieloznaczność słowa "wersja"
Słowo wersja jest także używane w kontekście "wersji
oprogramowania", jak na przykład "wersja 1.0". Należy odróżnić wersję
w tym znaczeniu, i w znaczeniu systemu kontroli
wersjiDlatego w języku angielskim na określenie "wersji" w
rozumieniu systemu kontroli wersji często stosowane jest słowo
"revision", zamiast "version" (przyp.
tłum.).
diff
Tekstowa reprezentacja zmiany. Diff wskazuje, które linie
uległy zmianie i w jaki sposób, pokazując przy okazji kilka linii
kontekstu przed i po. Programista, który zna dany obszar kodu może
na ogół przeczytać diff i zrozumieć, na czym polega zmiana, a być
może nawet wyłapać błędy.
etykieta (ang.
tag)
Określa pewien zbiór plików w ściśle określonych
wersjach. Etykiety sa na ogół używane do oznaczania ważnych
momentów w życiu projektu. Na przykład etykieta jest na ogół
tworzona dla każdego publicznego wydania, tak, aby każdy mógł
pobrać bezpośrednio z repozytorium dokładnie te same wersje
plików, które zostały wydane. Popularnymi nazwami etykiet są na
przykład Release_1_0,
Delivery_00456, itd.
gałąź (ang.
branch)
Kopia projektu znajdująca się w repozytorium, ale
izolowana w taki sposób, że zmiany w gałęzi nie wpływają na
resztę projektu, i odwrotnie, do czasu gdy zmiany nie zostaną
przez kogoś "scalone" (patrz niżej). Gałęzie bywają także
nazywane "liniami rozwoju". Nawet gdy projekt nie posiada wielu
gałęzi, mówi się że rozwój odbywa się na "głównej gałęzi",
także nazywanej "pniem" (ang.
trunk).
Gałęzie dają możliwość odizolowania od siebie różnych linii
rozwoju. Na przykład gałąź może powstać na potrzeby
eksperymentalnego kodu, który mógłby zdestabilizować główną
gałąź. Albo odwrotnie, gałąź może być użyta jako miejsce, w
którym nowe wydanie będzie stabilizowane. Podczas procesu
wydania normalny rozwój może odbywać się w głównej gałęzi
repozytorium, a w tym samym czasie na gałęzi utworzonej dla
wydania nie będą akceptowane żadne zmiany oprócz tych, które
zostały dozwolone przez zarządzających wydaniem. W ten sposób
wydanie nowej wersji nie musi kolidować z normalnym rozwojem.
Patrz dalej
w tym rozdziale aby dowiedzieć się więcej o
gałęziach.
scalanie lub portowanie (ang.
merge lub
port)
Przeniesienie zmiany z jednej gałęzi na inną. Chodzi
zarówno o scalanie zmian z głównej gałęzi do innej gałęzi, jak
i w drugą stronę. To najczęściej stosowane w praktyce rodzaje
scaleń—rzadko przenosi się zmiany pomiędzy dwoma
gałęziami, z których żadna nie jest główną. Patrz oby dowiedzieć się więcej o
takich scalaniach.
"Scalanie" ma jeszcze drugie, podobne znaczenie: to
zachowanie systemu kontroli wersji gdy stwierdzi, że dwóch
użytkowników dokonało zmian w tym samym pliku, które nie
zachodzą na siebie. Takie zmiany na ogół nie mają na siebie
wpływu, więc u tego użytkownika, który dokona aktualizacji
pliku (w którym sam dokonał zmian), zmiany innych zostaną
automatycznie scalone. To bardzo częsta sytuacja, szczególnie w
projektach, w których wiele osób pracuje nad tym samym kodem.
Gdy dwie różne zmiany zachodzą na siebie,
pojawia się "konflikt" (patrz niżej).
konflikt (ang.
conflict)
Konflikt zachodzi, gdy dwie osoby próbują dokonać zmian
dokładnie w tym samym miejscu kodu. Wszystkie systemy kontroli
wersji automatycznie wykrywają konflikty i powiadamiają jednego
z użytkowników o ich istnieniu. Reszta jest w rękach człowieka,
musi on ręcznie rozwiązać (ang.
resolve) konflikt i poinformować o tym
system kontroli wersji.
blokada (ang.
lock)
Sposób na zadeklarowanie wyłączności na zmiany w danym
pliku lub katalogu. Na przykład: "Nie mogę zrobić commitu moich
zmian w stronach WWW. Wygląda na to, że Alfred założył blokadę
na czas poprawek w obrazkach tła." Nie wszystkie systemy
kontroli wersji pozwalają na stosowanie blokad, a z tych które
pozwalają, nie wszystkie wymagają korzystania z nich. To
dlatego, że równoległy wspólny rozwój jest standardem, a
blokowanie plików przed zmianami innych jest (na ogół)
sprzeczne z tą ideą.
Mówi się, że systemy kontroli wersji, które wymagają
stosowania blokad aby wykonać commit, pracują w modelu
blokada-modyfikacja-odblokowanie. Te,
które ich nie wymagają stosują model
kopia-modyfikacja-scalanie. Doskonałe
wyjaśnienie i porównanie obu modeli można znaleźć w .
Na ogół model kopia-modyfikacja-scalanie jest lepszy dla
rozwoju otwartego oprogramowania, i wszystkie systemy kontroli
wersji omówione w tym rozdziale wspierają taki
model.
Wybór systemu kontroli wersji
W chwili pisania tych słów dwoma najpopularniejszymi systemami kontroli
wersji w świecie wolnego oprogramowania sią CVS
(Concurrent Versions System, ) i SVN
(Subversion, ).
CVS istnieje od bardzo dawna. Większość doświadczonych programistów jest
już przyzwyczajona do korzystania z niego. Mniej więcej spełania swoje
zadanie i jest popularny od bardzo dawna, więc wybierając CVS raczej nie
doprowadzisz do długiej dyskusji o tym, czy to dobry wybór. Jednak CVS ma
pewne wady. Nie pozwala na łatwe odróżnianie tego, że dana zmiana dotyczyła
wielu plików, nie pozwala na zmianę nazwy czy kopiowanie plików pod kontrolą
wersji (jeśli więc potrzebujesz przeorganizować strukturę kodu w trakcie
projektu, masz problem), ma słabe wsparcie dla scalania, nie obsługuje dobrze
dużych plików ani plików binarnych, a niektóre operacje bywają bardzo powolne,
gdy dotyczą wielu plików.
Żadna z tych wad nie jest dyskwalifikująca, więc CVS jest wciąż dość
popularny. Jednak w ostatnich kilku latach system kontroli wersji Subversion
zaczął zyskiwać zwolenników, szczególnie w nowszych
projektach.Patrz i
aby zobaczyć dowody tego trendu. Jeśli rozpoczynasz nowy
projekt, polecam Subversion.
Z drugiej strony jestem zaangażowany w projekt Subversion, więc moja
obiektywność może być kwestionowana. Co więcej, w ostatnich latach
pojawiło się wiele nowych systemów kontroli wersji na wolnych licencjach.
zawiera listę wszystkich, które znam,
posortowanych według (przybliżonej) popularności. Uświadamia ona, że wybór
systemu kontroli wersji może stać się projektem badawczym na całe życie.
Być może dylematów pozbawi Cię dostawca hostingu, jeśli jednak musisz
wybierać, porozmawiaj z innymi programistami, zapytaj znajomych o ich
doświadczenia, a następnie wybierz jeden system i przy nim pozostań. Każdy
stabilny i gotowy do zastnowań produkcyjnych system kontroli wersji
powinien wystarczyć, nie musisz martwić się za bardzo skutkami swojej
decyzji. Jeśli jednak nie możesz się zdecydować, skorzystaj z Subversion.
Jest dość łatwy w nauce, i najprawdopodobniej pozostanie standardem przez
przynajmniej kilka late.
Korzystanie z systemu kontroli wersji
Rady w tym rozdziale nie dotyczą jakiegoś konkretnego systemu kontroli
wersji, ich zastosowanie powinno być łatwe w każdym z nich. Sprawdź
dokumentację Twojego systemu kontroli wersji aby dowiedzieć się
wiecej.
Wersjonuj wszystko
Kontrolę wersji stosuj nie tylko dla kodu źródłowego projeku, ale także
strony internetowej, dokumentacji, FAQ, dokumentów projektowych i
wszystkiego innego, co ludzie mogliby edytować. Przechowuj je zaraz obok
kodu, w tym samym repozytorium. Każdą informację, którą warto zapisać,
warto też wersjonować—a więc każdą informację, która może ulec
zmienie. Rzeczy które nie ulegają zmianie powinny być archiwizowane, nie
wersjonowane. Na przykład email po wysłaniu nie może już zmienić treści, a
więc kontrola wersji w tym przypadku nie miałaby sensu (do czasu, gdy nie
stanie się częścią jakiegoś większego, ewolującego dokumentu).
Wersjonowanie wszystkiego razem, w jednym miejscu, jest tak ważne, gdyż
wtedy ludzi muszą nauczyć się tylko jednego mechanizmu nadsyłania zmian.
Często uczestnik projektu zaczyna od edycji strony internetowej czy
dokumentacji, a następnie stopniowo przechodzi do trudniejszych zadań. Gdy
projekt korzysta z tego samego systemu dla wszystkich zmian, ludzi muszą
nauczyć się korzystać z niego jedynie raz. Wersjonowanie wszystkiego razem
oznacza też, że commit nowego kodu może zawierać też aktualizację
dokumentacji, utworzenie gałęzi kodu tworzy także gałąź dokumentacji, i
tak dalej.
W przechowuj w repozytorium plików generowanych.
Nie są one edytowalnymi danymi, gdyż są generowane automatycznie na
podstawie innych plików. Na przykład niektóre systemy budowania tworzą
plik configure w oparciu o szablon
configure.in. Aby dokonać zmian w pliku
configure należy wyedytować
configure.in i wygenerować plik wynikowy, a więc
jedynie szablon jest "plikiem edytowalnym". Wersjonuj jedynie
szablony—jeśli będziesz wersjonować także pliki wynikowe, ludzi będą
zapominać o tym, aby je ponownie wygenerować po dokonaniu zmian w
szablonie, a wynikające z tego niespójności będą prowadzić do sporego
zamieszania.Aby poznać inną opinię na temat wersjonowania
plików configure, przeczytaj wpis na blogu
Alexey'a Makhotkina zatytułowany "configure.in and
version control", dostępny pod adresem .
Od zasady mówiącej, że wszystkie edytowalne dane powinny być przechowywane w
systemie kontroli wersji, jest niestety jeden wyjątek: system śledzenia
błędów. Bazy błędów zawierają wiele edytowalnych danych, ale z powodów
technicznych nie przechowują ich w głównym systemie kontroli wersji.
Niektóre z nich mają własne prymitywne możliwości wersjonowania, są one
jednak zupełnie niezależne od głównego repozytorium projektu.
Możliwość przeglądania
Repozytorium projektu powinno dać się przeglądać przy użyciu
przeglądarki internetowej. Nie chodzi tu tylko o możliwość dostępu do
najnowszych wersji plików, ale także cofanie się w czasie i podgląd
starych wersji, porównywanie różnic pomiędzy wersjami, czytania komentarzy
do zmian, i tak dalej.
Możliwość przeglądania jest istotna, ponieważ daje możliwość łatwego
dostępu do danych projektu. Gdyby repozytorium nie było dostępne za pomocą
przeglądarki, wtedy każdy kto chciałby sprawdzić zawartość jakiegoś pliku
(na przykład aby sprawdzić, czy pewna poprawka została dołączona do kodu)
musiałby najpierw zainstalować u siebie klienta systemu kontroli wersji,
co mogłoby zmienić kilkuminutowe zapytanie w pół godzinne zadanie.
Możliwość przeglądania zakłada też istnienie standardowych adresów do
przeglądania wybranych wersji plików, włączając w to tę najnowszą. To może
być bardzo przydatne w dyskusjach technicznych lub w odsyłaczach do
dokumentacji. Na przykład zamiast mówić "Aby znaleźć porady dotyczące
debugowania serwera sprawdź plik www/hacking.html w swojej kopii roboczej"
można powiedzieć "Aby znaleźć porady dotyczące debugowania serwera sprawdź
http://subversion.apache.org/docs/community-guide/",
podając adres wskazujący na najbardziej aktualną wersję pliku
hacking.html. Adres URL jest lepszy, ponieważ jest
jednoznaczny i niezależny od tego, na ile aktualną kopię roboczą posiada
adresat.
Niektóre systemy kontroli wersji posiadają wbudowane mechanizmy do
przeglądania repozytorium, inne polegają na zewnętrznych narzędziach.
Takimi narzędziami są ViewCVS (),
CVSWeb (), i
WebSVN ().
Pierwszy z nich współpracuje zarówno z CVS jak i Subversion, drugi jedynie
z CVS, a trzeci tylko i wyłącznie z Subversion.
Powiadomienia o commitach
Każdy commit do repozytorim powinien powodować wysłanie emaila
zawierającego informacje o autorze zmian, czasie ich wykonania,
zmodyfikowanych plikach i różnicach w stosunku do wersji pierwotnej. Ten
email powinien zostać wysłany na specjalną listę dyskusyjną, odrębną od
tej, na której dyskutują ludzie. Programiści (i inne zainteresowane osoby)
powinni być zachęcani do subskrybowania tej listy, gdyż jest to
najefektywniejszy sposób na to, aby śledzić zmiany w projekcie na poziomie
kodu. Oprócz oczywistych zalet takiego przeglądu kodu (patrz ), takie powiadomienia wzmacniają społeczność,
gdyż tworzą wspólne forum na którym ludzie mogą reagować na zdarzenia
(commity) widoczne dla wszystkich innych.
Szczegóły konfiguracji powiadomień są zależne od konkretnego systemu
kontroli wersji, ale na ogół istnieje gotowy skrypt, który można w tym
celu wykorzystać. Jeśli masz problemy z jego odnalezieniem, spróbuj
poszukać w dokumentacji pod hasłem hooks, a w
szczególności post-commit hook (w terminologii CVS
loginfo hook). Nie ma przyjętego polskiego
odpowiednika, więc na potrzeby tego rozdziału użyjemy bezpośredniego
tłumaczenia "hak". Haki post-commit pozwalają na automatyczne wykonywanie
pewnych zadań w odpowiedzi na commi. Hak zostaje wykonany dla każdego
commita, otrzymując wszystkie konieczne informacje o nim—których
może użyć na przykład do wysłania emaila.
Czasem warto zmodyfikować domyślne zachowanie gotowego skryptu
wysyłającego powiadomienia:
Some commit mailers don't include the actual diffs in the
email, but instead provide a URL to view the change on the web using
the repository browsing system. While it's good to provide the URL,
so the change can be referred to later, it is also
very important that the commit email include
the diffs themselves. Reading email is already part of people's
routine, so if the content of the change is visible right there in
the commit email, developers will review the commit on the spot,
without leaving their mail reader. If they have to click on a URL to
review the change, most won't do it, because that requires a new
action instead of a continuation of what they were already doing.
Furthermore, if the reviewer wants to ask something about the
change, it's vastly easier to hit reply-with-text and simply
annotate the quoted diff than it is to visit a web page and
laboriously cut-and-paste parts of the diff from web browser to
email client.
(Of course, if the diff is huge, such as when a large body of
new code has been added to the repository, then it makes sense to
omit the diff and offer only the URL. Most commit mailers can do
this kind of limiting automatically. If yours can't, then it's
still better to include diffs, and live with the occasional huge
email, than to leave the diffs off entirely. Convenient reviewing
and commenting is a cornerstone of cooperative development, much
too important to do without.)
The commit emails should set their Reply-to header
to the regular development list, not the commit email list. That
is, when someone reviews a commit and writes a response, their
response should be automatically directed toward the human
development list, where technical issues are normally discussed.
There are a few reasons for this. First, you want to keep all
technical discussion on one list, because that's where people expect
it to happen, and because that way there's only one archive to
search. Second, there might be interested parties not subscribed to
the commit email list. Third, the commit email list advertises
itself as a service for watching commits, not for watching commits
and occasional technical discussions. Those who
subscribed to the commit email list did not sign up for anything but
commit emails; sending them other material via that list would
violate an implicit contract. Fourth, people often write programs
that read the commit email list and process the results (for
display on a web page, for example). Those programs are prepared to
handle consistently-formatted commit emails, but not inconsistent
human-written mails.
Note that this advice to set Reply-to does not contradict the
recommendations in
earlier in
this chapter. It's
always okay for the sender of a message to set
Reply-to. In this case, the sender is the version control system
itself, and it sets Reply-to in order to indicate that the
appropriate place for replies is the development mailing list, not
the commit list.
CIA: Another Change Publication Mechanism
Commit emails are not the only way to propagate change news.
Recently, another mechanism called CIA () has been developed. CIA is a real-time
commit statistics aggregator and distributor. The most popular use of
CIA is to send commit notifications to IRC channels, so that people
logged into those channels see the commits happening in real time.
Though of somewhat less technical utility than commit emails, since
observers might or might not be around when a commit notice pops up in
IRC, this technique is of immense social utility.
People get the sense of being part of something alive and active, and
feel that they can see progress being made right before their
eyes.
The way it works is that you invoke the CIA notifier program
from your post-commit hook. The notifier formats the commit
information into an XML message, and sends to a central server
(typically cia.navi.cx). That server then
distributes the commit information to other forums.
CIA can also be configured to send out RSS
feeds. See the documentation at
for details.
To see an example of CIA in action, point your IRC
client at irc.freenode.net, channel
#commits.
Use branches to avoid bottlenecks
Non-expert version control users are sometimes a bit afraid of
branching and merging. This is probably a side effect of CVS's
popularity: CVS's interface for branching and merging is somewhat
counterintuitive, so many people have learned to avoid those
operations entirely.
If you are among those people, resolve right now to conquer any
fears you may have and take the time to learn how to do branching and
merging. They are not difficult operations, once you get used to
them, and they become increasingly important as a project acquires
more developers.
Branches are valuable because they turn a scarce
resource—working room in the project's code—into an
abundant one. Normally, all developers work together in the same
sandbox, constructing the same castle. When someone wants to add a
new drawbridge, but can't convince everyone else that it would be an
improvement, branching makes it possible for her to go to an isolated
corner and try it out. If the effort succeeds, she can invite the
other developers to examine the result. If everyone agrees that the
result is good, they can tell the version control system to move
("merge") the drawbridge from the branch castle over to the main
castle.
It's easy to see how this ability helps collaborative
development. People need the freedom to try new things without
feeling like they're interfering with others' work. Equally
importantly, there are times when code needs to be isolated from the
usual development churn, in order to get a bug fixed or a release
stabilized (see and
in
) without worrying
about tracking a moving target.
Use branches liberally, and encourage others to use them. But
also make sure that a given branch is only active for exactly as long
as needed. Every active branch is a slight drain on the community's
attention. Even those who are not working in a branch still maintain
a peripheral awareness of what's going on in it. Such awareness is
desirable, of course, and commit emails should be sent out for branch
commits just as for any other commit. But branches should not become
a mechanism for dividing the development community. With rare
exceptions, the eventual goal of most branches should be to merge
their changes back into the main line and disappear.
Singularity of information
Merging has an important corollary: never commit the same change
twice. That is, a given change should enter the version control
system exactly once. The revision (or set of revisions) in which the
change entered is its unique identifier from then on. If it needs to
be applied to branches other than the one on which it entered, then it
should be merged from its original entry point to those other
destinations—as opposed to committing a textually identical
change, which would have the same effect in the code, but would make
accurate bookkeeping and release management impossible.
The practical effects of this advice differ from one version
control system to another. In some systems, merges are special
events, fundamentally distinct from commits, and carry their own
metadata with them. In others, the results of merges are committed
the same way other changes are committed, so the primary means of
distinguishing a "merge commit" from a "new change commit" is in the
log message. In a merge's log message, don't repeat the log message
of the original change. Instead, just indicate that this is a merge,
and give the identifying revision of the original change, with at most
a one-sentence summary of its effect. If someone wants to see the
full log message, she should consult the original revision.
The reason it's important to avoid repeating the log message is
that log messages are sometimes edited after they've been committed.
If a change's log message were repeated at each merge destination,
then even if someone edited the original message, she'd still leave
all the repeats uncorrected—which would only cause confusion
down the road.
The same principle applies to reverting a change. If a change
is withdrawn from the code, then the log message for the reversion
should merely state that some specific revision(s) is being reverted,
not describe the actual code change that results
from the reversion, since the semantics of the change can be derived
by reading the original log message and change. Of course, the
reversion's log message should also state the reason why the change is
being reverted, but it should not duplicate anything from the original
change's log message. If possible, go back and edit the original
change's log message to point out that it was reverted.
All of the above implies that you should use a consistent syntax
for referring to revisions. This is helpful not only in log messages,
but in emails, the bug tracker, and elsewhere. If you're using
CVS, I suggest "path/to/file/in/project/tree:REV",
where REV is a CVS revision number such as "1.76". If you're using
Subversion, the standard syntax for revision 1729 is "r1729" (file
paths are not needed because Subversion uses global revision numbers).
In other systems, there is usually a standard syntax for expressing
the changeset name. Whatever the appropriate syntax is for your
system, encourage people to use it when referring to changes.
Consistent expression of change names makes project bookkeeping much
easier (as we will see in and
), and since a lot of the
bookkeeping will be done by volunteers, it needs to be as easy as
possible.
See also
in
.
Authorization
Most version control systems offer a feature whereby certain
people can be allowed or disallowed from committing in specific
sub-areas of the repository. Following the principle that when handed
a hammer, people start looking around for nails, many projects use
this feature with abandon, carefully granting people access to just
those areas where they have been approved to commit, and making sure
they can't commit anywhere else. (See
in
for how projects
decide who can commit where.)
There is probably little harm done by exercising such tight
control, but a more relaxed policy is fine too. Some projects simply
use an honor system: when a person is granted commit access, even for
a sub-area of the repository, what they actually receive is a password
that allows them to commit anywhere in the project. They're just
asked to keep their commits in their area. Remember that there is no
real risk here: in an active project, all commits are reviewed anyway.
If someone commits where they're not supposed to, others will
notice it and say something. If a change needs to be undone, that's
simple enough—everything's under version control anyway, so
just revert.
There are several advantages to the relaxed approach. First, as
developers expand into other areas (which they usually will if they
stay with the project), there is no administrative overhead to
granting them wider privileges. Once the decision is made, the person
can just start committing in the new area right away.
Second, expansion can be done in a more fine-grained manner.
Generally, a committer in area X who wants to expand to area Y will
start posting patches against Y and asking for review. If someone who
already has commit access to area Y sees such a patch and approves of
it, they can just tell the submitter to commit the change directly
(mentioning the reviewer/approver's name in the log message, of
course). That way, the commit will come from the person who actually
wrote the change, which is preferable from both an information
management standpoint and from a crediting standpoint.
Last, and perhaps most important, using the honor system
encourages an atmosphere of trust and mutual respect. Giving someone
commit access to a subdomain is a statement about their technical
preparedness—it says: "We see you have expertise to make commits
in a certain domain, so go for it." But imposing strict authorization
controls says: "Not only are we asserting a limit on your expertise,
we're also a bit suspicious about
your intentions." That's not the sort of
statement you want to make if you can avoid it. Bringing someone into
the project as a committer is an opportunity to initiate them into a
circle of mutual trust. A good way to do that is to give them more
power than they're supposed to use, then inform them that it's up to
them to stay within the stated limits.
The Subversion project has operated on the honor system way for
more than four years, with 33 full and 43 partial committers as of
this writing. The only distinction the system actually enforces is
between committers and non-committers; further subdivisions are
maintained solely by humans. Yet we've never had a problem with
someone deliberately committing outside their domain. Once or twice
there's been an innocent misunderstanding about the extent of
someone's commit privileges, but it's always been resolved quickly and
amiably.
Obviously, in situations where self-policing is impractical, you
must rely on hard authorization controls. But such situations are
rare. Even when there are millions of lines of code and hundreds or
thousands of developers, a commit to any given code module should
still be reviewed by those who work on that module, and they can
recognize if someone committed there who wasn't supposed to. If
regular commit review isn't happening, then the
project has bigger problems to deal with than the authorization system
anyway.
In summary, don't spend too much time fiddling with the version
control authorization system, unless you have a specific reason to. It
usually won't bring much tangible benefit, and there are advantages to
relying on human controls instead.
None of this should be taken to mean that the restrictions
themselves are unimportant, of course. It would be bad for a project
to encourage people to commit in areas where they're not qualified.
Furthermore, in many projects, full (unrestricted) commit access has a
special status: it implies voting rights on project-wide questions.
This political aspect of commit access is discussed more in in
.
Bug Tracker
Bug tracking is a broad topic; various aspects of it are
discussed throughout this book. Here I'll try to concentrate mainly
on setup and technical considerations, but to get to those, we have to
start with a policy question: exactly what kind of information should
be kept in a bug tracker?
The term bug tracker is misleading. Bug
tracking systems are also frequently used to track new feature
requests, one-time tasks, unsolicited patches—really anything
that has distinct beginning and end states, with optional transition
states in between, and that accrues information over its lifetime.
For this reason, bug trackers are also called issue
trackers, defect trackers,
artifact trackers, request
trackers, trouble ticket systems,
etc. See for a list of software.
In this book, I'll continue to use "bug tracker" for the
software that does the tracking, because that's what most people call
it, but will use issue to refer to a single
item in the bug tracker's database. This allows us to distinguish
between the behavior or misbehavior that the user encountered (that is,
the bug itself), and the tracker's record of the
bug's discovery, diagnosis, and eventual resolution. Keep in mind
that although most issues are about actual bugs, issues can be used to
track other kinds of tasks too.
The classic issue life cycle looks like this:
Someone files the issue. They provide a summary, an
initial description (including a reproduction recipe, if
applicable; see
in
for
how to encourage good bug reports), and whatever other
information the tracker asks for. The person who files
the issue may be totally unknown to the project—bug
reports and feature requests are as likely to come from
the user community as from the developers.
Once filed, the issue is in what's called an
open state. Because no action has
been taken yet, some trackers also label it as
unverified and/or
unstarted. It is not assigned to
anyone; or, in some systems, it is assigned to a fake
user to represent the lack of real assignation. At this
point, it is in a holding area: the issue has been
recorded, but not yet integrated into the project's
consciousness.
Others read the issue, add comments to it, and
perhaps ask the original filer for clarification on some
points.
The bug gets reproduced.
This may be the most important moment in its
life cycle. Although the bug is not actually fixed yet,
the fact that someone besides the original filer was able
to make it happen proves that it is genuine, and, no less
importantly, confirms to the original filer that they've
contributed to the project by reporting a real bug.
The bug gets diagnosed: its
cause is identified, and if possible, the effort required
to fix it is estimated. Make sure these things get
recorded in the issue; if the person who diagnosed the
bug suddenly has to step away from the project for a
while (as can often happen with volunteer developers),
someone else should be able to pick up where she left
off.
In this stage, or sometimes the previous one, a
developer may "take ownership" of the issue and
assign it to herself ( in
examines the assignment process in more detail). The issue's
priority may also be set at this
stage. For example, if it is so severe that it should
delay the next release, that fact needs to be identified
early, and the tracker should have some way of noting
it.
The issue gets scheduled for resolution.
Scheduling doesn't necessarily mean naming a date by which
it will be fixed. Sometimes it just means deciding which
future release (not necessarily the next one) the bug
should be fixed by, or deciding that it need not block any
particular release. Scheduling may also be dispensed
with, if the bug is quick to fix.
The bug gets fixed (or the task completed, or
the patch applied, or whatever). The change or set of
changes that fixed it should be recorded in a comment in
the issue, after which the issue is
closed and/or marked as
resolved.
There are some common variations on this life cycle. Sometimes
an issue is closed very soon after being filed, because it turns out
not to be a bug at all, but rather a misunderstanding on the part of
the user. As a project acquires more users, more and more such
invalid issues will come in, and developers will close them with
increasingly short-tempered responses. Try to guard against the
latter tendency. It does no one any good, as the individual user in
each case is not responsible for all the previous invalid issues; the
statistical trend is visible only from the developers' point of view,
not the user's. (In
later
in this chapter, we'll look at
techniques for reducing the number of invalid issues.) Also, if
different users are experiencing the same misunderstanding over and
over, it might mean that that aspect of the software needs to be
redesigned. This sort of pattern is easiest to notice when there is
an issue manager monitoring the bug database; see
in
.
Another common life cycle variation is for the issue to be closed
as a duplicate soon after Step 1. A duplicate
is when someone files an issue that's already known to the project.
Duplicates are not confined to open issues: it's possible for a bug to
come back after having been fixed (this is known as a
regression), in which case the preferred course
is usually to reopen the original issue and close any new reports as
duplicates of the original one. The bug tracking system should keep
track of this relationship bidirectionally, so that reproduction
information in the duplicates is available to the original issue, and
vice versa.
A third variation is for the developers to close the issue,
thinking they have fixed it, only to have the original reporter reject
the fix and reopen it. This is usually because the developers simply
don't have access to the environment necessary to reproduce the bug,
or because they didn't test the fix using the exact same reproduction
recipe as the reporter.
Aside from these variations, there may be other small details of
the life cycle that vary depending on the tracking software. But the
basic shape is the same, and while the life cycle itself is not
specific to open source software, it has implications for how open
source projects use their bug trackers.
As Step 1 implies, the tracker is as much a public face of the
project as the mailing lists or web pages. Anyone may file an issue,
anyone may look at an issue, and anyone may browse the list of currently
open issues. It follows that you never know how many people are
waiting to see progress on a given issue. While the size and skill of
the development community constrains the rate at which issues can be
resolved, the project should at least try to acknowledge each issue the
moment it appears. Even if the issue lingers for a while, a response
encourages the reporter to stay involved, because she feels that a
human has registered what she has done (remember that filing an
issue usually involves more effort than, say, posting an email).
Furthermore, once an issue is seen by a developer, it enters the
project's consciousness, in the sense that that developer can be on
the lookout for other instances of the issue, can talk about it with
other developers, etc.
The need for timely reactions implies two things:
The tracker must be connected to a mailing list, such that
every change to an issue, including its initial filing, causes a
mail to go out describing what happened. This mailing list
is usually different from the regular development list, since not
all developers may want to receive automated bug mails, but (just
as with commit mails) the Reply-to header should be set to the
development mailing list.
The form for filing issues should capture the reporter's
email address, so she can be contacted for more information.
(However, it should not require the
reporter's email address, as some people prefer to report issues
anonymously. See
later
in this chapter for more on the importance of
anonymity.)
Interaction with Mailing Lists
Make sure the bug tracker doesn't turn into a discussion forum.
Although it is important to maintain a human presence in the bug
tracker, it is not fundamentally suited to real-time discussion.
Think of it rather as an archiver, a way to organize facts and
references to other discussions, primarily those that take place on
mailing lists.
There are two reasons to make this distinction. First, the bug
tracker is more cumbersome to use than the mailing lists (or than
real-time chat forums, for that matter). This is not because bug
trackers have bad user interface design, it's just that their
interfaces were designed for capturing and presenting discrete states,
not free-flowing discussions. Second, not everyone who should be
involved in discussing a given issue is necessarily watching the bug
tracker. Part of good issue management (see
in
) is to make sure
each issue is brought to the right peoples' attention, rather than
requiring every developer to monitor all issues. In
in , we'll look at ways to make
sure people don't accidentally siphon discussions out of appropriate
forums and into the bug tracker.
Some bug trackers can monitor mailing lists and automatically
log all emails that are about a known issue. Typically they do this
by recognizing the issue's identifying number in the subject line of
the mail, as part of a special string; developers learn to include
these strings in their mails to attract the tracker's notice. The bug
tracker may either save the entire email, or (even better) just record
a link to the mail in the regular mailing list archive. Either way,
this is a very useful feature; if your tracker has it, make sure
both to turn it on and to remind people to take advantage of
it.
Pre-Filtering the Bug Tracker
Most issue databases eventually suffer from the same problem: a
crushing load of duplicate or invalid issues filed by well-meaning but
inexperienced or ill-informed users. The first step in combatting
this trend is usually to put a prominent notice on the front page of
the bug tracker, explaining how to tell if a bug is really a bug, how
to search to see if it's already been filed, and finally, how to
effectively report it if one still thinks it's a new bug.
This will reduce the noise level for a while, but as the number
of users increases, the problem will eventually come back. No
individual user can be blamed for it. Each one is just trying to
contribute to the project's well-being, and even if their first bug
report isn't helpful, you still want to encourage them to stay
involved and file better issues in the future. In the meantime,
though, the project needs to keep the issue database as free of junk
as possible.
The two things that will do the most to prevent this problem
are: making sure there are people watching the bug tracker who have
enough knowledge to close issues as invalid or duplicates the moment
they come in, and requiring (or strongly encouraging) users to confirm
their bugs with other people before filing them in the tracker.
The first technique seems to be used universally. Even projects
with huge issue databases (say, the Debian bug tracker at
, which contained 315,929 issues
as of this writing) still arrange things so that
someone sees each issue that comes in. It may be
a different person depending on the category of the issue. For
example, the Debian project is a collection of software packages, so
Debian automatically routes each issue to the appropriate package
maintainers. Of course, users can sometimes misidentify an issue's
category, with the result that the issue is sent to the wrong person
initially, who may then have to reroute it. However, the important
thing is that the burden is still shared—whether the user
guesses right or wrong when filing, issue watching is still
distributed more or less evenly among the developers, so each issue is
able to receive a timely response.
The second technique is less widespread, probably because it's
harder to automate. The essential idea is that every new issue gets
"buddied" into the database. When a user thinks he's found a problem,
he is asked to describe it on one of the mailing lists, or in an IRC
channel, and get confirmation from someone that it is indeed a bug.
Bringing in that second pair of eyes early can prevent a lot of
spurious reports. Sometimes the second party is able to identify that
the behavior is not a bug, or is fixed in recent releases. Or she may
be familiar with the symptoms from a previous issue, and can prevent a
duplicate filing by pointing the user to the older issue. Often it's
enough just to ask the user "Did you search the bug tracker to see if
it's already been reported?" Many people simply don't think of that,
yet are happy to do the search once they know someone's
expecting them to.
The buddy system can really keep the issue database clean, but
it has some disadvantages too. Many people will file solo anyway,
either through not seeing, or through disregarding, the instructions
to find a buddy for new issues. Thus it is still necessary for
volunteers to watch the issue database. Furthermore, because most new
reporters don't understand how difficult the task of maintaining the
issue database is, it's not fair to chide them too harshly for
ignoring the guidelines. Thus the volunteers must be vigilant, and
yet exercise restraint in how they bounce unbuddied issues back to
their reporters. The goal is to train each reporter to use the
buddying system in the future, so that there is an ever-growing pool
of people who understand the issue-filtering system. On seeing an
unbuddied issue, the ideal steps are:
Immediately respond to the issue, politely thanking the user
for filing, but pointing them to the buddying guidelines
(which should, of course, be prominently posted on the web
site).
If the issue is clearly valid and not a duplicate, approve it
anyway, and start it down the normal life cycle. After all,
the reporter's now been informed about buddying, so there's
no point wasting the work done so far by closing a valid
issue.
Otherwise, if the issue is not clearly valid, close it, but
ask the reporter to reopen it if they get confirmation from
a buddy. When they do, they should put a reference to the
confirmation thread (e.g., a URL into the mailing list
archives).
Remember that although this system will improve the signal/noise
ratio in the issue database over time, it will never completely stop
the misfilings. The only way to prevent misfilings entirely is to
close off the bug tracker to everyone but developers—a cure that
is almost always worse than the disease. It's better to accept that
cleaning out invalid issues will always be part of the project's
routine maintenance, and to try to get as many people as possible to
help.
See also
in
.
IRC / Real-Time Chat Systems
Many projects offer real-time chat rooms using Internet
Relay Chat (IRC), forums where users
and developers can ask each other questions and get instant responses.
While you can run an IRC server from your own
web site, it is generally not worth the hassle. Instead, do what
everyone else does: run your IRC channels at Freenode
(). Freenode gives you the control
you need to administer your project's IRC
channels,There is no requirement or expectation that
you donate to Freenode, but if you or your project can afford it,
please consider a contribution. They are a tax-exempt charity in the
U.S., and they perform a valuable service. while
sparing you the not-insignificant trouble of maintaining an IRC server
yourself.
The first thing to do is choose a channel name. The most
obvious choice is the name of your project—if that's available
at Freenode, then use it. If not, try to choose something as close to
your project's name, and as easy to remember, as possible. Advertise
the channel's availabity from your project's web site, so a visitor
with a quick question will see it right away. For example, this
appears in a prominently placed box at the top of Subversion's home
page:
If you're using Subversion, we recommend that you
join the users@subversion.tigris.org
mailing list, and read the Subversion Book and
FAQ.
You can also ask questions on IRC at
irc.freenode.net
channel #svn.
Some projects have multiple channels, one per subtopic. For
example, one channel for installation problems, another for usage
questions, another for development chat, etc. ( in
discusses and how to
divide into multiple channels). When your project is young, there
should only be one channel, with everyone talking together. Later, as
the user-to-developer ratio increases, separate channels may become
necessary.
How will people know all the available channels, let alone which
channel to talk in? And when they talk, how will they know what the
local conventions are?
The answer is to tell them by setting the channel
topic.To set a channel topic, use the
/topic command. All commands in IRC start with
"/". See if
you're not familiar with IRC usage and administration; in particular,
is an
excellent tutorial. The channel topic is a brief
message each user sees when they first enter the channel. It gives
quick guidance to newcomers, and pointers to further information. For
example:
You are now talking on #svn
Topic for #svn is Forum for Subversion user questions, see also
http://subversion.tigris.org/. || Development discussion happens in
#svn-dev. || Please don't paste long transcripts here, instead use
a pastebin site like http://pastebin.ca/. || NEWS: Subversion 1.1.0
is released, see http://svn110.notlong.com/ for details.
That's terse, but it tells newcomers what they need to know. It
says exactly what the channel is for, gives the project home page (in
case someone wanders into the channel without having first been to the
project web site), mentions a related channel, and gives some guidance
about pasting.
Paste Sites
An IRC channel is a shared space: everyone can see what everyone
else is saying. Normally, this is a good thing, as it allows people
to jump into a conversation when they think they have something to
contribute, and allows spectators to learn by watching. But it
becomes problematic when someone has to provide a large quantity of
information at once, such as a debugging session transcript, because
pasting too many lines of output into the channel will disrupt other
conversations.
The solution is to use one of the
pastebin or pastebot
sites. When requesting a large amount of data from someone, ask them
not to paste it into the channel, but instead to go to (for example)
, paste their data into the form
there, and tell the resulting new URL to the IRC channel. Anyone can
then visit the URL and view the data.
There are a number of free paste sites available now, too many
for a comprehensive list, but here are some of the ones I've seen used:
,
,
,
,
and
.
Bots
Many technically-oriented IRC channels have a non-human member,
a so-called bot, that is capable of storing and
regurgitating information in response to specific commands.
Typically, the bot is addressed just like any other member of the
channel, that is, the commands are delivered by "speaking to" the bot.
For example:
<kfogel> ayita: learn diff-cmd = http://subversion.tigris.org/faq.html#diff-cmd
<ayita> Thanks!
That told the bot (who is logged into the channel as ayita) to
remember a certain URL as the answer to the query "diff-cmd". Now we
can address ayita, asking the bot to tell another user about
diff-cmd:
<kfogel> ayita: tell jrandom about diff-cmd
<ayita> jrandom: http://subversion.tigris.org/faq.html#diff-cmd
The same thing can be accomplished via a convenient shorthand:
<kfogel> !a jrandom diff-cmd
<ayita> jrandom: http://subversion.tigris.org/faq.html#diff-cmd
The exact command set and behaviors differ from bot to bot. The
above example is with ayita
(), of which
there is usually an instance running in #svn at
freenode. Other bots include Dancer
() and Supybot
(). Note that no special server
privileges are required to run a bot. A bot is a client program;
anyone can set one up and direct it to listen to a particular
server/channel.
If your channel tends to get the same questions over and over,
I highly recommend setting up a bot. Only a small percentage of
channel users will acquire the expertise needed to manipulate the bot,
but those users will answer a disproportionately high percentage of
questions, because the bot enables them to respond so much more
efficiently.
Archiving IRC
Although it is possible to archive everything that happens in an
IRC channel, it's not necessarily expected. IRC conversations may be
nominally public, but many people think of them as informal,
semi-private conversations. Users may be careless with grammar, and
often express opinions (for example, about other software or other
programmers) that they wouldn't want preserved forever in an online
archive.
Of course, there will sometimes be excerpts
that should be preserved, and that's fine. Most IRC clients can log a
conversation to a file at the user's request, or failing that, one can
always just cut and paste the conversation from IRC into a more
permanent forum (most often the bug tracker). But indiscriminate
logging may make some users uneasy. If you do archive everything,
make sure you state so clearly in the channel topic, and give a URL to
the archive.
Wikis
A wiki is a web site that allows any
visitor to edit or extend its content; the term "wiki" (from a
Hawaiian word meaning "quick" or "super-fast") is also used to refer
to the software that enables such editing. Wikis were invented in
1995, but their popularity has really started to take off since 2000
or 2001, boosted partly by the success of Wikipedia (), a wiki-based free-content
encyclopedia. Think of a wiki as falling somewhere between IRC and
web pages: wikis don't happen in realtime, so people get a chance to
ponder and polish their contributions, but they are also very easy to
add to, involving less interface overhead than editing a regular web
page.
Wikis are not yet standard equipment for open source projects,
but they probably will be soon. As they are relatively new
technology, and people are still experimenting with different ways of
using them, I will just offer a few words of caution here—at
this stage, it's easier to analyze misuses of wikis than to analyze
their successes.
If you decide to run a wiki, put a lot of effort into having a
clear page organization and pleasing visual layout, so that visitors
(i.e., potential editors) will instinctively know how to fit in their
contributions. Equally important, post those standards on the wiki
itself, so people have somewhere to go for guidance. Too often, wiki
administrators fall victim to the fantasy that because hordes of
visitors are individually adding high quality content to the site,
the sum of all these contributions must therefore also be of high
quality. That's not how web sites work. Each individual page or
paragraph may be good when considered by itself, but it will not be
good if embedded in a disorganized or confusing whole. Too often,
wikis suffer from:
Lack of navigational principles.
A well-organized web site makes visitors feel like they know
where they are at any time. For example, if the pages are
well-designed, people can intuitively tell the difference
between a "table of contents" region and a "content" region.
Contributors to a wiki will respect such differences too, but
only if the differences are present to begin with.
Duplication of information.
Wikis frequently end up with different pages saying similar
things, because the individual contributors did not notice the
duplications. This can be partly a consequence of the lack of
navigational principles noted above, in that people may not find
the duplicate content if it is not where they expect it to
be.
Inconsistent target audience.
To some degree this problem is inevitable when there are so many
authors, but it can be lessened if there are written guidelines
about how to create new content. It also helps to aggressively
edit new contributions at the beginning, as an example, so that
the standards start to sink in.
The common solution to all these problems is the same: have
editorial standards, and demonstrate them not only by posting them,
but by editing pages to adhere to them. In general, wikis will
amplify any failings in their original material, since contributors
imitate whatever patterns they see in front of them. Don't just
set up the wiki and hope everything falls into place. You must also
prime it with well-written content, so people have a template to
follow.
The shining example of a well-run wiki is Wikipedia, though this
may be partly
because the content (encyclopedia entries) is naturally well-suited to
the wiki format. But if you examine Wikipedia closely, you'll see
that its administrators laid a very thorough
foundation for cooperation. There is extensive documentation on how
to write new entries, how to maintain an appropriate point of view,
what sorts of edits to make, what edits to avoid, a dispute resolution
process for contested edits (involving several stages, including
eventual arbitration), and so forth. They also have authorization
controls, so that if a page is the target of repeated inappropriate
edits, they can lock it down until the problem is resolved. In other
words, they didn't just throw some templates onto a web site and hope
for the best. Wikipedia works because its founders thought carefully
about how to get thousands of strangers to tailor their writing to a
common vision. While you may not need the same level of preparedness
to run a wiki for a free software project, the spirit is worth
emulating.
For more information about wikis, see
. Also, the first
wiki remains alive and well, and contains a lot of discussion about
running wikis: see ,
, and
for
various points of view.
Web Site
There is not much to say about setting up the project web site
from a technical point of view: setting up a web server and writing
web pages are fairly simple tasks, and most of the important things to
say about layout and arrangement were covered in the previous chapter.
The web site's main function is to present a clear and welcoming
overview of the project, and to bind together the other tools (the
version control system, bug tracker, etc.). If you don't have the
expertise to set up a web server yourself, it's usually not hard to
find someone who does and is willing to help out. Nonetheless, to
save time and effort, people often prefer to use one of the canned
hosting sites.
Canned Hosting
There are two main advantages to using a canned site. The first
is server capacity and bandwidth: their servers are beefy boxes sitting
on really fat pipes. No matter how successful your project gets,
you're not going to run out of disk space or swamp the network
connection. The second advantage is simplicity. They have already
chosen a bug tracker, a version control system, a mailing list manager,
an archiver, and everything else you need to run a site. They've
configured the tools, and are taking care of backups for all the data
stored in the tools. You don't need to make many decisions. All you
have to do is fill in a form, press a button, and suddenly you've got
a project web site.
These are pretty significant benefits. The disadvantage, of
course, is that you must accept their choices and
configurations, even if something different would be better for your
project. Usually canned sites are adjustable within certain narrow
parameters, but you will never get the fine-grained control you would
have if you set up the site yourself and had full administrative
access to the server.
A perfect example of this is the handling of generated files.
Certain project web pages may be generated files—for example,
there are systems for keeping FAQ data in an easy-to-edit master
format, from which HTML, PDF, and other presentation formats can be
generated. As explained in
earlier in this chapter,
you wouldn't want to version the generated formats, only the master
file. But when your web site is hosted on someone else's server, it
may be impossible to set up a custom hook to regenerate the online
HTML version of the FAQ whenever the master file is changed. The only
workaround is to version the generated formats too, so that they show
up on the web site.
There can be larger consequences as well. You may not have as
much control over presentation as you would wish. Some of the canned
hosting sites allow you to customize your web pages, but the site's
default layout usually ends up showing through in various awkward
ways. For example, some projects that host themselves at SourceForge
have completely customized home pages, but still point developers to
their "SourceForge page" for more information. The SourceForge page
is what would be the project's home page, had the project not used a
custom home page. The SourceForge page has links to the bug tracker,
the CVS repository, downloads, etc. Unfortunately, a SourceForge page
also contains a great deal of extraneous noise. The top is a banner
ad, often an animated image. The left side is a vertical arrangement
of links of little relevance to someone interested in the project.
The right side is often another advertisement. Only the center of the
page is devoted to truly project-specific material, and even that is
arranged in a confusing way that often makes visitors unsure of what
to click on next.
Behind every individual aspect of SourceForge's design, there is
no doubt a good reason—good from SourceForge's point of view,
such as the advertisements. But from an individual project's point of
view, the result can be a less-than-ideal web page. I don't mean to
pick on SourceForge; similar concerns apply to many of the canned
hosting sites. The point is that there's a tradeoff. You get relief
from the technical burdens of running a project site, but only at the
price of accepting someone else's way of running it.
Only you can decide whether canned hosting is best for your
project. If you choose a canned site, leave open the option of
switching to your own servers later, by using a custom domain name for
the project's "home address". You can forward the URL to the canned
site, or have a fully customized home page at the public URL and hand
users off to the canned site for sophisticated functionality. Just
make sure to arrange things such that if you later decide to use a
different hosting solution, the project's address doesn't need to
change.
Choosing a canned hosting site
The largest and most well-known hosting site is SourceForge. Two other
sites providing the same or similar services are savannah.gnu.org and BerliOS.de. A few organizations,
such as the Apache Software
Foundation and Tigris.orgDisclaimer:
I am employed by CollabNet, which sponsors
Tigris.org, and I use Tigris regularly., give free
hosting to open source projects that fit well with their missions and
their community of existing projects.
Haggen So did a thorough evaluation of various canned hosting
sites, as part of the research for his Ph.D. thesis,
Construction of an Evaluation Model for Free/Open Source
Project Hosting (FOSPHost) sites. The results are at
, and see especially
the very readable comparison chart at .
Anonymity and involvement
A problem that is not strictly limited to the canned sites, but
is most often found there, is the abuse of user login functionality.
The functionality itself is simple enough: the site allows each
visitor to register herself with a username and password. From
then on it keeps a profile for that user, and project administrators
can assign the user certain permissions, for example, the right to
commit to the repository.
This can be extremely useful, and in fact it's one of the prime
advantages of canned hosting. The problem is that sometimes user
login ends up being required for tasks that ought to be permitted to
unregistered visitors, specifically the ability to file issues in the
bug tracker, and to comment on existing issues. By requiring a
logged-in username for such actions, the project raises the
involvement bar for what should be quick, convenient tasks. Of
course, one wants to be able to contact someone who's entered data
into the issue tracker, but having a field where she can enter her
email address (if she wants to) is sufficient. If a new user spots a
bug and wants to report it, she'll only be annoyed at having to fill
out an account creation form before she can enter the bug into the
tracker. She may simply decide not to file the bug at all.
The advantages of user management generally outweigh the
disadvantages. But if you can choose which actions can be done
anonymously, make sure not only that all
read-only actions are permitted to non-logged-in visitors, but also
some data entry actions, especially in the bug tracker and, if you
have them, wiki pages.