Trimiterea de conținut

Pentru a contribui cu o nouă documentație sau pentru îmbunătățirea uneia existente, trimite un pull request (PR)

• Dacă schimbarea ta este mică, sau ești nefamiliarizat cu Git, vezi cum se Folosește GitHub pentru a învăța cum să editezi o pagină.
• Altfel, vezi cum se Lucreză de pe un fork local pentru a învăța cum să faci schimbări în mediul tău local de dezvoltare.

Politica de contribuție folosind IA generativă

IA generativă este permisă, dar tu ești responsabil pentru revizuirea și validarea întregului conținut generat de IA — Dacă nu-l înțelegi, nu-l trimite!

Pentru detalii, vezi Politica de contribuție folosind IA generativă.

Cum să contribui

Figura următoare ilustrează cum să contribui cu documentație nouă.

flowchart LR
    subgraph first[Cum să contribui]
    direction TB
       T[ ] -.-
       B[Creează un fork al repository-ului în GitHub] --- C[Scrie documente în markdown<br> și construiește site-ul cu Hugo]
       C --- D[Împinge sursele la fork]
       D --- E[Deschide un pull request]
       E --- F[Semnează <a href="../prerequisites/#cla">CLA-ul CNCF</a>]
    end

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,C,D,E,F,G,H grey
class S,T spacewhite
class first,second white

Figura 1. Contribuții cu conținut nou.

Utilizarea GitHub

Modifică și trimite schimbări din browser-ul tău

Dacă nu ești foarte experimentat cu fluxurile de lucru cu Git, aici se regăsește o metodă mai ușoară de pregătire și deschidere a unui nou pull request (PR). Figura 2 ilustrează pașii și detaliile urmează.

flowchart LR
A([fa:fa-user Contribuitor<br>Nou]) --- id1[(open-telemetry/opentelemetry.io<br>GitHub)]
subgraph tasks[Modificări folosind GitHub]
direction TB
    0[ ] -.-
    1[1\. Modifică această pagină] --> 2[2\. Folosește editorul de markdown<br>din GitHub pentru a face schimbări]
    2 --> 3[3\. Completează în Propune schimbare de fișier]

end
subgraph tasks2[ ]
direction TB
4[4\. Selectează Propune schimbare de fișier] --> 5[5\. Selectează Creează pull request] --> 6[6\. Completează în Deschide un pull request]
6 --> 7[7\. Selectează Creează pull request]
end

id1 --> tasks --> tasks2

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,1,2,3,4,5,6,7 grey
class 0 spacewhite
class tasks,tasks2 white
class id1 k8s

Figura 2. Pașii pentru deschiderea unui PR folosind GitHub.

1. Pe pagina unde vezi issue-ul, selectează opțiunea Editează această pagină din panoul de navigare din partea dreaptă.

2. Dacă nu ești un membru al proiectului, GitHub oferă opțiunea de creare a unui fork al repository-ului. Selectează Fork this repository.

3. Efectuează schimbările în editorul din GitHub.

4. Completează formularul Propune schimbare de fișier.

5. Selectează Propune schimbare de fișier.

6. Selectează Creează pull request.

7. Va apărea ecranul Deschide un pull request. Descrierea ta îi ajută pe cei ce revizuiesc să înțeleagă schimbările tale.

8. Selectează Creează pull request.

Înainte de a îmbina un pull request, membrii comunității OpenTelemetry îl revizuiesc și-l aprobă.

Dacă un revizuitor solicită să faci modificări:

1. Du-te la tab-ul Fișiere schimbate.
2. Selectează iconița creion (de editare) în oricare fișier schimbat din pull request.
3. Aplică schimbările cerute. Dacă există o sugestie de cod, aplic-o.
4. Trimite schimbările.

Când revizuirea este completă, un revizuitor va adăuga schimbările din PR-ul tău, care se vor putea vedea câteva minute mai târziu.

Rezolvarea problemelor semnalate de verificările PR-ului

După ce ai trimis un PR, GitHub rulează niște verificări ale build-ului. Anumite verificări ce eșuează, precum probleme de formatare, pot fi rezolvate automat.

Adaugă următorul comentariu în PR-ul tău:

/fix

