Guida del Committer

È richiesto l'uso di ssh(1) o telnet(1) con Kerberos 5 per connettersi agli host del progetto. Per ssh(1) è permesso solo il protocollo 2. Questi sono generalmente più sicuri che un semplice telnet(1) o rlogin(1) visto che la negoziazione delle credenziali avverrà sempre in modo cifrato. Tutto il traffico è cifrato di default con ssh(1). Insieme a programmi di utilità come ssh-agent(1) e scp(1), anch'essi disponibili, ssh(1) è di gran lunga più conveniente. Se non sai nulla di ssh(1), guarda la Sezione 9, «Guida Rapida a SSH».

Il repository CVS di FreeBSD ha un numero di componenti che, se combinati, supportano i sorgenti di base del sistema operativo, la documentazione, l'infrastruttura dei port delle applicazioni di terze parti, e vari programmi di utilità. Quando vengono assegnati i bit di commit di FreeBSD, vengono specificate le aree dell'albero dove il bit può essere usato. Solitamente, le aree associate a un bit corrispondono a quelle di chi ha autorizzato l'assegnamento del bit di commit. Ulteriori aree di autorità possono essere aggiunte in seguito: se occorrerà, il committer dovrà seguire le normali procedure di allocazione del bit di commit per quell'area dell'albero, chiedendo l'approvazione all'entità appropriata e possibilmente prendendo un mentore per quell'area per un po' di tempo.

I bit di commit assegnati prima dello sviluppo della nozione di aree di autorità possono essere usati in molte parti dell'albero. Tuttavia, il buon senso dice che un committer che non ha mai lavorato precedentemente in un'area dell'albero chieda una revisione del proprio lavoro prima di effettuare il commit, chieda l'approvazione del responsabile appropriato, e/o lavori d'accordo con un mentore. Dato che le regole sulla manutenzione del codice differiscono a seconda dell'area dell'albero, questo è per il bene del committer che lavora in un'area poco familiare tanto quanto per gli altri che lavorano sull'albero.

I committer sono incoraggiati a chiedere la revisione del proprio lavoro come parte del normale processo di sviluppo, indifferentemente dall'area dell'albero in cui stanno lavorando.

Si assume che tu abbia già familiarità con le operazioni di base di CVS.

I CVS Repository Meisters <cvsadm@FreeBSD.org> sono i «proprietari» del repository CVS e sono responsabili delle sue modifiche dirette allo scopo di ripulire o sistemare dei gravi abusi di CVS da parte di un committer. Nel caso dovessi causare qualche problema al repository, diciamo una errata operazione di cvs import o cvs tag, invia un messaggio al membro responsabile fra i CVS Repository Meisters <cvsadm@FreeBSD.org>, come stabilito nella tabella qui sotto, (o chiama uno di loro) ed esponi il problema. Per questioni molto importanti che interessano l'intero albero CVS-non solo un'area specifica-puoi contattare i CVS Repository Meisters <cvsadm@FreeBSD.org>. Non contattare i CVS Repository Meisters <cvsadm@FreeBSD.org> per copie di repository o altre cose che possono gestire i team più specifici.

Gli unici che hanno il permesso di manipolare direttamente i bit del repository sono i «repomeister». Per questo non ci sono shell di login disponibili sulle macchine del repository, tranne che per i repomeister.

L'albero CVS è attualmente diviso in quattro repository differenti, ovvero doc, ports, projects e src. Questi vengono ricomposti sotto un unico CVSROOT quando vengono distribuiti tramite CVSup per la convenienza dei nostri utenti.

I repository CVS sono ospitati sulle macchine repository. Attualmente, ognuno dei repository elencati qui sopra risiede sulla stessa macchina fisica, ncvs.FreeBSD.org, ma per permettere la possibilità di averne ognuno su una macchina diversa in futuro, ci sono diversi nomi di host che i committer dovrebbero utilizzare. Inoltre, ogni repository risiede in una directory differente. La seguente tabella racchiude la situazione.

Le operazioni sul CVS sono fatte da remoto impostando la variabile di ambiente CVSROOT a ncvs.FreeBSD.org:/home/ncvs e la variabile CVS_RSH a ssh, e quindi effettuando le appropriate operazioni di check-out/check-in. Molti committer definiscono degli alias che si espandono nella corretta invocazione di cvs per il repository appropriato. Per esempio, un utente di tcsh(1) può aggiungere le seguenti righe al suo .cshrc per questo scopo:

