Skip to content

Latest commit

 

History

History
397 lines (309 loc) · 16.5 KB

README-it.md

File metadata and controls

397 lines (309 loc) · 16.5 KB
Raw

Kubernetes Contributor Cheat Sheet

English

Questo documento fornisce una lista di risorse utili per contribuire a Kubernetes, suggerimenti, trucchi e best practices utilizzate nel progetto Kubernetes. E' un "TL;DR" o un breve condensato di informazioni utili per rendere migliore la tua esperienza di GitHub contributor.

Sommario

Risorse utili

Per cominciare

  • Contributor Guide - Documento che descrive come cominciare a contribuire al Kubernetes project.
  • Developer Guide - Documento che descrive come cominciare a contribuire codice al Kubernetes project.
  • Security and Disclosure Information - Documento che descrive come segnalare vulnerabilities e come viene gestito il security release process (hotfix).

SIGs and Other Groups

Community

  • Calendar - Visaluzza tutti gli eventi della Kubernetes Community (SIG/WG meetings, eventi etc.)
  • kubernetes-dev - La mailing list su Kubernetes development
  • Kubernetes Forum - Forum ufficale di Kubernetes.
  • Slack channels - Slack channel ufficiale di Kubernetes.
  • Stack Overflow - Il sito dove gli utenti di Kubernetes possono inviare le loro domande.
  • YouTube Channel - YouTube channel ufficiale di Kubernetes.

Workflow

Tests

  • Prow - Kubernetes CI/CD System.
  • Test Grid - Visualizzo lo storico dei test e tutte le informazioni associate.
  • Triage Dashboard - Aggrega problematiche simili per semplificare il troubleshooting.

Important Email Aliases

Other Useful Links

Comunicare efficacement su GitHub

Come essere rispettosi gli uni degli Altri

Come primo step, familiarizza con il Code of Conduct.

Esempi di buone/cattive comunicazioni

Quando stai segnalando un problema, o chiedendo aiuto, esprimi cortesemente la tua richiesta:

🙂 “X doesn’t compile when I do Y, do you have any suggestions?”

😞 “X doesn’t work! Please fix it!”

Quando stai chiudendo una PR, fornisci una spiegazione cordiale del motivo per cui questa non rispetta i criteri per essere accettata.

🙂 “I’m closing this PR because this feature can’t support the use case X. In it's proposed form, it would be a better to be implemented with Y tool. Thank you for working on this.”

😞 “Why isn’t this following the API conventions? This should be done elsewhere!”

Contribuire

Firmare la CLA

Prima di poter inviare qualsiasi contribuzione a Kubernetes, devi firmare la Contributor License Agreement(CLA). Il progetto Kubernetes accetta contribuzioni solo se tu o la tua azienda hanno firmato la CLA.

Nel caso tu incontri problemi nel firmare la CLA, segui le CLA troubleshooting guidelines.

Aprire of rispondere ad una Issues

Le issues in GitHub sono lo strumento principale per tracciare elementi come bug reports, richieste di nuove feature, o report di altri problemi come i failing tests. Le issue non sono intese come strumenti per gestire user support requests. Per queste ultime, verifica la troubleshooting guide, segnala il problema su Stack Overflow o accedi al Kubernetes forum.

References:

Creare una Issue

  • Utilizza l'issue template se disponibile. L'ulizzo corretto degli issue template aiuta gli altri contributors nel rispondere alla tua issue.
  • Segui le istruzioni definite nell'issue template.
  • Fornisci una descrizione accurata della issue che stai sollevando.
  • Assegna le labels opportune. Se non sei sicure, il k8s-ci-robot bot (Kubernetes CI bot) risponderà alla tua issue aggiungendo le label necessarie affinche la tua issue sia opportunamente valutata.
  • Utilizza con parsimonia i comandi /assign @<username> o /cc @<username>. La tua issue sarà valuta in modo più efficace applicando le le label opportune anzichè assegnando più persone alla tua issue.

Rispondere ad una Issue

  • Quanndo inizi a lavorare su una issue, lascia un commento in modo che gli altri contributors sono informati della cosa e quindi si eviti di duplicare lavoro.
  • Se per caso risolvi una tua vecchia issue per conto tuo, prima di chiuderla lascia un commento sulla issue in modo che possa aiutare altri utenti che incontreranno lo stesso problema.
  • Includi riferimenti al altre PRs o issues (o altro materiale pubblicamente accessibile). Esempio: "ref: #1234". Questo aiuta ad identificare altre attività correlate che sono in corso/già state completate altrove.

Aprire una Pull Request

Le pull requests in GitHub (PR) sono il principale modo per contribuire codice, documentazione o altre forme di lavoro nei git repository di Kubernetes.

References:

Creare una Pull Request

  • Segui le istruzioni del pull request template se disponibile. Questo aiuterà quelli che risponderanno alla tua PR.
  • Se la PR è per un trivial fix come un broken link, un typo o un errore di grammatica, rivedi tutto il documento per verificare se ci sono altri errori dello stesso tipo. Non aprire diverse PRs per small fixes nello stesso documento.
  • Fai riferimento a qualsiasi issue correlata alla tua PR a alle issue che la tua PR risolve.
  • Evita di creare single commits con un numero elevato di modifiche. Invece, suddividi la tua PR in una serie di commit più semplici e logicamente consistenti. Questo semplifica il lavoro di review della tua PR.
  • Aggiungi dei commenti alla tua PR dove ritieni che qualcosa necessiti di una spiegazione aggiuntiva.
  • Utilizza con parsimonia il comando /assign @<username>. Avere PR con un numero elevato di reviewer non ti garantisce di avere una review più rapidamente.
  • Se consideri la tua PR ancora un "Work in progress" aggiungi il prefisso [WIP] al nome della PR oppure utilizza il comando /hold. Questo impedisce all tua PR di fare merge fino a che [WIP] o hold sono rimossi.
  • Se la tua PR non è stata rivista, non chiuderla e non aprirne un'altra con le stesse modifiche. Puoi pingare i tuoi reviewer con un commento dove con @<github username>.
  • Se non ottieni risposta entro qualche giorno, posta un link della tua PR nel #pr-reviews channel su Slack per trovare altri reviewers.

Esempi di PR description

Ref. #3064 #3097
All files owned by SIG testing were moved from `/devel` to the new folder `/devel/sig-testing`.

/sig contributor-experience
/cc @stakeholder1 @stakeholder2
/kind cleanup
/area developer-guide
/assign @approver1 @approver2 @approver3

Cosa c'è in questa PR:

  • Line 1 - Il riferimento ad altre issues o PRs (#3064 #3097).
  • Line 2 - Una semplice descrizione di quali modifiche questa PR implementa.
  • Line 4 - L'indicazione del SIG di riferimento tramite il comando /sig contributor-experience..
  • Line 5 - L'elenco dei reviewer che potrebbero essere interessati a questa PR è specificato utilizzando il comando /cc.
  • Line 6 - Il comando /kind cleanup aggiunge una label che categorizza la PR come attività di clean up di codice, processi, o riduzione del technical debt.
  • Line 7 - Il comando /area developer-guide categorizza la PR come modifica nell'area della developer guide.
  • Line 8 - Il comando /assign assegna uno o più reviewer alla PR. Un approver saà suggerito dal k8s-ci-robot che seleziona dalle liste di owners definite negli OWNERS file. Gli approver aggiungeranno la label /approve alla PR quando sarà pronta per il merge.

Troubleshooting di una Pull Request

Dopo che la tua PR è inviata, una serie di test è eseguita dalla piattaforma di CI di Kubernetes, Prow. Se uno dei test fallisce, k8s-ci-robot aggiungerà un commento alla PR con il link ai test falliti e ai relativi logs.

Ogni nuova commit sulla tua PR comporta in automatico la ripetizione dei test.

In alcune situazioni ci possono anche essere dei problemi con la piattaforma di CI di Kubernetes (flakes). Questi possono avvenire per svariate ragioni, anche se gli stessi test passano localmente. Puoi ri-eseguire i test con il comando /retest.

Per maggiori informazioni sulla risoluzione dei problemi sui test, vedi Testing Guide.

Labels

Kubernetes utilizza le labels per fare triage e categorizzare sia le issues che le pull request. Applicare le label opportune aiuta la tua issue o la tua PR ad essere valutata in modo più effettivo.

References:

Label utilizzate frequenetemente:

Lavora localmente

Prima di inviare una pull request è necessario fare iun pò di lavoro localmenente. Se non sei esperto di git, l' Atlassian git tutorial è un buon punto di partenza. Come alternativa, Git magic tutorial di Stanford è una soluzione disponbile in diverse lingue.

References:

Branch Strategy

Il progetto Kubernetes utilizza il "Fork and Pull" workflow che è tipico di diversi progetti su GitHub. Utilizzando la terminologia git terms, il tuo personal fork è definito come "origin" mentre il progetto vero e proprio è chiamato "upstream". Per mantenere il tuo branch personale (origin) allineato con il progetto (upstream), è necessario che quest'ultimo sia collegato nel tuo ambiente di lavoro locale.

Aggiungere Upstream

Aggiungere upstream come remote, e disabilitare la possibilità di fare push su quest'ultimo.

# replace <upstream git repo> with the upstream repo url
# example:
#  https://github.com/kubernetes/kubernetes.git
#  [email protected]/kubernetes/kubernetes.git

git remote add upstream <upstream git repo>
git remote set-url --push upstream no_push

Eseguendo il comando git remote -v è possibile verificare la corretta configurazione dei remotes.

Mantenere il tuo Fork in Sync

Fai Fetch delle ultime modifiche da upstream e a segure "rebase" delle stesse sul tuo master branch locale. Questo permetterà di mantenere sincronizzati il repository locale con l' upstream project. Quando hai finito, riscordati di fare Push delle modifiche locali sul tuo remote master.

git fetch upstream
git checkout master
git rebase upstream/master
git push

Devi ripetere questa operazione ogni volta prima di creare un nuovo branch locale per lavorare su una nuova feature o su una fix.

git checkout -b myfeature

Squashing Commits

L'obiettivo principale dell'operazione di squashing commits è quello di garantire che la history delle commit documenti in modo chiaro l'elenco delle modifiche che sono state fatte. Solitamente questa attività viene fatta come ultima fare del processi di review un PR. Se non se sicuro se fare una squash dei tuoi commit, è solitamente preferibile lasciare più commit e attendere che gli altri contributors che stanno facendo la review della tua PR esprimano un giudizio in merito.

E' possbile utilizzare un interactive rebase per scegliere quali commits tenere e di quali invece vuoi fare squash, e a seguire fai force push del tuo branch.

git rebase -i HEAD~3
...
git push --force