Acesta va declanșa ca bot-ul OpenTelemetry să încerce să rezolve problemele de build. Bot-ul răspunde cu un comentariu despre progres care face referire la comanda de rezolvare, apoi actualizează același comentariu cu rezultatul - fiecare comandă de rezolvare pe care o emiți primește propriul comentariu de la bot. Sau poți emite una dintre următoarele comenzi de rezolvare pentru a trata o problemă specifică:

/fix:code-excerpts
/fix:dict
/fix:expired
/fix:filenames
/fix:format
/fix:i18n
/fix:l10n
/fix:markdown
/fix:refcache
/fix:submodule
/fix:text

Comanda de rezolvare trebuie să fie prima linie a comentariului tău; poți adăuga text explicativ în liniile ce urmează. Emiterea unei noi comenzi de rezolvare în timp ce una rulează deja o anulează pe cea ce rulează astfel că cea mai recentă comandă câștigă; atunci când se poate, comentariul bot-ului asociat acțiunii anulate este actualizat pentru a indica anularea.

Dezvoltare pe mediul local

Dacă ești mai experimentat cu Git sau dacă schimbările tale sunt mai mari decât câteva linii, lucrează de pe un fork local.

Asigură-te că ai git instalat pe calculatorul tău. Poți de asemenea să folosești o interfață pentru Git.

Figura 3 arată pașii de urmat atunci când lucrezi de pe un fork local. Detaliile pentru fiecare pas urmează.

flowchart LR
1[Fă un fork al repository-ului<br>open-telemetry/opentelemetry.io] --> 2[Creează o clonă locală<br>și setează upstream-ul]
subgraph changes[Schimbările tale]
direction TB
S[ ] -.-
3[Creează o ramură<br>de exemplu: ramura_mea_noua] --> 3a[Modifică folosind<br>un editor de text] --> 4["Previzualizează schimbările tale<br>local folosind Hugo<br>(localhost:1313)"]
end
subgraph changes2[Commit / Push]
direction TB
T[ ] -.-
5[Trimite schimbările tale] --> 6[Împinge commit-ul la<br>origin/ramura_mea_noua]
end

2 --> changes --> changes2

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class 1,2,3,3a,4,5,6 grey
class S,T spacewhite
class changes,changes2 white

Figura 3. Lucrul de pe un fork local pentru a aplica modificările.

Fă un fork al repository-ului

1. Navighează la repository-ul opentelemetry.io.
2. Selectează Fork.

Clonează și setează upstream-ul

1. Într-o fereastră de terminal, clonează fork-ul tău și instalează dependențele necesare:

   git clone git@github.com:<utilizatorul_tau_github>/opentelemetry.io.git
   cd opentelemetry.io
   npm install
   

2. Setează repository-ul open-telemetry/opentelemetry.io ca upstream-ul remote:

   git remote add upstream https://github.com/open-telemetry/opentelemetry.io.git
   

3. Confirmă repertoriile pentru origin și upstream:

   git remote -v
   

   Rezultatul este similar cu:

   origin	git@github.com:<utilizatorul_tau_github>/opentelemetry.io.git (fetch)
   origin	git@github.com:<utilizatorul_tau_github>/opentelemetry.io.git (push)
   upstream	https://github.com/open-telemetry/opentelemetry.io.git (fetch)
   upstream	https://github.com/open-telemetry/opentelemetry.io.git (push)
   

4. Preia commit-uri de pe ramura origin/main a fork-ului și de pe upstream/main al open-telemetry/opentelemetry.io:

   git fetch origin
   git fetch upstream
   

   Acest lucru te asigură că repository-ul tău local este la zi înainte să începi să faci modificări. Împinge schimbările de pe upstream la origin regulat pentru a păstra fork-ul sincronizat cu upstream-ul

Creează o ramură

1. Creează o ramură. Acest exemplu presupune că ramura de bază este upstream/main:

   git checkout -b <ramura_mea_noua> upstream/main
   

2. Fă schimbările tale folosind un editor de cod sau text.

În orice moment, folosește comanda git status pentru a vedea ce fișiere ai modificat.

Trimite schimbările tale

Când ești gata să trimiți un pull request, urcă schimbările tale.