alias dcvs env CVS_RSH=ssh cvs -d user@dcvs.FreeBSD.org:/home/dcvs
alias pcvs env CVS_RSH=ssh cvs -d user@pcvs.FreeBSD.org:/home/pcvs
alias projcvs env CVS_RSH=ssh cvs -d user@projcvs.FreeBSD.org:/home/projcvs
alias scvs env CVS_RSH=ssh cvs -d user@ncvs.FreeBSD.org:/home/ncvs

In questo modo è possibile fare tutte le operazioni di CVS localmente ed usare Xcvs commit per effettuare il commit sull'albero CVS ufficiale. Se desideri aggiungere qualcosa di totalmente nuovo (ad esempio dei sorgenti in contrib, ecc.), deve essere usato cvs import. Guarda come riferimento la pagina man di cvs(1) per l'utilizzo.

Se devi usare le operazioni add e delete di CVS come se fosse un'operazione mv(1), allora va effettuata una copia nel repository piuttosto che usare add e delete di CVS. In una copia nel repository, un CVS Meister copierà il/i file nei loro nuovi nomi e/o locazioni e ti avviserà ad operazione avvenuta. Lo scopo di una copia del repository è di preservare la cronologia dei cambiamenti del file, o i log. Noi del FreeBSD Project diamo molta importanza alla cronologia dei cambiamenti che CVS fornisce al progetto.

Informazioni di riferimento, tutorial, e FAQ su CVS possono essere trovate su: http://www.cvshome.org/docs/. Anche le informazioni contenute nei capitoli di Karl Fogel da «Open Source Development with CVS» sono molto utili.

Dag-Erling C. Smørgrav ha fornito inoltre il seguente «mini manuale» su CVS.

Suggerimenti e trucchi aggiuntivi:

Come nuovo committer ci sono alcune cose che dovresti fare all'inizio.

Tutti i nuovi committer hanno un mentore assegnato a loro per i primi mesi. Il tuo mentore è responsabile di insegnarti le regole e le convenzioni del progetto e guidare i tuoi primi passi nella comunità dei committer. È anche personalmente responsabile delle tue azioni durante questo periodo iniziale. Fino a quando il tuo mentore non decide (e lo annuncia con un commit forzato su access) che sei diventato pratico e pronto per effettuare commit da solo, non dovresti effettuare commit senza aver prima ottenuto la revisione e l'approvazione del tuo mentore, e dovresti documentare l'approvazione con una riga Approved by: nel messaggio di commit.

Tutti i commit src dovrebbero andare su FreeBSD-CURRENT prima di essere fusi in FreeBSD-STABLE. Nessuna nuova caratteristica importante o modifica ad alto rischio dovrebbe essere fatta sul ramo FreeBSD-STABLE.

Attualmente il FreeBSD Project suggerisce di usare il seguente testo come schema di licenza preferito:

Copyright © <Year> <Author>. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

Il progetto FreeBSD scoraggia fortemente la cosiddetta clausola pubblicitaria nel nuovo codice. A causa del grande numero di contributi al progetto FreeBSD, osservare questa clausola per molti fornitori commerciali è diventato difficile. Se hai codice nell'albero con la clausola pubblicitaria, pensa a rimuoverla. In pratica, considera di usare la licenza qui sopra per il tuo codice.

Il progetto FreeBSD scoraggia completamente nuove licenze e variazioni sulle licenze standard. Nuove licenze richiedono l'approvazione di <core@FreeBSD.org> per risiedere nel repository principale. Più licenze differenti vengono usate nell'albero, più problemi possono essere causati a chi desidera utilizzare questo codice, tipicamente da conseguenze non previste di una licenza strutturata male.

