Gå til indholdet

Indsendelse af en pull-anmodning

Nu hvor du har gemt alle dine ændringer, er du klar til at indsende en pull-anmodning. For at sikre en smidig gennemgangsproces er der en række trin, du bør følge.

Arbejde med pre-commit

Når du committer en ændring, kører pre-commit automatisk. Hvis der findes problemer med committen, vil dette medføre, at din commit mislykkes. Hvor det er muligt, vil pre-commit foretage de nødvendige ændringer for at rette de fundne problemer. I det følgende eksempel blev der fundet et problem med kodeformatering ved ruff check:

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

I dette tilfælde løste ruff automatisk problemet, så du kan derefter tilføje alle filer, der blev ændret som følge af pre-commit-kontrollerne, og gencommitte ændringen. Nogle kontroller kræver dog, at du foretager manuelle ændringer. Når du har foretaget disse ændringer, skal du tilføje alle ændrede filer igen og gencommitte.

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

Når alt er gået igennem, vil du se en besked om, at commit er blevet afsluttet, og din git-log vil vise din commit som den seneste tilføjelse. Du er nu klar til at pushe til GitHub.

Overfør dine ændringer til GitHub og opret din pull-anmodning

Første gang du push'er til GitHub, får du en URL, der fører dig direkte til GitHub-siden, hvor du kan oprette en ny pull-request. Følg URL'en og opret din pull-request.

Nedenfor vises et eksempel på, hvad du kan forvente på push, hvor URL'en er fremhævet.

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Hvis du tidligere har pushet den aktuelle gren til GitHub, modtager du ikke URL'en igen. Der er dog andre måder at få adgang til URL'en til oprettelse af PR:

  • Naviger til upstream-repositoriet, klik på "Pull Requests" efterfulgt af "New pull request", og vælg den, du vil sende din pull-anmodning fra.
  • Hvis du for nylig har pushet, skal du navigere til upstream-repositoriet, finde banneren over listen over filer, der angiver, at repoet har "haft nylige pushes", og klikke på knappen "Sammenlign og pull request".
  • Brug GitHub CLI gh pr create kommandoen, og udfyld de anmodede oplysninger.
  • Brug GitHub CLI gh pr create --web kommandoen til at åbne en webbrowser til siden for oprettelse af PR.

Alle disse muligheder giver dig mulighed for at oprette din nye pull-anmodning.

GitHub CLI: gh

GitHub tilbyder GitHub CLI, som giver dig adgang til mange af GitHubs funktioner fra din terminal via kommandoen gh. GitHub CLI-dokumentationen dækker alle funktionerne.

Indhold af pull-anmodning

En pull request-titel skal være informativ, klar og kortfattet. Forsøg at holde den kort, hvis det er muligt, men længere titler er acceptable, hvis det er nødvendigt. En god PR-titel skal give en person uden nogen kontekst en rimelig god idé om, hvilken fejl eller funktion der er implementeret i din PR.

PR-beskrivelsen skal tydeligt afspejle ændringerne i PR. En person uden nogen kontekst skal kunne læse din beskrivelse og få en relativt fuldstændig forståelse af, hvorfor ændringen foretages. Undgå vittigheder, idiomer, slangudtryk og unødvendig formatering, såsom brug af store bogstaver eller overdreven tegnsætning. Dette skal være en ligetil forklaring af, hvad der sker i din PR, og ved at undgå disse ting bliver beskrivelsen mere tilgængelig for andre.

Hvis der er reproduktionssager eller testprocedurer, som du har brugt, og som ikke allerede er en del af ændringerne i PR, skal de forklares og medtages i PR. Forklaringen skal omfatte, hvordan de udføres, og hvad der skal gøres for at reproducere det ønskede resultat.

Hvis din pull-anmodning løser problem #1234, skal du inkludere teksten `Fixes

1234` i din pull-anmodningsbeskrivelse. Dette vil medføre, at problemet

automatisk lukkes, når pull-anmodningen flettes. Du kan henvise til andre diskussioner, problemer eller pull-anmodninger ved hjælp af den samme #1234 syntaks. Du kan henvise til et problem i et andet repository ved at sætte et - foran nummeret – for eksempel vil python/cpython#1234 henvise til problem 1234 i CPython-repositoryet.

Kontinuerlig integration

Kontinuerlig integration, eller CI, er processen med at køre automatiserede kontroller på din pull-anmodning. Dette kan omfatte enkle kontroller, såsom at sikre, at koden er korrekt formateret, men det omfatter også at køre testsuiten og oprette dokumentation.

Der er mange ændringer, der kan føre til CI-fejl. Generelt set vil vi ikke gennemgå en PR, der ikke passerer CI. Hvis du opretter en pull-anmodning, og CI fejler, vil vi ikke påbegynde din gennemgang, før den passerer. Hvis dine ændringer resulterer i en fejl, er det dit ansvar at undersøge årsagen og løse problemet.

Når CI fejler, vises fejllinkene nederst på PR-siden under overskriften "Nogle kontroller var ikke vellykkede". Du vil se en liste over fejlbehæftede kontroller, som vil blive vist øverst på listen over alle kontroller, hvis der også er kontroller, der er bestået. Hvis du klikker på fejllinket, vil du blive ført til loggen. Loggen indeholder ofte alle de oplysninger, du har brug for for at finde ud af, hvad der forårsagede fejlen. Læs loggen igennem og prøv at finde ud af, hvorfor fejlen opstår, og gør derefter det nødvendige for at løse den.

Lejlighedsvis vil en CI-kontrol mislykkes af årsager, der ikke har noget at gøre med dine ændringer. Dette kan skyldes et problem på den maskine, der kører CI-kontrollen, eller fordi en CI-kontrol er ustabil. Hvis du ser en fejl, og du er temmelig sikker på, at den ikke har noget at gøre med dine ændringer, skal du tilføje en kommentar til din PR om dette, så vil vi undersøge det.

For at udløse en ny CI-kørsel skal du overføre nye ændringer til din gren.

Hvis du befinder dig i en situation, hvor du har brug for hjælp til at få CI til at bestå, så skriv en kommentar på PR og lad os det vide, så vil vi gøre vores bedste for at hjælpe.

Kontrollen af pre-commit og towncrier

Hvis enten pre-commit eller towncrier kontrollen fejler, vil det blokere for, at de fleste af de øvrige CI-kontroller kan køres. Du skal løse de relevante problemer, før det fulde sæt af kontroller kan køres.

Vi har begrænsede CI-ressourcer. Det er vigtigt at forstå, at CI starter hver gang du pusher til grenen. Hvis du skal foretage en række ændringer, er det bedre at foretage disse ændringer lokalt og pushe dem alle på én gang. CI kører kun på den seneste commit i en batch, hvilket minimerer belastningen på vores CI-system.

Processen med at indsende din PR er ikke afsluttet, før den har bestået CI, eller du kan give en forklaring på, hvorfor den ikke har bestået.

Din pull-anmodning kan kræve yderligere indhold, såsom en ændringsnote, før den kan gennemgås.