1. În repository-ul tău local, verifică ce fișiere trebuie să urci:

   git status
   

   Rezultatul este similar cu:

   On branch <ramura_mea_noua>
   Your branch is up to date with 'origin/<ramura_mea_noua>'.
   
   Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)
   
   modified:   content/en/docs/file-you-are-editing.md
   
   no changes added to commit (use "git add" and/or "git commit -a")
   

2. Adaugă fișierele listate sub Changes not staged for commit la setul de schimbări:

   git add <your_file_name>
   

   Repetă asta pentru fiecare fișier.

3. După ce ai adăugat toate fișierele, creează un commit:

   git commit -m "Mesajul tău de commit"
   

4. Împinge ramura ta locală cu commit-ul nou la fork-ul tău:

   git push origin <ramura_mea_noua>
   

5. Odată ce schimbările sunt trimise, GitHub te înștiințează că poți crea un PR.

Deschide un PR nou

Figura 4 arată pașii pentru a deschide un PR din fork-ul tău pe opentelemetry.io.

flowchart LR
subgraph first[ ]
direction TB
1[1\. Mergi la repository-ul opentelemetry.io] --> 2[2\. Selectează 'New Pull Request']
2 --> 3[3\. Selectează 'compare across forks']
3 --> 4[4\. Selectează fork-ul tău din<br>meniul drop-down de selecție al repository-ului head]
end
subgraph second [ ]
direction TB
5[5\. Selectează ramura ta din<br>meniul drop-down de comparație] --> 6[6\. Selectează Creează Pull Request]
6 --> 7[7\. Adaugă o descriere<br>la PR-ul tău]
7 --> 8[8\. Selectează Creează pull request]
end

first --> second

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
class 1,2,3,4,5,6,7,8 grey
class first,second white

Figura 4. Pașii pentru a deschide un PR din fork-ul tău la opentelemetry.io.

1. Într-un browser web, navighează la repository-ul opentelemetry.io.

2. Selectează New Pull Request.

3. Selectează compare across forks.

4. Din meniul drop-down pentru repository-ul head , selectează fork-ul tău.

5. Din meniul drop-down compare, selectează ramura ta.

6. Selectează Creează Pull Request.

7. Adaugă o descriere pentru pull request-ul tău:

   • Title (50 de caractere sau mai puțin): Creează un rezumat al intenției schimbărilor.
   • Description: Descrie schimbările în detaliu.
     • Dacă există un GitHub issue de care se leagă, include Fixes #12345 sau Closes #12345 în descriere astfel ca automatizările din GitHub să închidă issue-ul menționat după ce PR-ul a fost unit. Dacă există și alte PR-uri conexe, menționează‑le și pe acelea.
     • Dacă dorești sfaturi despre ceva specific, include în descriere orice întrebare la care ai vrea ca revizuitorii să se gândească.

8. Selectează butonul Creează pull request.

Pull request-ul tău este disponibil în secțiunea Pull requests.

După deschiderea unui PR, GitHub rulează teste automate and încearcă să lanseze o previzualizare folosind Netlify.

• Dacă build-ul de Netlify eșuează, selectează Details pentru mai multe informații.
• Dacă build-ul de Netlify reușește, selectează Details pentru a deschide o versiune intermediară a website-ului OpenTelemetry cu schimbările tale aplicate. Așa verifică revizuitorii schimbările tale.

Și alte verificări pot eșua. Vezi lista cu toate verificările de PR.

Rezolvă problemele

Înainte să trimiți o schimbare la repertoriu, rulează următoarea comandă și (i) remediază orice problemă semnalată, (ii) trimite orice fișier schimbat de către script:

npm run test-and-fix

Pentru a testa și repara separat toate problemele din fișierele tale, rulează:

npm run test # Checks but does not update any files
npm run fix  # May update files

Pentru a lista toate script-urile NPM disponibile, rulează npm run. Vezi PR checks pentru mai multe informații despre verificările de pull request și cum să repari erorile automat.

Vizualizează schimbările tale

Vizualizează schimbările local înainte să le trimiți sau să deschizi un pull request. O previzualizare îți permite să identifici erorile de build sau de formatare Markdown.

Pentru a construi și servi site-ul pe mediul local folosind Hugo, rulează următoarea comandă:

npm run serve

Navighează la http://localhost:1313 în browser-ul tău web pentru a vedea versiunea locală. Hugo monitorizează modificările și reconstruiește site-ul după caz.

