Come gestire un programma InnerSource di successo

Completato

Questa unità illustra come progettare un programma InnerSource per sfruttare il meglio dei modelli open source all'interno di qualsiasi organizzazione di sviluppo software.

Che cos'è InnerSource?

Chiunque può usare, modificare e condividere liberamente software open source. Con il software open source, chiunque può visualizzare, modificare e distribuire un progetto per qualsiasi scopo, con l'idea che la condivisione del codice porti a software migliore e più affidabile.

InnerSource è la pratica di applicare modelli open source ai progetti con un numero limitato di destinatari. Un'azienda può, ad esempio, implementare un programma InnerSource che rispecchia la struttura di un tipico progetto open source, ad eccezione del fatto che è accessibile solo ai dipendenti. In pratica, si tratta di un programma open source protetto dal firewall aziendale.

Vantaggi di InnerSource

Un programma InnerSource può offrire numerosi vantaggi oltre a quelli forniti dai tradizionali modelli chiusi.

In primo luogo, viene incoraggiata la trasparenza. L'accesso al codice sorgente di altri progetti aziendali può aiutare gli sviluppatori a migliorare la produttività quando lavorano sui propri progetti. È possibile vedere in che modo diversi team hanno risolto problemi simili a quelli che stanno affrontando e spesso è possibile trovare codice e altri asset riutilizzabili. L'accesso ai problemi dei team, alle richieste pull e ai piani del progetto fornisce inoltre dati migliori per comprendere la velocità e la direzione del progetto.

Viene anche ridotta la frizione. Si supponga che un team consumer dipenda da una correzione di bug o da una nuova funzionalità per un progetto di proprietà di un team diverso. In un programma InnerSource, hanno un canale attraverso il quale possono proporre le modifiche necessarie. Se per qualsiasi motivo non è possibile eseguire il merge di tali modifiche, il team consumer ha la possibilità di creare una copia tramite fork del progetto per soddisfare le proprie esigenze.

Infine, vengono standardizzate le procedure. Un problema comune che le organizzazioni di sviluppo affrontano è il fatto che team diversi spesso operano in modi diversi. La creazione di un programma InnerSource è un'ottima opportunità per adottare convenzioni standard che possono essere usate in ogni team di sviluppo, anche se non vengono seguite procedure identiche. Due team, ad esempio, possono preferire processi diversi per l'accettazione dei contributi. La standardizzazione del modo in cui vengono comunicati i diversi processi consente a tutti di contribuire più facilmente.

Questi esempi sono solo alcuni dei vantaggi offerti dai programmi InnerSource. Per altre informazioni, vedere An introduction to InnerSource (Introduzione a InnerSource).

Configurare un programma InnerSource in GitHub

Impostare la visibilità e le autorizzazioni del repository

È possibile configurare i repository GitHub con tre livelli di visibilità. Gli utenti che non soddisfano i requisiti di visibilità visualizzano pagine "non trovate" quando provano ad accedere al repository. I livelli sono i seguenti:

• I repository pubblici sono visibili a tutti. Usare questa visibilità per progetti che sono realmente open source e consentono l'accesso a persone all'interno e all'esterno dell'organizzazione.
• I repository interni sono visibili solo ai membri dell'organizzazione a cui appartengono. Usare questa visibilità per i progetti InnerSource.
• I repository privati sono visibili solo al proprietario e a tutti i team o i singoli utenti da esso aggiunti. Usare questa visibilità per i progetti a cui devono accedere solo utenti e gruppi specifici.

Una volta stabilita la visibilità del repository, è possibile configurare le autorizzazioni per singoli utenti o team. Sono disponibili cinque livelli di autorizzazione:

• Il livello di lettura è consigliato per i collaboratori che non scrivono codice e che desiderano visualizzare il progetto o discuterne.
• Il livello di valutazione è consigliato per i collaboratori che devono gestire in modo proattivo i problemi e le richieste pull senza accesso in scrittura.
• Il livello di scrittura è consigliato per i collaboratori che eseguono attivamente il push nel progetto.
• Il livello di gestione è consigliato per i project manager che devono gestire il repository senza accedere ad azioni sensibili o distruttive.
• Il livello di amministratore è consigliato per le persone che necessitano dell'accesso completo al progetto, incluse azioni sensibili e distruttive, ad esempio la gestione della sicurezza o l'eliminazione di un repository.

Altre informazioni sulle autorizzazioni di accesso al repository per livello.

Creare repository individuabili

Con l'ampliarsi di un programma InnerSource, il numero di repository può aumentare in modo significativo. Sebbene possa essere straordinario avere tutti gli asset a disposizione dell'organizzazione, può diventare complicato trovare il contenuto in modo efficiente. Per risolvere in modo proattivo questo problema, è consigliabile che i team considerino cosa possono fare per aiutare gli altri a trovare e usare i repository in modo più semplice.

Ecco alcune procedure consigliate:

• Usare un nome di repository descrittivo, ad esempio warehouse-api o supply-chain-web.
• Includere una descrizione concisa. Una frase o due sono sufficienti per consentire agli utenti potenziali di capire se il progetto può soddisfare le loro esigenze.
• Concedere in licenza il repository in modo che i clienti sappiano come possono usare, modificare e distribuire il software.
• Includere un file README.md nel repository. GitHub usa questo file come pagina di destinazione quando gli utenti visitano il repository.

Aggiungere un file README

Un file README comunica le aspettative per il progetto ed è utile per gestire i contributi. I file README possono:

• Definire lo scopo e la visione del progetto, in modo che i potenziali consumatori possano capire se soddisfa le loro esigenze.
• Offrire strumenti visivi, ad esempio screenshot o esempi di codice, per illustrare il progetto in azione.
• Includere collegamenti a una versione di produzione o demo dell'app per la revisione.
• Definire le aspettative per i prerequisiti e le procedure di distribuzione.
• Includere riferimenti ai progetti da cui si dipende. Questi riferimenti sono un modo efficace per promuovere il lavoro di altri utenti.
• Usare Markdown per guidare i lettori nella creazione di contenuto formattato correttamente.

Se si inserisce il file README nella directory radice del repository o nella directory nascosta .github o docs, GitHub riconosce ed espone automaticamente il file README ai visitatori del repository. Se un repository contiene più file README, il file visualizzato viene scelto dai percorsi nell'ordine seguente: la directory .github, la directory radice del repository e infine la directory docs.

Vedere alcuni esempi straordinari di file README.

Una volta avviato il progetto, usare la posta elettronica e altri canali di rete per promuoverlo. Raggiungendo i destinatari appropriati sarà possibile aumentare notevolmente la partecipazione al progetto.

Gestire progetti in GitHub

Man mano che i progetti diventano popolari, l'afflusso di utenti e contributi può richiedere un notevole lavoro di gestione. A seconda del progetto, potrebbe essere necessaria una quantità significativa di lavoro anche solo per gestire le aspettative dei partecipanti.

Per risolvere questo problema in modo proattivo, GitHub cerca un file CONTRIBUTING.md nella radice (oppure in /docs o /.github) di un repository. Usare questo file per illustrare i criteri per i contributi per il progetto. I dettagli esatti possono variare, ma è consigliabile consentire ai potenziali collaboratori di conoscere le convenzioni seguite dal progetto. Ad esempio, dove il team cerca le richieste pull, quali dettagli vengono richiesti per i report sui bug e così via.

Se esiste un file CONTRIBUTING.md, GitHub presenta un collegamento a esso quando gli utenti creano problemi o richieste pull, invitando a seguirlo.

Vedere alcuni esempi straordinari di file CONTRIBUTING.md

Valutare anche la possibilità di aggiungere un file CODEOWNERS al repository per definire i singoli utenti o team responsabili della revisione delle modifiche al codice.

Creare modelli per richieste pull e problemi

GitHub supporta modelli di avvio per i nuovi problemi e le richieste pull. Usare questi modelli per fornire il testo della descrizione iniziale quando si crea un nuovo problema o una richiesta pull.

Se, ad esempio, nel progetto è presente il file .github/ISSUE_TEMPLATE.md, ogni volta che un utente avvia il processo di creazione di un problema, viene visualizzato il contenuto seguente. Invece di dover fare continuamente riferimento ai dettagli richiesti in un file CONTRIBUTING.md, è possibile compilare il modulo per definire il problema in base al testo del modello.

Lo stesso vale per le richieste pull, con l'unica differenza del percorso, che è .github/PULL_REQUEST_TEMPLATE.md.

Vedere alcuni esempi straordinari di modelli per problemi e richieste pull di GitHub.

Definire i flussi di lavoro

Per i progetti che incoraggiano i contributi esterni, assicurarsi di specificare il flusso di lavoro seguito. Il flusso di lavoro deve includere informazioni dettagliate su dove e come usare i rami per bug e funzionalità. Deve includere anche il modo in cui devono essere aperte le richieste pull e tutti gli altri dettagli che gli utenti esterni al team del repository devono conoscere prima di eseguire il push del codice. Se non si ha ancora in mente un flusso di lavoro, prendere in considerazione il flusso di GitHub.

È necessario comunicare una strategia per la gestione di versioni e distribuzioni. Queste parti del flusso di lavoro influiscono sulla creazione di rami e sulle operazioni di merge, quindi è importante comunicarle ai collaboratori. Altre informazioni sulla correlazione tra questi elementi e la strategia di creazione di rami Git.

Misurazione del successo del programma

Qualsiasi team che decida di usare InnerSource deve considerare i tipi di metriche da monitorare per misurare il successo del programma. Sebbene le metriche tradizionali come quelle relative a time-to-market e bug segnalati siano ancora applicabili, non indicano necessariamente i vantaggi ottenuti tramite InnerSource.

Si consiglia invece di aggiungere metriche che mostrino come la partecipazione esterna abbia migliorato la qualità del progetto. Il repository riceve richieste pull da origini esterne che correggono i bug e aggiungono funzionalità? Ci sono partecipanti attivi che discutono del progetto e del suo futuro? Il programma incoraggia un'espansione di InnerSource che offre vantaggi anche ad altre parti dell'organizzazione?

In breve, le metriche sono complesse, in particolare quando si tratta di misurare il valore e l'effetto dei contributi di singoli utenti e team. Se non vengono usate nel modo giusto, le metriche possono danneggiare la cultura e i processi esistenti e diminuire l'apprezzamento collettivo per l'organizzazione o il team di leadership. Quando si valuta come misurare l'adozione di InnerSource, tenere presente le indicazioni seguenti sulle metriche:

• Misurare il processo, non l'output
  • Tempo di completamento delle revisioni del codice
  • Dimensioni delle richieste pull
  • Lavori in corso
  • Tempo di apertura
• Misurare rispetto agli obiettivi, non a valori assoluti
• Misurare i team, non i singoli utenti
  • Numero di collaboratori univoci per un progetto
  • Numero di progetti che riutilizzano il codice
  • Numero di menzioni (@mentions) tra team

Per informazioni sui successi ottenuti da altri utenti, vedere questi case study di InnerSource.