Se stai lavorando direttamente sul tuo codice o su codice che è già stabilito essere di tua responsabilità, allora c'è probabilmente poca necessità di confrontarsi con altri committer prima di effettuare un commit. Se vedi un bug in un'area del sistema che è chiaramente orfana (e ce n'è qualcuna di queste aree, per nostra vergogna), agisci allo stesso modo. Se, tuttavia, stai per modificare qualcosa che è chiaramente mantenuto attivamente da qualcun'altro (ed è solo guardando la mailing list cvs-committers che puoi veramente sapere cosa è e cosa non è) allora invia le modifiche a lui, come avresti fatto prima di diventare committer. Per i port, dovresti contattare il MAINTAINER specificato nel Makefile. Per altre parti del repository, se non sei sicuro di chi possa essere il maintainer attivo, potrebbe essere utile scorrere l'output di cvs log per vedere chi ha effettuato delle modifiche in passato. Bill Fenner ha scritto un utile script di shell che può aiutare a determinare chi sia il maintainer attivo. Questo elenca ogni persona che ha effettuato commit su un file specifico con il numero di commit che ha fatto. Può essere trovato su freefall in ~fenner/bin/whodid. Se alle tue richieste non corrisponde una risposta o se il committer in altro modo dimostra uno scarso interesse nell'area oggetto della modifica, vai avanti ed effettua il commit tu stesso.

Se non sei sicuro di un commit per qualunque motivo, fallo revisionare da -hackers prima di effettuare il commit. Meglio che sia criticato lì piuttosto che quando è parte del repository CVS. Se ti capita di effettuare un commit che provoca controversie, potresti voler considerare l'annullamento delle modifiche finché il problema sia chiarito. Ricorda - con CVS possiamo sempre tornare indietro.

Non mettere in dubbio le intenzioni di qualcuno che non è d'accordo con te. Se vedono una soluzione differente dalla tua per un problema, o anche un problema diverso, non è perché sono stupidi, perché hanno una dubbia origine, o perché stanno cercando di distruggere il tuo duro lavoro, la tua immagine personale, o FreeBSD, ma semplicemente perché hanno una visione differente del mondo. La diversità è una buona cosa.

Dissenti onestamente. Argomenta la tua posizione con i suoi meriti, sii onesto sui difetti che può avere, e sii disponibile a guardare le loro soluzioni, o anche le loro visioni del problema, con mente aperta.

Accetta le correzioni. Possiamo tutti sbagliare. Se hai fatto un errore, scusati e vai avanti con la tua vita. Non picchiarti, e sicuramente non picchiare gli altri per il tuo sbaglio. Non sprecare tempo imbarazzandoti o recriminando, risolvi solo il problema e vai avanti.

Chiedi aiuto. Cerca (e dai) revisioni dagli altri. Uno delle cose in cui dovrebbe eccellere il software open source è il numero di occhi che lo scrutano; questo non è vero se nessuno revisionerà il codice.

Il FreeBSD Project utilizza GNATS per gestire i bug e le richieste di cambiamenti. Assicurati di usare edit-pr numero-pr su freefall quando effettui il commit di una correzione o di un suggerimento trovato in un PR GNATS per chiuderlo. È inoltre considerato gentile se trovi il tempo di chiudere ogni PR associato al tuo commit, se esistono. Puoi anche usare send-pr(1) tu stesso per proporre qualsiasi cambiamento che pensi debba essere fatto, a seguito di una maggiore revisione da parte di altre persone.

Puoi trovare di più su GNATS su:

Puoi far girare una copia locale di GNATS, e poi integrare l'albero GNATS di FreeBSD in esso tramite CVSup. In seguito puoi usare i comandi GNATS localmente, o usare altre interfacce, come tkgnats. Questo ti permette di interrogare il database dei PR senza bisogno di essere connesso a Internet.

Oltre ai meister del repository, ci sono altri membri e team del FreeBSD Project che probabilmente arriverai a conoscere nel tuo ruolo di committer. Brevemente, e senza pretesa di elencarli tutti, questi sono:

Ora dovresti essere in grado di usare ssh-add(1) per autenticarti una volta a sessione. Ti verrà richiesta la pass phrase della tua chiave privata, e quindi verrà salvata nel tuo agente di autenticazione (ssh-agent(1)). Se non vuoi più avere la tua chiave salvata nell'agente, l'esecuzione di ssh-add -d la rimuoverà.

Verifica facendo qualcosa come ssh freefall.FreeBSD.org ls /usr.

Per maggiori informazioni, guarda security/openssh, ssh(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), e scp(1).

Traduzione in corso

Traduzione in corso

Traduzione in corso

Sfortunatamente, non ci sono molti benefici derivanti dall'essere un committer. Il riconoscimento di essere un progettista di software competente è probabilmente l'unica cosa che sarà di tuo vantaggio a lungo termine. Ciononostante, ci sono comunque alcuni benefici:

Traduzione in corso