Pentru a opri instanța locală de Hugo, mergi înapoi în terminal și tastează Ctrl+C, sau închide fereastra de terminal.

Lansări ale site-ului și previzualizări din PR

Dacă trimiți un PR, Netlify lansează o previzualizare astfel că poți revizui schimbările tale. Odată ce schimbările din PR-ul sunt trimise, Netlify lansează versiunea actualizată a site-ului pe server-ul de producție.

Notă: Previzualizările din PR includ pagini draft, dar build-urile de producție nu.

Pentru a vedea log-uri despre deploy și mai multe, vizitează panoul proiectului – Necesită un login pe Netlify.

Îndrumări pentru PR

Înainte ca schimbările dintr-un PR să fie integrate, uneori este necesar să se treacă prin câteva iterații de revizuire-și-editare. Pentru a face acest proces cât mai facil pentru noi cât și pentru tine, te rugăm să aderi la următoarele:

• Dacă PR-ul tău nu este un fix rapid, atunci lucrează de pe un fork: Apasă butonul Fork din antetul repository-ului și clonează fork-ul local. Când ești gata, trimite un PR către repository-ul upstream.
• Nu lucra pe ramura main a fork-ului tău, creează o ramură specifică pentru PR.
• Asigură-te că administratorii au dreptul să modifice schimbările din pull request-ul tău.

Schimbări de la revizuitori

Uneori revizuitorii trimit schimbări la pull request-ul tău. Înainte de a face orice altă schimbare, preia acele schimbări.

1. Preia schimbări de pe fork-ul tău remote și aplică un rebase pe ramura ta de lucru:

   git fetch origin
   git rebase origin/<ramura-ta>
   

2. După rebase, trimite schimbările noi către fork-ul tău folosind force-push:

   git push --force-with-lease origin <ramura-ta>
   

Poți de asemenea să rezolvi din interfața GitHub conflictele datorate integrării schimbărilor .

Conflictele datorate integrării schimbărilor și rebase

Dacă alt contribuitor trimite schimbări la același fișier în alt PR, poate genera un conflict de integrare a schimbărilor. Trebuie să rezolvi toate aceste conflicte în PR-ul tău.

1. Actualizează fork-ul tău și integrează schimbările în ramura ta locală folosind rebase:

   git fetch origin
   git rebase origin/<ramura-ta>
   

   Apoi trimite schimbările la fork-ul tău folosind force-push:

   git push --force-with-lease origin <ramura-ta>
   

2. Preia schimbările de pe ramura upstream/main a repository-ului open-telemetry/opentelemetry.io și integrează-le în ramura ta folosind rebase:

   git fetch upstream
   git rebase upstream/main
   

3. Inspectează rezultatele după rebase:

   git status
   

   Acest lucru duce la o serie de fișiere marcate ca fiind în conflict.

4. Deschide fiecare fișier în conflict și caută marcajele de conflict: >>>, <<<, și ===. Rezolvă conflictele și apoi șterge marcajul de conflict.

   Pentru mai multe informații, vezi Cum sunt prezentate conflictele.

5. Adaugă fișierele în setul de schimbări:

   git add <numele-fișierului>
   

6. Continuă rebase-ul:

   git rebase --continue
   

7. Repetă pașii 2 până la 5 după caz.

   După aplicarea tuturor schimbărilor, comanda git status arată că procesul de rebase este complet.

8. Trimite schimbările din ramura ta către fork-ul tău folosind force-push:

   git push --force-with-lease origin <ramura-ta>
   

   Pull request-ul nu va mai arăta vreun conflict.

Cerințe pentru integrarea schimbărilor

Schimbările din pull request sunt integrate atunci când sunt conforme cu următoarele criterii:

• Toate revizuirile făcute de aprobatori, administratori, membrii comitetului tehnic sau experți au statusul “Approved”.
• Nici o conversație nerezolvată.
• Să fie aprobat de către cel puțin un aprobator.
• Nici o verificare de PR care să eșueze.
• Ramura PR-ului este la zi cu ramura de bază.
• Schimbările paginilor de documentație nu acoperă traducerile.

Important

Nu te îngrijora prea mult despre verificările de PR care eșuează. Membrii comunității te vor ajuta să le rezolvi, fie oferindu-ți instrucțiuni despre cum să le repari, fie reparându-le pentru tine.