Începutul
Modelul clasic al inițierii unui proiect de software liber a fost
creat de Eric Raymond, într-un articol acum faimos despre proiecte
open-source intitulat Catedrala și bazarul.
El scria:
Fiecare exemplu de software bun începe prin a
scărpina o mâncărime a unui dezvoltator.
(din
)
Trebuie reținut faptul că Rayomnd nu a spus că proiectele open-source
apar doar când un individ simte o nevoie. Mai degrabă spunea că aplicațiile
bune rezultă atunci când programatorul are un
interes personal în a-și vedea problema rezolvat; relevanța față
de software-ul liber este că preocuparea personală reprezenta cea mai
des întâlnită motivație pentru inițierea unui astfel de proiect.
Și în zilele noastre tot așa pornesc majoritatea proiectelor de
software liber, dar mai puțin decât în 1997, când Raymond a scris aceste
cuvinte. Astăzi, avem fenomenul organizațiilor—inclusiv corporații
în căutare de profit—care inițiază proiecte mari, administrate
centralizat, de la zero. Programatorul singuratic, care scrie niște cod
pentru a rezolva o problemă și care, mai apoi, realizează că rezultatul
are o aplicabilitate mai mare, este încă sursa multor proiecte de software
liber dar aceasta nu mai este unica poveste.
Punctul de vedere al lui Raymond este, încă, pertinent. Condiția
esențială este ca producătorii software-ului să aiba un interes direct
în succesul acestuia, pentru că ei înșiși îl folosesc. Dacă aplicația nu
face exact ceea ce ar trebui, persoana sau organizația care o produce va
simți acest lucru în munca de zi cu zi. De exemplu, proiectul OpenAdapter
(), inițiat de bancherul
Dresdner Kleinwort Wasserstein ca o platformă open-source pentru
integrarea sistemelorde informații financiare disparate, nu se poate
spune că adresează problema individuală a vreunui programator. El rezolvă
o problemă instituțională. Dar problema aceasta apare direct din
experiențele instituției și a partenerilor ei și de aceea, dacă proiectul
nu reușește să ofere soluții, ei vor ști. Acest lucru produce software
de calitate pentru că bucla de reglaj funcționează în direcția potrivită.
Programul nu se scrie pentru a fi vândut altcuiva care să își rezolve
problema. Este scris pentru a rezolva o problemă proprie
și apoi distribuit altora, la fel ca și când problema ar fi
o boală iar aplicația medicamentul a cărui distribuție vrea să elimine
complet epidemia.
Capitolul acesta discută cum să prezinți o aplicație liberă nouă
lumii dar multe dintre recomandările lui pot să pară cunoscute unei
organizații de sănătate care distribuie medicamente. Scopurile sunt
asemănătoare: Vrei să fie clar ce face medicamentul, să ajungă în mâinile
oamenilor potriviți și să fii sigur că persoanele care îl vor primi știu
cum să îl folosească. În cazul software-ului, vrei de asemenea să atragi
unii dintre cei care îl primesc în activitatea de cercetare pentru a
îmbunătăți medicamentul.
Distribuirea de software gratuit e o problemă cu două tăișuri.
Aplicația trebuie să strângă utilizatori și dezvoltatori. Aceste două
nevoi nu se află neapărat în conflict dar adaugă puțină complexitate
modului de prezentare inițială a proiectului. O parte a informației
e utilă pentru amândouă mediile, o altă parte doar pentru unul dintre ele.
Amândouă tipurile de informație trebuie să subscrie principiului unei
prezentări scalate; mai precis, gradul de detaliu prezentat în fiecare
etapă trebuie să corespundă în mod direct timpului și efortului depus
de cititor. Efortul mai mare trebuie să corespundă recompensei mai mari.
Când cele două nu sunt corelate îndeaproape, oamenii își pierd
repede credința și nu mai depun efort.
Corolarul este că aparențele contează.
Programatorii, în special, nu vor să creadă acest lucru de multe ori.
Dragostea lor de fond peste formă este aproape un punct de mândrie
profesională. Nu e accidental faptul că atât de mulți programatori au
o antipatie față de marketing și relații publice, nici că designerii
profesioniști sunt, de multe ori, oripilați de ceea ce creează
programatorii pe cont propriu.
E de regretat acest lucru pentru că există situații în care forma
este și fond, iar prezentarea proiectului este una
dintre ele. De exemplu, primul lucru pe care îl află un vizitator
despre un proiect este cum arată site-ul web. Informația aceasta
e absorbită înainte ca orice parte din conținutul site-ului
să fie înțeles—înainte să se fi citit vreun text sau să se fi
dat click pe un link. Oricât de nedrept ar putea să pară, oamenii nu se
pot abține de la a-și forma o primă impresie imediat. Aspectul site-ului
arată dacă s-a realizat prezentarea proiectului cu grijă. Majoritatea
putem să ne dăm seama din prima dacă un site a fost creat în grabă sau
a fost gândit cu atenție. Asta este prima informație pe care proiectul
vostru o oferă și impresia pe care o creează se va transfera mai apoi
restului proiectului prin asociație.
Astfel, în vreme ce o mare parte din acest capitol vorbește de
conținutul cu care trebuie să înceapă proiectul vostru, trebuie să
vă amintiți și că aspectul acestuia contează. Pentru că site-ul
proiectului trebuie să funcționeze pentru două tipuri diferite de
vizitatori—utilizatori și dezvoltatori—trebuie acordată multă
atenție clarității și francheții. Deși nu este locul potrivit pentru un
tratat general despre design-ul de pagini web, un principiu e destul
de important pentru a merita să fie menționat, în special când site-ul
servește mai multor audiențe (poate suprapuse): oamenii trebuie să aibă
o idee despre unde îi va duce un link înainte de a da click pe el. De
exemplu, trebuie să fie evident doar privind link-ul
către documentația pentru utilizatori că el duce către
documentația pentru utilizatori și nu către cea pentru dezvoltatori.
Conducerea unui proiect înseamnă, pe de-o parte, furnizarea de informații
dar și asigurarea comfortului. Simpla prezență a anumitor oferte
standard, în locurile așteptate, dă asigurări utilizatorilor și
dezvoltatorilor care se gândesc dacă să se implice. Spune faptul că
acest proiect e bine organizat, a anticipat întrebările pe care
oamenii le vor pune, și a făcut un efort pentru a răspunde la ele
într-un mod care să necesite un efort minim din partea celui care
întreabă. Emanând această aură de pregătire, proiectul trimite un mesaj:
„Timpul vostru nu va fi irosit dacă vă implicați”, care e exact ceea
ce vor oamenii să audă.
Dar, prima dată, privește în jur
Înainte de a începe un proiect open-source, trebuie făcut un lucru
important:
Întotdeauna uitați-vă dacă nu există un proiect care să facă
exact ceea ce vreți. Șansele sunt destul de mari ca, oricare ar fi
problema pe care o vreți rezolvată acum, altcineva s-o fi rezolvat-o
înainte. Dacă au rezolvat-o și au distribuit și codul cu o licență liberă,
atunci nu există niciun motiv pentru a reinventa roata astăzi. Există,
desigur, și excepții: dacă vreți să porniți un proiect ca pe o experiență
educațională, codul pre-existent nu vă va ajuta; poate că proiectul la
care vă gândiți e atât de specializat încât nu există nicio șansă ca
oricine altcineva să o fi facut-o. Dar, în general, nu există nici un
sens în a nu căuta și recompensa poate fi mare. Dacă motoarele normale
de căutare pe Internet nu returnează nimic, încercați să căutați pe:
(un site de știri legate de
proiecte open-source, despre care se va discuta mai mult mai încolo), pe
și în directorul de software
liber al Fundației pentru Software Liber la adresa:
.
Chiar dacă nu găsești exact ceea ce cauți, s-ar putea să
găsești ceva atât de apropiat încât să aibă sens să te alături
proiectului și să adaugi funcționalitate decât să începi de la zero
de unul singur.
Cum să începi cu ce există deja
Te-ai uitat în jur, ai văzut că nimic din ce există nu se
potrivește nevoilor tale, și ai decis să inițiezi un proiect nou.
Ce faci acum?
Cea mai grea parte când lansezi un proiect de software liber e
să transformi o viziune privată într-una publică. Tu sau organizația ta
poti să știi foarte bine ceea ce vrei dar exprimarea acestui scop
într-un mod comprehensibil lumii necesită un volum apreciabil de lucru.
Cu toate acestea, e esențial să asiguri timpul necesar pentru a o face.
Tu și ceilalți fondatori trebuie să decideți la ce se referă exact
proiectul—adică să decideți care sunt limitările lui, ceea ce
nu va face precum și ceea ce va putea face—și
să scrieți o declarație a misiunii. Această parte nu e, de obicei, prea
dificilă deși poate uneori să scoată la iveală presupuneri nerostite sau
chiar neînțelegeri despre natura proiectului, ceea ce e un lucru bun:
e mai bine să le rezolvați acum decât mai târziu. Următorul pas este
de a pregăti proiectul pentru consumul public, etapă care este una
extrem de grea.
Ceea ce face această parte atât de laborioasă este faptul că ea
presupune organizarea și documentarea lucrurilor pe care toată lumea le
știe deja—„toată lumea” înseamnă toți cei care au fost implicați
în proiect până acum. Astfel, pentru oamenii care execută această muncă,
nu există niciun beneficiu imediat. Ei nu au nevoie de un fișier
README care să dea o descriere a proiectului și
nici de un document de design sau manual de utilizator. Ei nu au nevoie
de un arbore de cod bine ordonat, conform standardelor informale dar
acceptate pe scară largă ale distribuției surselor software.
Indiferent cum ar fi aranjat codul, pentru ei este în regulă pentru că
deja cunosc structura și, dacă există un cod executabil, știu și cum să
îl folosească. Nu contează, pentru ei, nici dacă presupunerile
arhitecturale fundamentale ale proiectului rămân nedocumentate; ei deja
sunt familiarizați și cu acestea.
Pe de altă parte, nou veniții au nevoie de aceste lucruri. Din
fericire, ei nu au nevoie de toate odată. Nu e nevoie să se furnizeze
toate resursele posibile înainte de a transforma proiectul în unul public.
Într-o lume perfectă, poate, fiecare proiect open-source nou și-ar
începe viața cu un document de design cuprinzător, un manual complet
pentru utilizatori (cu marcaje speciale pentru opțiunile planificate
dar încă neimplementate), cod bine și frumos împachetat, capabil să
ruleze pe orice platformă de execuție, și așa mai departe. În realitate,
rezolvarea tuturor acestor probleme ar fi un mare consumator de timp și,
oricum, e o muncă pentru care dezvoltatorii se pot aștepta și la ajutor
din partea din partea voluntarilor odată ce proiectul a început.
Ce este totuși necesar este să se
investească destul în prezentare astfel încât nou-veniții să poată trece
ușor peste obstacolul inițial al lipsei de familiaritate. Imaginați-vă
că este primul pas dintr-un proces de bootstrapping, de a aduce proiectul
la un fel de nivel minim de energie pentru activare. Am auzit oameni
numind acest prag ca și energie de hacktivare:
cantitatea de efort pe care un nou-venit trebuie să-l depună înainte de
a primi ceva în schimbul timpului lui. Cu cât nivelul acestei energii
e mai scăzut, cu atât mai bine. Prima etapă presupune aducerea acestui
nivel suficient de jos încât oamenii să fie încurajați să se implice.
Fiecare dintre următoarele subsecțiuni descrie un aspect
important al inițierii unui proiect. Ele sunt prezentate aproximativ
în ordinea în care un vizitator nou le-ar întâlni deși ordinea în care
ar fi implementate în realitate ar fi diferită. Puteți să le tratați ca
o listă de verificări. Când porniți un proiect parcurgeți lista și
asigurați-vă că fiecare aspect e tratat sau cel puțin că vă simțiți
confortabil cu consecințele potențiale dacă ați omis una dintre ele.
Alegerea unui nume bun
Puneți-vă în pantofii cuiva care tocmai a auzit despre proiect,
poate chiar în urma căutării unei aplicații care să rezolve o problemă.
Primul lucru pe care îl vor observa va fi numele proiectului.
Un nume bun nu va aduce automat succesul proiectului la fel cum
un nume rău nu-l va blestema—deși, în realitate, un nume
foarte,rău ar putea face asta, vom porni de la
presupunerea că niciunul dintre cititori nu vrea să-și facă proiectul
să eșueze. Cu toate acestea, un nume rău poate încetini rata de adopție
a proiectului, fie pentru că oamenii nu-l consideră serios, fie pentru că
pur și simplu nu pot să-l rețină.
Un nume bun:
Dă o idee despre ceea ce face proiectului sau are măcar
o legătură evidentă, astfel încât, dacă o persoană știe
numele și ceea ce face proiectul, să poată regăsi
rapid numele în memorie mai târziu.
E ușor de reținut. Nu se poate trece peste faptul că
engleza este limba standard a Internet-ului. „ușor de memorat”
înseamnă „ușor de memorat pentru o persoană care știe bine
engleză”. Numele care sunt glume dependente de pronunția
unui vorbitor nativ, de exemplu, vor fi opace pentru mulți
vorbitori nenativi de engleză. Dacă gluma este foarte
convingătoare și memorabilă, ar putea fi totuși folosită;
țineți doar minte faptul că majoritatea oamenilor care văd
numele nu și-l vor imagina în cap în același mod cum ar
face-o un vorbitor nativ.
Nu este identic cu numele altui proiect și nu încalcă
nicio marcă înregistrată. Aici nu e vorba doar de bune maniere
ci și de aspectul legal. Nu vreți să aveți parte de o
confuzie de identitate. E destul de greu să urmărești toate
proiectele care sunt disponibile pe net fără a avea
proiecte diferite care poartă același nume.
Resursele menționate anterior la
sunt utile pentru
desoperirea faptului că alt proiect are deja numele la
care vă gândiți. Căutări gratuite după mărci înregistrate
se pot face la adresele
și .
Dacă se poate, e disponibil ca un nume de domeniu în
domeniile rădăcină de genul
.com,
.net și
.org. Probabil că ar fi bine
de ales unul .org,
pentru a îl prezenta ca pagina oficială a proiectului;
celelalte două ar trebui să redirecționeze acolo și ar trebui
să existe doar pentru a preveni ca terțe părți să creeze
confuzii de identitate în jurul numelui proiectului. Chiar
dacă vreți să găzduiți proiectul la altă adresă (vezi
),
puteți să înregistrați, totuși, domenii specifice proiectului
și să le redirecționați către site-ul de găzduire. E
mai ușor pentru utilizatori să țină minte un URL simplu.
Stabiliți o declarație a misiunii clară
După ce au găsit site-ul proiectului, următorul lucru pe care
oamenii îl vor face este să caute o descriere rapidă, o declarație a
misiunii, astfel încât să decidă (în termen de 30 de secunde) dacă sunt
sau nu interesați să afle mai multe. Aceasta trebuie amplasată pe prima
pagină în mod proeminent, de preferință chiar sub numele proiectului.
Declarația scopului trebuie să fie concretă, limitatoare și, mai
presus de orice, scurtă. Acesta este un exemplu bun, de la :
De a crea, ca și o comunitate, cea mai bună suită de
produse pentru birou astfel încât aceasta să ruleze pe toate platformele
principale și să furnizeze acces la toată funcționalitatea și toate
datele prin API-uri bazate pe componente deschise și un format
al fișierelor bazat pe XML.
În doar câteva cuvinte, au nimerit toate punctele importante, în
special prin apelul la cunoștințele anterioare ale cititorului. Spunând:
"ca și o comunitate", ei semnalizează faptul că
nicio corporație nu va domina dezvoltarea; "internațional
" înseamnă că aplicația va permite oamenilor să lucreze
în mai multe limbi și cu mai multe setări locale; "toate
platformele principale " înseamnă că aceasta va fi portabilă
pe Unix, Macintosh și Windows. Restul sugerează faptul că interfețele
deschise și formatele de fișiere ușor de înțeles sunt o parte importantă
a țelului. Nu spun direct că vor să creeze o alternativă gratuită la
Microsoft Office dar majoritatea oamenilor pot să citească printre
rânduri. Deși această declarație pare largă la prima vedere, în realitate
este destul de restrânsă: cuvintele "suită de produse pentru
birou" au un înțeles foarte concret pentru cineva care este
familiarizat cu astfel de aplicații. Din nou, se presupune experiența
anterioară a cititorului (în acest caz, probabil din MS Office) pentru
a face declarația misiunii concisă.
Natura declarației misiunii depinde parțial de cel care o scrie,
nu doar de aplicația pe care o descrie. De exemplu, are sens pentru
OpenOffice.org să folosească sintagma "ca și o comunitate
", pentru că proiectul a fost inițiat, și încă este
sponsorizat în mare, de Sun Microsystems. Incluzând aceste cuvinte, Sun
indică faptul că e conștientă de grijile că ar încerca să domine
procesul de dezvoltare. În acest fel de probleme, simpla demonstrație
de conștientizare a potențialului problemei ajută
destul în evitarea problemei în întregimea ei. Pe de altă parte,
proiectele care nu sunt sponsorizate de o corporație nu au nevoie de
o astfel de sintagmă; dezvoltarea de către comunitate este lucrul
normal așa că, în mod normal, nu ar fi niciun motiv pentru care
să fie enumerat ca și parte a misiunii.
Afirmați că proiectul este liber
Cei care rămân interesați după ce au citit declarația scopului
vor vrea să vadă mai multe detalii, poate documentația pentru utilizatori
sau dezvoltatori, și, în cele din urmă, să downloadeze ceva. Dar înainte
să se întâmple oricare dintre lucrurile acestea, vor dori să știe că
sursele sunt deschise.
Prima pagină trebuie să explice clar și fără ambiguitate
că proiectul este open-source. Poate părea evident acest
lucru dar ați fi surprinși să aflați câte proiecte uită să facă asta. Am
văzut site-uri de proiecte de software liber unde prima pagină nu numai
că nu specifica sub care licență de software liber era distribuită dar
nici măcar nu menționa faptul că proiectul e liber. Uneori cea mai
importantă informație era retrogradată până la pagina de download, cea
pentru dezvoltatori sau alt loc în care era nevoie de mai mult de un
click de mouse pentru a ajunge. În cazuri extreme, licența nu apărea
nicăieri pe site—singurul mod de a o găsi era de a downloada
aplicația și de a căuta înăuntru.
Nu faceți această greșeală. O astfel de omisiune poate duce la
pierderea unor potențiali dezvoltatori și utilizatori. Publicați pe prima
pagină, chiar sub declarația scopului proiectului, că acesta este
software liber sau open-source și menționați licența exactă. Un ghid
scurt pentru alegerea licenței se găsește în
în continuarea acestui capitol, iar problemele legate de
licențiere sunt discutate în detaliu în .
În acest moment, vizitatorul nostru ipotetic a determinat—
probabil într-un minut sau mai puțin—că e interesat să petreacă, de
exemplu, încă cinci minute pentru a investiga proiectul. Următoarele
secțiuni descriu ce trebuie să descopere în acele cinci minute.
Lista de posibilități și cerințe
Ar trebui să existe o listă scurtă cu posibilitățile oferite de
software (dacă una dintre ele nu e încă terminată, ea poate fi listată
dar se pune "planificat" sau
"în curs" lângă aceasta), și genul de sistem
necesar pentru a rula software-ul. Gândiți-vă la lista de posibilități și
cerințe la fel cum ați prezenta cuiva care vă cere un rezumat scurt al
proiectului. De multe ori e doar o extindere logică a scopului declarat.
De exemplu, declarația misiunii proiectului poate fi:
De a crea un motor de indexare și căutare text cu
o interfață de programare bogată, pentru a fi folosită de programatori
în furnizarea serviciilor de căutare în seturi mari de fișiere text.
Lista de posibilități și cerințe ar da detaliile, clarificând
prezentarea scopului declarat:
Posibilități:
Caută în text simplu, HTML și XML
Căutare după cuvinte și fraze
(planificat) Căutare fuzzy
(planificat) Actualizare incrementală a indecșilor
(planificat) Indexarea paginilor web
distante
Cerințe:
Python 2.2 sau mai recent
Spațiu suficient pe disc pentru a salva
indecșii(aproximativ de două ori dimensiunea datelor
originale)
Având la dispoziție aceste informații, cititorii pot să înțeleagă
rapid dacă acest proiect are vreo șansă să îi ajute și pot lua în
calcul să contribuie și ei ca dezvoltatori.
Starea dezvoltării
Oamenii vor întotdeauna să afle în ce stadiu se află proiectul.
Pentru proiectele noi, vor să știe care e diferența dintre promisiunile
proiectului și realitatea curentă. Pentru proiectele mature, vor să știe
cât de activ sunt întreținute, cât de des apar noi versiuni, cât de rapid
se răspunde la erorile raportate, etc.
Pentru a răspunde la astfel de întrebări, trebuie să existe o
pagină pentru starea dezvoltării în care să se prezinte scopurile pe
termen scurt ale proiectului și nevoile (de exemplu, se poate să fie
nevoie de dezvoltatori cu o anumită expertiză). Pagina poate da și
informații despre versiunile anterioare, cu liste de capabilități, astfel
încât vizitatorii să înțeleagă cum definește proiectul ideea de
„progres” și cât de rapid progresează în concordanță cu acea definiție.
Să nu vă fie frică să păreți nepregătiți și nu cedați tentației
de a minți în legătură cu starea proiectului. Toată lumea știe că
aplicațiile evoluează în etape; nu e nicio rușine în a spune „aplicația
e în stadiul alpha și are bug-uri cunoscute. Rulează, și funcționează în
cea mai mare parte a timpului, dar o folosiți pe propria răspundere”.
O astfel de exprimare nu va speria dezvoltatorii de care e nevoie în
această etapă. Cât despre utilizatori, unul dintre cele mai proaste
lucruri pe care le poate face un proiect este să atragă utilizatori
înainte ca aplicația să fie pregătită pentru ei. O reputație de
de instabilitate sau probleme (bug-uri) este greu de înlocuit odată
„câștigată”. Conservatorismul are meritele lui pe termen lung;
întotdeauna e mai bine ca aplicațiaa să fie
mai stabilă decât se așteaptă utilizatorul decât
mai puțin stabilă și surprizele plăcute produc cea mai bună reputație.
Alpha și Beta
Termenul alpha reprezintă o primă
versiune, cu care utilizatorii pot să își facă treaba și care are
funcționalitatea intenționată, dar care are și bug-uri. Principalul
scop al software-ului alpha este de a genera feedback astfel încât
dezvoltatorii să știe la ce e nevoie să mai lucreze. Stadiul următor,
beta, presupune că toate problemele serioase
ale aplicației au fost rezolvate dar încă nu s-au efectuat
destule teste pentru a certifica versiunea. Scopul software-ului
beta este de a deveni versiunea oficială, dacă nu se găsesc bug-uri,
sau de a oferi feedback detaliat dezvoltatorilor astfel încât ei să
ajungă la versiunea oficială cât mai repede. Diferența dintre alpha
și beta este, în principal, una de judecată.
Download-uri
Aplicația trebuie să poată fi descărcată ca și cod sursă într-un
format standard. Când proiectul se află la început, pachetele binare
(executabile) nu sunt necesare decât dacă aplicația are cerințe sau
dependențe atât de complicate pentru a fi transformată în executabil
încât ar fi prea greu pentru majoritatea oamenilor să o facă să
ruleze. (Dacă aceasta e situația, proiectul va avea probleme
serioase în a atrage dezvoltatori orice-ar fi).
Mecanismul de distribuție trebuie să fie cât mai convenabil,
standardizat și simplu. Dacă ați încerca să eliminați o boală, nu ați
distribui medicamentul într-un așa fel încât ar fi nevoie de o
dimensiune non-standard de seringă pentru a-l administra. La fel,
aplicația trebuie să fie conformă cu metodele de compilare și instalare
standard; cu cât deviază mai mult de la standarde, cu atât vor renunța
mai ușor potențialii dezvoltatori și utilizatori și vor pleca.
Deși sună evident, majoritatea proiectelor nu se obosesc să
standardizeze procedurile de instalare până la o etapă foarte
târzie, spunându-și că pot să facă asta oricând: "O să
rezolvăm toate problemele astea când codul va fi mai aproape de a fi
gata."Ceea ce nu realizează e că, amânând munca plictisitoare
de a termina procedurile pentru compilare și instalare, ei de fapt
prelungesc durata de care e nevoie pentru a termina—pentru că
ei descurajează dezvoltatorii care altfel ar fi putut contribui la
cod. Mai grav de-atât, ei nu știu că pierd toți
acești dezvoltatori pentru că procesul este o acumulare de
non-evenimente: cineva vizitează site-ul, downloadează aplicația,
încearcă să o folosească, nu reușește, renunță și merge mai departe. Cine
va ști vreodată că s-a întâmplat în afară de acea persoană? Nimeni care
lucrează la proiect nu va realiza interesul acelei persoane și un
lucru bun va fi irosit în mod tacit.
Munca plictisitoare care poate aduce câștiguri mari ar trebui
să fie făcută întotdeauna devreme și reducerea semnificativă a barierelor
în calea celor care vor să se alăture proiectului aduce câștiguri mari.
Când creați un pachet binar downloadabil, e vital să dați un număr
unic de versiune astfel încât oamenii să poată compara două versiuni
diferite și să știe care dintre ele e mai recentă. O discuție detaliată
a modului în care se dau numerele de versiune apare în , iar detaliile despre standardizarea
procedurilor de compilare și instalare sunt prezentate în
, amândouă regăsite
în .
Version Control and Bug Tracker Access
Downloading source packages is fine for those who just want to
install and use the software, but it's not enough for those who want
to debug or add new features. Nightly source snapshots can help, but
they're still not fine-grained enough for a thriving development
community. People need real-time access to the latest sources, and
the way to give them that is to use a version control system. The
presence of anonymously accessible version controlled sources is a
sign—to both users and developers—that this project is
making an effort to give people what they need to participate. If you
can't offer version control right away, then put up a sign saying you
intend to set it up soon. Version control infrastructure is discussed
in detail in in
.
The same goes for the project's bug tracker. The importance of
a bug tracking system lies not only in its usefulness to developers,
but in what it signifies for project observers. For many people, an
accessible bug database is one of the strongest signs that a project
should be taken seriously. Furthermore, the higher the number of bugs
in the database, the better the project looks. This might seem
counterintuitive, but remember that the number of bugs recorded really
depends on three things: the absolute number of bugs present in the
software, the number of users using the software, and the convenience
with which those users can register new bugs. Of these three factors,
the latter two are more significant than the first. Any software of
sufficient size and complexity has an essentially arbitrary number of
bugs waiting to be discovered. The real question is, how well will
the project do at recording and prioritizing those bugs? A project
with a large and well-maintained bug database (meaning bugs are
responded to promptly, duplicate bugs are unified, etc.) therefore
makes a better impression than a project with no bug database, or a
nearly empty database.
Of course, if your project is just getting started, then the bug
database will contain very few bugs, and there's not much you can do
about that. But if the status page emphasizes the project's youth,
and if people looking at the bug database can see that most filings have
taken place recently, they can extrapolate from that that the project
still has a healthy rate of filings, and they
will not be unduly alarmed by the low absolute number of bugs
recorded.
Note that bug trackers are often used to track not only software
bugs, but enhancement requests, documentation changes, pending tasks,
and more. The details of running a bug tracker are covered in
in
, so I won't
go into them here. The important thing from a presentation point of
view is just to have a bug tracker, and to make
sure that fact is visible from the front page of the project.
Communications Channels
Visitors usually want to know how to reach the human beings
involved with the project. Provide the addresses of mailing lists,
chat rooms, and IRC channels, and any other forums where others
involved with the software can be reached. Make it clear that you and
the other authors of the project are subscribed to these mailing
lists, so people see there's a way to give feedback that will reach
the developers. Your presence on the lists does not imply a
committment to answer all questions or implement all feature requests.
In the long run, most users will probably never join the forums
anyway, but they will be comforted to know that they
could if they ever needed to.
In the early stages of a project, there's no need to have
separate user and developer forums. It's much better to have everyone
involved with the software talking together, in one "room." Among
early adopters, the distinction between developer and user is often
fuzzy; to the extent that the distinction can be made, the ratio of
developers to users is usually much higher in the early days of the
project than later on. While you can't assume that every early
adopter is a programmer who wants to hack on the software, you can
assume that they are at least interested in following development
discussions and in getting a sense of the project's direction.
As this chapter is only about getting a project started, it's
enough merely to say that these communications forums need to exist.
Later, in in
, we'll examine where
and how to set up such forums, the ways in which they might need
moderation or other management, and how to separate user forums from
developer forums, when the time comes, without creating an
unbridgeable gulf.
Developer Guidelines
If someone is considering contributing to the project, she'll
look for developer guidelines. Developer guidelines are not so much
technical as social: they explain how the developers interact with
each other and with the users, and ultimately how things get
done.
This topic is covered in detail in
in
, but the basic
elements of developer guidelines are:
pointers to forums for interaction with other
developers
instructions on how to report bugs and submit
patches
some indication of how
development is usually done—is the project a
benevolent dictatorship, a democracy, or something
else
No pejorative sense is intended by "dictatorship", by the way. It's
perfectly okay to run a tyranny where one particular developer has
veto power over all changes. Many successful projects work this way.
The important thing is that the project come right out and say so. A
tyranny pretending to be a democracy will turn people off; a tyranny
that says it's a tyranny will do fine as long as the tyrant is
competent and trusted.
See
for an example of particularly thorough developer guidelines, or
for
broader guidelines that focus more on governance and the spirit of
participation and less on technical matters.
The separate issue of providing a programmer's introduction to
the software is discussed in
later in this chapter.
Documentation
Documentation is essential. There needs to be
something for people to read, even if it's
rudimentary and incomplete. This falls squarely into the "drudgery"
category referred to earlier, and is often the first area where a new
open source project falls down. Coming up with a mission statement
and feature list, choosing a license, summarizing development
status—these are all relatively small tasks, which can be
definitively completed and usually need not be returned to once done.
Documentation, on the other hand, is never really finished, which may
be one reason people sometimes delay starting it at all.
The most insidious thing is that documentation's utility to
those writing it is the reverse of its utility to those who will read
it. The most important documentation for initial users is the basics:
how to quickly set up the software, an overview of how it works,
perhaps some guides to doing common tasks. Yet these are exactly the
things the writers of the documentation know all
too well—so well that it can be difficult for them to see
things from the reader's point of view, and to laboriously spell out
the steps that (to the writers) seem so obvious as to be unworthy of
mention.
There's no magic solution to this problem. Someone just needs
to sit down and write the stuff, and then run it by typical new users
to test its quality. Use a simple, easy-to-edit format such as HTML,
plain text, Texinfo, or some variant of XML—something that's
convenient for lightweight, quick improvements on the spur of the
moment. This is not only to remove any overhead that might impede the
original writers from making incremental improvements, but also for
those who join the project later and want to work on the
documentation.
One way to ensure basic initial documentation gets done is to
limit its scope in advance. That way, writing it at least won't feel
like an open-ended task. A good rule of thumb is that it should meet
the following minimal criteria:
Tell the reader clearly how much technical
expertise they're expected to have.
Describe clearly and thoroughly how to set up
the software, and somewhere near the beginning of the
documentation, tell the user how to run some sort of
diagnostic test or simple command to confirm that
they've set things up correctly. Startup
documentation is in some ways more important than
actual usage documentation. The more effort someone has
invested in installing and getting started with the
software, the more persistent she'll be in figuring out
advanced functionality that's not well-documented.
When people abandon, they abandon early; therefore,
it's the earliest stages, like installation, that need
the most support.
Give one tutorial-style example of how to do a
common task. Obviously, many examples for many tasks
would be even better, but if time is limited, pick one
task and walk through it thoroughly. Once someone
sees that the software can be
used for one thing, they'll start to explore what else
it can do on their own—and, if you're lucky,
start filling in the documentation themselves. Which
brings us to the next point...
Label the areas where the documentation is known
to be incomplete. By showing the readers that you are
aware of its deficiencies, you align yourself with
their point of view. Your empathy reassures them that
they don't face a struggle to convince the project of
what's important. These labels needn't represent
promises to fill in the gaps by any particular date
—it's equally legitimate to treat them as open
requests for volunteer help.
The last point is of wider importance, actually, and can be
applied to the entire project, not just the documentation. An
accurate accounting of known deficiencies is the norm in the open
source world. You don't have to exaggerate the project's
shortcomings, just identify them scrupulously and dispassionately when
the context calls for it (whether in the documentation, in the bug
tracking database, or on a mailing list discussion). No one will
treat this as defeatism on the part of the project, nor as a
commitment to solve the problems by a certain date, unless the project
makes such a commitment explicitly. Since anyone who uses the
software will discover the deficiencies for themselves, it's much
better for them to be psychologically prepared—then the
project will look like it has a solid knowledge of how it's
doing.
Maintaining a FAQ
A FAQ ("Frequently Asked Questions"
document) can be one of the best investments a project makes in
terms of educational payoff. FAQs are highly tuned to the questions
users and developers actually ask—as opposed to the questions
you might have expected them to ask—and
therefore, a well-maintained FAQ tends to give those who consult it
exactly what they're looking for. The FAQ is often the first place
users look when they encounter a problem, often even in preference
to the official manual, and it's probably the document in your
project most likely to be linked to from other sites.
Unfortunately, you cannot make the FAQ at the start of the
project. Good FAQs are not written, they are grown. They are by
definition reactive documents, evolving over time in response to
people's day-to-day usage of the software. Since it's impossible to
correctly anticipate the questions people will ask, it is impossible
to sit down and write a useful FAQ from scratch.
Therefore, don't waste your time trying to. You may, however,
find it useful to set up a mostly blank FAQ template, so there will
be an obvious place for people to contribute questions and answers
after the project is under way. At this stage, the most important
property is not completeness, but convenience: if the FAQ is easy to
add to, people will add to it. (Proper FAQ maintenance is a
non-trivial and intriguing problem, and is discussed more in in
.)
Availability of documentation
Documentation should be available from two places: online
(directly from the web site), and in the
downloadable distribution of the software (see
in
). It needs to be
online, in browsable form, because people often read documentation
before downloading software for the first time,
as a way of helping them decide whether to download at all. But it
should also accompany the software, on the principle that downloading
should supply (i.e., make locally accessible) everything one needs to
use the package.
For online documentation, make sure that there is a link that
brings up the entire documentation in one HTML
page (put a note like "monolithic" or "all-in-one" or "single large
page" next to the link, so people know that it might take a while to
load). This is useful because people often want to search for a
specific word or phrase across the entire documentation. Generally,
they already know what they're looking for; they just can't remember
what section it's in. For such people, nothing is more frustrating
than encountering one HTML page for the table of contents, then a
different page for the introduction, then a different page for
installation instructions, etc. When the pages are broken up like
that, their browser's search function is useless. The separate-page
style is useful for those who already know what section they need, or
who want to read the entire documentation from front to back in
sequence. But this is not the most common way
documentation is accessed. Far more often, someone who is basically
familiar with the software is coming back to search for a specific
word or phrase. To fail to provide them with a single, searchable
document would only make their lives harder.
Developer documentation
Developer documentation is written to help programmers
understand the code, so they can repair and extend it. This is
somewhat different from the developer guidelines
discussed earlier, which are more social than technical. Developer
guidelines tell programmers how to get along with each other;
developer documentation tells them how to get along with the code
itself. The two are often packaged together in one document for
convenience (as with the example given
earlier), but they don't have to be.
Although developer documentation can be very helpful, there's no
reason to delay a release to do it. As long as the original authors
are available (and willing) to answer questions about the code, that's
enough to start with. In fact, having to answer the same questions
over and over is a common motivation for writing documentation. But
even before it's written, determined contributors will still manage to
find their way around the code. The force that drives people to spend
time learning a code base is that the code does something useful for
them. If people have faith in that, they will take the time to figure
things out; if they don't have that faith, no amount of developer
documentation will get or keep them.
So if you have time to write documentation for only one
audience, write it for users. All user documentation is, in effect,
developer documentation as well; any programmer who's going to work on
a piece of software will need to be familiar with how to use it.
Later, when you see programmers asking the same questions over and
over, take the time to write up some separate documents just for
them.
Some projects use wikis for their initial documentation, or even
as their primary documentation. In my experience, this really only
works if the wiki is actively edited by a few people who agree on how
the documentation is to be organized and what sort of "voice" it
should have. See
in
for
more.
Example Output and Screenshots
If the project involves a graphical user interface, or if it
produces graphical or otherwise distinctive output, put some samples
up on the project web site. In the case of interface, this means
screenshots; for output, it might be screenshots or just files. Both
cater to people's need for instant gratification: a single screenshot
can be more convincing than paragraphs of descriptive text and mailing
list chatter, because a screenshot is inarguable proof that the
software works. It may be buggy, it may be hard
to install, it may be incompletely documented, but that screenshot is
still proof that if one puts in enough effort, one can get it to
run.
Screenshots
Since screenshots can be daunting until you've actually made a
few, here are basic instructions for making them. Using the Gimp
(), open
File->Acquire->Screenshot,
choose Single Window or
Whole Screen, then click
OK. Now your next mouse click will
capture the window or screen clicked on as an image in the Gimp.
Crop and resize the image as necessary, using the instructions at
.
There are many other things you could put on the project web
site, if you have the time, or if for one reason or another they are
especially appropriate: a news page, a project history page, a related
links page, a site-search feature, a donations link, etc. None of
these are necessities at startup time, but keep them in mind for the
future.
Canned Hosting
There are a few sites that provide free hosting and
infrastructure for open source projects: a web area, version control,
a bug tracker, a download area, chat forums, regular backups, etc.
The details vary from site to site, but the same basic services are
offered at all of them. By using one of these sites, you get a lot
for free; what you give up, obviously, is fine-grained control over
the user experience. The hosting service decides what software the
site runs, and may control or at least influence the look and feel of
the project's web pages.
See
in
for a more
detailed discussion of the advantages and disadvantages of canned
hosting, and a list of sites that offer it.
Choosing a License and Applying It
This section is intended to be a very quick, very rough guide to
choosing a license. Read to understand
the detailed legal implications of the different licenses, and how the
license you choose can affect people's ability to mix your software
with other free software.
There are a great many free software licenses to choose from.
Most of them we needn't consider here, as they were written to satisfy
the particular legal needs of some corporation or person, and wouldn't
be appropriate for your project. We will restrict ourselves to just
the most commonly used licenses; in most cases, you will want to
choose one of them.
The "Do Anything" Licenses
If you're comfortable with your project's code potentially being
used in proprietary programs, then use
an MIT/X-style license. It is the simplest of
several minimal licenses that do little more than assert nominal
copyright (without actually restricting copying) and specify that the
code comes with no warranty. See
for details.
The GPL
If you don't want your code to be used in proprietary programs,
use the GNU General Public License
(). The GPL is
probably the most widely recognized free software license in the world
today. This is in itself a big advantage, since many potential users
and contributors will already be familiar with it, and therefore won't
have to spend extra time to read and understand your license. See
in for details.
How to Apply a License to Your Software
Once you've chosen a license, you should state it on the
project's front page. You don't need to include the actual text of
the license there; just give the name of the license, and make it link
to the full license text on another page.
This tells the public what license you
intend the software to be released under, but
it's not sufficient for legal purposes. For that, the software itself
must contain the license. The standard way to do this is to put the
full license text in a file called COPYING (or
LICENSE), and then put a short notice at the top
of each source file, naming the copyright date, holder, and license,
and saying where to find the full text of the license.
There are many variations on this pattern, so we'll look at just
one example here. The GNU GPL says to put a notice like this at the
top of each source file:
Copyright (C) <year> <name of author>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
It does not say specifically that the copy of the license you
received along with the program is in the file
COPYING, but that's where it's usually put. (You
could change the above notice to state that directly.) This template
also gives a geographical address from which to request a copy of the
license. Another common method is to give a link to a web page
containing the license. Just use your judgement and point to wherever
you feel the most permanent copy of the license is maintained, which
might simply be somewhere on your project's web site. In general, the
notice you put in each source file does not have to look exactly like
the one above, as long as it starts with the same notice of copyright
holder and date, states the name of the license, and makes it clear
where to view the full license.
Setting the Tone
So far we've covered one-time tasks you do during project setup:
picking a license, arranging the initial web site, etc. But the most
important aspects of starting a new project are dynamic. Choosing a
mailing list address is easy; ensuring that the list's conversations
remain on-topic and productive is another matter entirely. If the
project is being opened up after years of closed, in-house
development, its development processes will change, and you will have
to prepare the existing developers for that change.
The first steps are the hardest, because precedents and
expectations for future conduct have not yet been set. Stability in a
project does not come from formal policies, but from a shared,
hard-to-pin-down collective wisdom that develops over time. There are
often written rules as well, but they tend to be essentially a
distillation of the intangible, ever-evolving agreements that really
guide the project. The written policies do not define the project's
culture so much as describe it, and even then only
approximately.
There are a few reasons why things work out this way. Growth
and high turnover are not as damaging to the accumulation of social
norms as one might think. As long as change does not happen
too quickly, there is time for new arrivals to
learn how things are done, and after they learn, they will help
reinforce those ways themselves. Consider how children's songs
survive the centuries. There are children today singing roughly the
same rhymes as children did hundreds of years ago, even though there
are no children alive now who were alive then. Younger children hear
the songs sung by older ones, and when they are older, they in turn
will sing them in front of other younger ones. The children are not
engaging in a conscious program of transmission, of course, but the
reason the songs survive is nonetheless that they are transmitted
regularly and repeatedly. The time scale of free software projects
may not be measured in centuries (we don't know yet), but the dynamics
of transmission are much the same. The turnover rate is faster,
however, and must be compensated for by a more active and deliberate
transmission effort.
This effort is aided by the fact that people generally show up
expecting and looking for social norms. That's just how humans are
built. In any group unified by a common endeavor, people who join
instinctively search for behaviors that will mark them as part of the
group. The goal of setting precedents early is to make those
"in-group" behaviors be ones that are useful to the project; for once
established, they will be largely self-perpetuating.
Following are some examples of specific things you can do to set
good precedents. They're not meant as an exhaustive list, just as
illustrations of the idea that setting a collaborative mood early
helps a project tremendously. Physically, every developer may be
working alone in a room by themselves, but you can do a lot to make
them feel like they're all working together in
the same room. The more they feel this way, the more time they'll
want to spend on the project. I chose these particular examples
because they came up in the Subversion project (),
which I participated in and observed from its very beginning. But
they're not unique to Subversion; situations like these will come up
in most open source projects, and should be seen as opportunities to
start things off on the right foot.
Avoid Private Discussions
Even after you've taken the project public, you and the other
founders will often find yourselves wanting to settle difficult
questions by private communications among an inner circle. This is
especially true in the early days of the project, when there are so
many important decisions to make, and, usually, few volunteers
qualified to make them. All the obvious disadvantages of public list
discussions will loom palpably in front of you: the delay inherent in
email conversations, the need to leave sufficient time for consensus
to form, the hassle of dealing with naive volunteers who think they
understand all the issues but actually don't (every project has these;
sometimes they're next year's star contributors, sometimes they stay
naive forever), the person who can't understand why you only want to
solve problem X when it's obviously a subset of larger problem Y, and
so on. The temptation to make decisions behind closed doors and
present them as faits accomplis, or at
least as the firm recommendations of a united and influential voting
block, will be great indeed.
Don't do it.
As slow and cumbersome as public discussions can be, they're
almost always preferable in the long run. Making important decisions
in private is like spraying contributor repellant on your project. No
serious volunteer would stick around for long in an environment where
a secret council makes all the big decisions. Furthermore, public
discussion has beneficial side effects that will last beyond whatever
ephemeral technical question was at issue:
The discussion will help train and educate new developers.
You never know how many eyes are watching the conversation;
even if most people don't participate, many may be tracking
silently, gleaning information about the software.
The discussion will train you in the art
of explaining technical issues to people who are not as
familiar with the software as you are. This is a skill that
requires practice, and you can't get that practice by talking
to people who already know what you know.
The discussion and its conclusions will be available in public
archives forever after, enabling future discussions to avoid
retracing the same steps. See
in .
Finally, there is the possibility that someone on the list may
make a real contribution to the conversation, by coming up with an
idea you never anticipated. It's hard to say how likely this is; it
just depends on the complexity of the code and degree of
specialization required. But if anecdotal evidence may be permitted,
I would hazard that this is more likely than one would intuitively
expect. In the Subversion project, we (the founders) believed we
faced a deep and complex set of problems, which we had been thinking
about hard for several months, and we frankly doubted that anyone on
the newly created mailing list was likely to make a real contribution
to the discussion. So we took the lazy route and started batting some
technical ideas back and forth in private emails, until an observer of
the projectWe haven't gotten to the section on
crediting yet, but just to practice what I'll later preach: the
observer's name was Brian Behlendorf, and it was he who pointed out
the general importance of keeping all discussions public unless there
was a specific need for privacy. caught wind of what
was happening and asked for the discussion to be moved to the public
list. Rolling our eyes a bit, we did—and were stunned by the
number of insightful comments and suggestions that quickly resulted.
In many cases people offered ideas that had never even occurred to us.
It turned out there were some very smart people
on that list; they'd just been waiting for the right bait. It's true
that the ensuing discussions took longer than they would have if we
had kept the conversation private, but they were so much more
productive that it was well worth the extra time.
Without descending into hand-waving generalizations like "the
group is always smarter than the individual" (we've all met enough
groups to know better), it must be acknowledged that there are certain
activities at which groups excel. Massive peer review is one of them;
generating large numbers of ideas quickly is another. The quality of
the ideas depends on the quality of the thinking that went into them,
of course, but you won't know what kinds of thinkers are out there
until you stimulate them with a challenging problem.
Naturally, there are some discussions that must be had
privately; throughout this book we'll see examples of those. But the
guiding principle should always be: If there's no reason for
it to be private, it should be public.
Making this happen requires action. It's not enough merely to
ensure that all your own posts go to the public list. You also have
to nudge other people's unnecessarily private conversations to the
list too. If someone tries to start a private discussion, and there's
no reason for it to be private, then it is incumbent on you to open
the appropriate meta-discussion immediately. Don't even comment on
the original topic until you've either successfully steered the
conversation to a public place, or ascertained that privacy really was
needed. If you do this consistently, people will catch on pretty
quickly and start to use the public forums by default.
Nip Rudeness in the Bud
From the very start of your project's public existence, you
should maintain a zero-tolerance policy toward rude or insulting
behavior in its forums. Zero-tolerance does not mean technical
enforcement per se. You don't have to remove people from the mailing
list when they flame another subscriber, or take away their commit
access because they made derogatory comments. (In theory, you might
eventually have to resort to such actions, but only after all other
avenues have failed—which, by definition, isn't the case at the
start of the project.) Zero-tolerance simply means never letting bad
behavior slide by unnoticed. For example, when someone posts a
technical comment mixed together with an ad
hominem attack on some other developer in the project,
it is imperative that your response address the ad
hominem attack first, as a
separate issue unto itself, and only afterward move on to the
technical content.
It is unfortunately very easy, and all too typical, for
constructive discussions to lapse into destructive flame wars.
People will say things in email that they would never say
face-to-face. The topics of discussion only amplify this effect: in
technical issues, people often feel there is a single right answer to
most questions, and that disagreement with that answer can only be
explained by ignorance or stupidity. It's a short distance from
calling someone's technical proposal stupid to calling the person
themselves stupid. In fact, it's often hard to tell where technical
debate leaves off and character attack begins, which is one reason why
drastic responses or punishments are not a good idea. Instead, when
you think you see it happening, make a post that stresses the
importance of keeping the discussion friendly, without accusing anyone
of being deliberately poisonous. Such "Nice Police" posts do have an
unfortunate tendency to sound like a kindergarten teacher lecturing a
class on good behavior:
First, let's please cut down on the
(potentially) ad hominem comments; for example, calling J's
design for the security layer "naive and ignorant of the basic
principles of computer security." That may be true or it may
not, but in either case it's no way to have the discussion. J
made his proposal in good faith. If it has deficiencies, point
them out, and we'll fix them or get a new design. I'm sure M
meant no personal insult to J, but the phrasing was unfortunate,
and we try to keep things constructive around here.
Now, on to the proposal. I think M was right
in saying that...
As stilted as such responses sound, they have a noticeable
effect. If you consistently call out bad behavior, but don't demand
an apology or acknowledgment from the offending party, then you leave
people free to cool down and show their better side by behaving more
decorously next time—and they will. One of the secrets of
doing this successfully is to never make the meta-discussion the main
topic. It should always be an aside, a brief preface to the main
portion of your response. Point out in passing that "we don't do
things that way around here," but then move on to the real content, so
that you're giving people something on-topic to respond to. If
someone protests that they didn't deserve your rebuke, simply refuse
to be drawn into an argument about it. Either don't respond (if you
think they're just letting off steam and don't require a response), or
say you're sorry if you overreacted and that it's hard to detect
nuance in email, then get back to the main topic. Never, ever insist
on an acknowledgment, whether public or private, from someone that
they behaved inappropriately. If they choose of their own volition to
post an apology, that's great, but demanding that they do so will only
cause resentment.
The overall goal is to make good etiquette be seen as one of the
"in-group" behaviors. This helps the project, because developers can
be driven away (even from projects they like and want to support) by
flame wars. You may not even know that they were driven away; someone
might lurk on the mailing list, see that it takes a thick skin to
participate in the project, and decide against getting involved at
all. Keeping forums friendly is a long-term survival strategy, and
it's easier to do when the project is still small. Once it's part of
the culture, you won't have to be the only person promoting it. It
will be maintained by everyone.
Practice Conspicuous Code Review
One of the best ways to foster a productive development
community is to get people looking at each others' code. Some
technical infrastructure is required to do this effectively—in
particular, commit emails must be turned on; see
for more details. The effect of
commit emails is that every time someone commits a change to the
source code, an email goes out showing the log message and diffs for
the change (see , in
). Code review
is the practice of reviewing commit emails as they come in, looking
for bugs and possible improvements.This is how code
review is usually done in open source projects, at any rate. In more
centralized projects, "code review" can also mean multiple people
sitting down together and going over printouts of source code, looking
for specific problems and patterns.
Code review serves several purposes simultaneously. It's the
most obvious example of peer review in the open source world, and
directly helps to maintain software quality. Every bug that ships in
a piece of software got there by being committed and not detected;
therefore, the more eyes watch commits, the fewer bugs will ship. But
code review also serves an indirect purpose: it confirms to people
that what they do matters, because one obviously wouldn't take time to
review a commit unless one cared about its effect. People do their
best work when they know that others will take the time to evaluate
it.
Reviews should be public. Even on occasions when I have been
sitting in the same physical room with developers, and one of us has
made a commit, we take care not to do the review verbally in the room,
but to send it to the development mailing list instead. Everyone
benefits from seeing the review happen. People follow the commentary
and sometimes find flaws in it, and even when they don't, it still
reminds them that review is an expected, regular activity, like
washing the dishes or mowing the lawn.
In the Subversion project, we did not at first make a regular
practice of code review. There was no guarantee that every commit
would be reviewed, though one might sometimes look over a change if
one was particularly interested in that area of the code. Bugs
slipped in that really could and should have been caught. A developer
named Greg Stein, who knew the value of code review from past work,
decided that he was going to set an example by reviewing every line of
every single commit that went into the code
repository. Each commit anyone made was soon followed by an email to
the developer's list from Greg, dissecting the commit, analyzing
possible problems, and occasionally praising a clever bit of code. Right
away, he was catching bugs and non-optimal coding practices that would
otherwise have slipped by without ever being noticed. Pointedly, he
never complained about being the only person reviewing every commit,
even though it took a fair amount of his time, but he did sing the
praises of code review whenever he had the chance. Pretty soon, other
people, myself included, started reviewing commits regularly too.
What was our motivation? It wasn't that Greg had consciously shamed
us into it. But he had proven that reviewing code was a valuable way
to spend time, and that one could contribute as much to the project by
reviewing others' changes as by writing new code. Once he
demonstrated that, it became expected behavior, to the point where any
commit that didn't get some reaction would cause the committer to
worry, and even ask on the list whether anyone had had a chance to
review it yet. Later, Greg got a job that didn't leave him as much
time for Subversion, and had to stop doing regular reviews. But by
then, the habit was so ingrained for the rest of us as to seem that it
had been going on since time immemorial.
Start doing reviews from very first commit. The sorts of
problems that are easiest to catch by reviewing diffs are security
vulnerabilities, memory leaks, insufficient comments or API
documentation, off-by-one errors, caller/callee discipline mismatches,
and other problems that require a minimum of surrounding context to
spot. However, even larger-scale issues such as failure to abstract
repeated patterns to a single location become spottable after one has
been doing reviews regularly, because the memory of past diffs informs
the review of present diffs.
Don't worry that you might not find anything to comment on, or
that you don't know enough about every area of the code. There will
usually be something to say about almost every commit; even where you
don't find anything to question, you may find something to praise.
The important thing is to make it clear to every committer that what
they do is seen and understood. Of course, code review does not
absolve programmers of the responsibility to review and test their
changes before committing; no one should depend on code review to
catch things he ought to have caught on his own.
When Opening a Formerly Closed Project, be Sensitive to the
Magnitude of the Change
If you're opening up an existing project, one that already has
active developers accustomed to working in a closed-source
environment, make sure everyone understands that a big change is
coming—and make sure that you understand how it's going to
feel from their point of view.
Try to imagine how the situation looks to them: formerly, all
code and design decisions were made with a group of other programmers
who knew the software more or less equally well, who all received the
same pressures from the same management, and who all know each others'
strengths and weaknesses. Now you're asking them to expose their code
to the scrutiny of random strangers, who will form judgements based
only on the code, with no awareness of what business pressures may
have forced certain decisions. These strangers will ask lots of
questions, questions that jolt the existing developers into realizing
that the documentation they slaved so hard over is
still inadequate (this is inevitable). To top it
all off, the newcomers are unknown, faceless entities. If one of your
developers already feels insecure about his skills, imagine how that
will be exacerbated when newcomers point out flaws in code he wrote,
and worse, do so in front of his colleagues. Unless you have a team
of perfect coders, this is unavoidable—in fact, it will probably
happen to all of them at first. This is not because they're bad
programmers; it's just that any program above a certain size has bugs,
and peer review will spot some of those bugs (see
earlier
in this chapter). At the same time, the newcomers
themselves won't be subject to much peer review at first, since they
can't contribute code until they're more familiar with the project.
To your developers, it may feel like all the criticism is incoming,
never outgoing. Thus, there is the danger of a siege mentality taking
hold among the old hands.
The best way to prevent this is to warn everyone about what's
coming, explain it, tell them that the initial discomfort is perfectly
normal, and reassure them that it's going to get better. Some of
these warnings should take place privately, before the project is
opened. But you may also find it helpful to remind people on the
public lists that this is a new way of development for the project,
and that it will take some time to adjust. The very best thing you
can do is lead by example. If you don't see your developers answering
enough newbie questions, then just telling them to answer more isn't
going to help. They may not have a good sense of what warrants a
response and what doesn't yet, or it could be that they don't have a
feel for how to prioritize coding work against the new burden of
external communications. The way to get them to participate is to
participate yourself. Be on the public mailing lists, and make sure
to answer some questions there. When you don't have the
expertise to field a question, then visibly hand it off to a developer
who does—and watch to make sure he follows up with an answer,
or at least a response. It will naturally be tempting for the
longtime developers to lapse into private discussions, since that's
what they're used to. Make sure you're subscribed to the internal
mailing lists on which this might happen, so you can ask that such
discussions be moved to the public lists right away.
There are other, longer-term concerns with opening up formerly
closed projects. explores
techniques for mixing paid and unpaid developers successfully, and
discusses the necessity of legal diligence
when opening up a private code base that may contain software written
or "owned" by other parties.
Announcing
Once the project is presentable—not perfect, just
presentable—you're ready to announce it to the world. This is
actually a very simple process: go to , click on
Submit in the top navigation bar, and fill
out a form announcing your new project. Freshmeat is the place
everyone watches for new project announcements. You only have to
catch a few eyes there for news of your project to spread by word of
mouth.
If you know of mailing lists or newsgroups where an announcement
of your project would be on-topic and of interest, then post there,
but be careful to make exactly one post per
forum, and to direct people to your project's own forums for follow-up
discussion (by setting the Reply-to header).
The posts should be short and get right to the point:
To: discuss@lists.example.org
Subject: [ANN] Scanley full-text indexer project
Reply-to: dev@scanley.org
This is a one-time post to announce the creation of the Scanley
project, an open source full-text indexer and search engine with a
rich API, for use by programmers in providing search services for
large collections of text files. Scanley is now running code, is
under active development, and is looking for both developers and
testers.
Home page: http://www.scanley.org/
Features:
- Searches plain text, HTML, and XML
- Word or phrase searching
- (planned) Fuzzy matching
- (planned) Incremental updating of indexes
- (planned) Indexing of remote web sites
Requirements:
- Python 2.2 or higher
- Enough disk space to hold the indexes (approximately 2x
original data size)
For more information, please come to scanley.org.
Thank you,
-J. Random
(See
in for advice on announcing
further releases and other project events.)
There is an ongoing debate in the free software world about
whether it is necessary to begin with running code, or whether a
project can benefit from being opened even during the
design/discussion stage. I used to think starting with running code
was the most important factor, that it was what separated successful
projects from toys, and that serious developers would only be
attracted to software that did something concrete already.
This turned out not to be the case. In the Subversion project,
we started with a design document, a core of interested and
well-connected developers, a lot of fanfare, and
no running code at all. To my complete surprise,
the project acquired active participants right from the beginning, and
by the time we did have something running, there were quite a few
volunteer developers already deeply involved. Subversion is not the
only example; the Mozilla project was also launched without running
code, and is now a successful and popular web browser.
In the face of such evidence, I have to back away from the
assertion that running code is absolutely necessary for launching a
project. Running code is still the best foundation for success, and a
good rule of thumb would be to wait until you have it before
announcing your project. However, there may be circumstances where
announcing earlier makes sense. I do think that at least a
well-developed design document, or else some sort of code framework,
is necessary—of course it may be revised based on public
feedback, but there has to be something concrete, something more
tangible than just good intentions, for people to sink their teeth
into.
Whenever you announce, don't expect a horde of volunteers to
join the project immediately afterward. Usually, the result of
announcing is that you get a few casual inquiries, a few more people
join your mailing lists, and aside from that, everything continues
pretty much as before. But over time, you will notice a gradual
increase in participation from both new code contributors and users.
Announcement is merely the planting of a seed. It can take a long
time for the news to spread. If the project consistently rewards
those who get involved, the news will spread,
though, because people want to share when they've found something
good. If all goes well, the dynamics of exponential communications
networks will slowly transform the project into a complex community,
where you don't necessarily know everyone's name and can no longer
follow every single conversation. The next chapters are about working
in that environment.