Løsning af et problem

BeeWare holder styr på en liste over kendte problemer. Alle disse problemer er kandidater til at blive løst.

Denne liste kan filtreres på forskellige måder. Du kan f.eks. filtrere efter platform, så du kan fokusere på problemer, der påvirker de platforme, du kan teste på, eller du kan filtrere efter problemtype, f.eks. dokumentationsfejl. Der er også et filter for gode første problemer – dette er problemer, der er blevet identificeret som problemer med en kendt årsag, og vi mener, at løsningen burde være relativt ligetil (selvom vi måske tager fejl i vores analyse).

Hvis et problem er mere end 6 måneder gammelt, er det meget muligt, at problemet er blevet løst, så det første skridt er at kontrollere, om du kan genskabe problemet. Brug oplysningerne i fejlrapporten til at forsøge at genskabe problemet. Hvis du ikke kan genskabe problemet, skal du rapportere det, du har fundet, som en kommentar til problemet og vælge et andet problem.

Hvis du kan genskabe problemet, så prøv at løse det! Find ud af, hvilken kombination af kode der implementerer funktionen, og se, om du kan finde ud af, hvad der ikke fungerer korrekt.

Selvom du ikke kan løse problemet, er det værd at rapportere alt, hvad du opdager undervejs, som en kommentar til problemet. Hvis du kan finde årsagen til problemet, men ikke løsningen, vil den viden ofte være nok for en person, der ved mere om platformen, til at løse problemet. Hvis problemet ikke allerede giver et godt reproduktionscase (en lille eksempelapp, der ikke gør andet end at reproducere problemet), kan det være en stor hjælp at levere et.

Bidrag til en fejlrettelse

Opsæt et udviklingsmiljø

For at bidrage til BeeWare skal du oprette et udviklingsmiljø.

Forudsætninger

Du skal installere følgende forudsætninger.

macOSLinuxWindows

BeeWare kræver Python 3.10+. Du skal også bruge en metode til at administrere virtuelle miljøer (f.eks. venv).

Du kan kontrollere den version af Python, du har installeret, ved at køre:

Python 3.8.10 (standard, 20. juli 2020, 16:16:00)

Hvis du har mere end én version af Python installeret, skal du muligvis erstatte python3 med et specifikt versionsnummer (f.eks. python3.13)

Vi anbefaler at undgå den seneste version af Python (dvs. versioner med et ".0" eller ".1" mikroversionsnummer, som f.eks. 3.14.0). Dette skyldes, at de værktøjer, der er nødvendige for at understøtte Python på macOS, ofte ikke er tilgængelige for de seneste stabile Python-versioner.

BeeWare kræver Python 3.10+. Du skal også bruge en metode til at administrere virtuelle miljøer (f.eks. venv).

Du kan kontrollere den version af Python, du har installeret, ved at køre:

Python 3.8.10 (standard, 20. juli 2020, 16:16:00)

Hvis du har mere end én version af Python installeret, skal du muligvis erstatte python3 med et specifikt versionsnummer (f.eks. python3.13)

Vi anbefaler at undgå den seneste version af Python (dvs. versioner med et ".0" eller ".1" mikroversionsnummer, som f.eks. 3.14.0). Dette skyldes, at de værktøjer, der er nødvendige for at understøtte Python på Linux, ofte er forsinkede og normalt ikke er tilgængelige for de seneste stabile Python-versioner.

BeeWare kræver Python 3.10+. Du skal også bruge en metode til at administrere virtuelle miljøer (f.eks. venv).

Du kan kontrollere den version af Python, du har installeret, ved at køre:

C:\...>py -3 --version

Hvis du har mere end én version af Python installeret, skal du muligvis erstatte -3 med et specifikt versionsnummer (f.eks. -python3.13)

Vi anbefaler at undgå nyligt udgivne versioner af Python (dvs. versioner med et ".0" eller ".1" mikroversionsnummer, som f.eks. 3.14.0). Dette skyldes, at de værktøjer, der er nødvendige for at understøtte Python på Windows, ofte er forsinkede og normalt ikke er tilgængelige for nyligt udgivne stabile Python-versioner.

Opsæt dit udviklingsmiljø

Den anbefalede måde at opsætte dit udviklingsmiljø til BeeWare er at bruge et virtuelt miljø, og derefter installere udviklingsversionen af BeeWare og dens afhængigheder.

Klon BeeWare repositoryet

Gå derefter til BeeWare siden på GitHub, og hvis du ikke allerede har gjort det, skal du forke repositoryet til din egen konto. Klik derefter på knappen "<> Code" på din fork. Hvis du har GitHub-desktopapplikationen installeret på din computer, kan du vælge "Open with GitHub Desktop" (Åbn med GitHub Desktop). Ellers skal du kopiere den angivne HTTPS-URL og bruge den til at klone repositoryet til din computer ved hjælp af kommandolinjen:

macOSLinuxWindows

Fork BeeWare repositoryet, og derefter:

$ git clone https://github.com/<dit brugernavn>/beeware.git

(erstatt dit GitHub-brugernavn)

Fork BeeWare repositoryet, og derefter:

$ git clone https://github.com/<dit brugernavn>/beeware.git

(erstatt dit GitHub-brugernavn)

Fork BeeWare repositoryet, og derefter:

C:\...>git clone https://github.com/<dit brugernavn>/beeware.git

(erstatt dit GitHub-brugernavn)

Indstil et upstream-repository

Når du har klonet din fork, skal du tilføje BeeWare-repositoriet som en upstream remote. Dette giver din lokale klon en reference til det originale repository, hvilket gør det nemmere at synkronisere opdateringer over tid.

Du skal også bruge tags fra upstream, så værktøjer som Toga og Briefcase kan finde de nøjagtige versionsnumre:

macOSLinuxWindows

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

Hvis du ønsker, at din fork også skal indeholde disse tags, kan du pushe dem:

$ git push --tags

Dette kan være nyttigt, hvis du senere opretter en ny klon og ønsker, at tags skal være tilgængelige fra din fork.

Opret et virtuelt miljø

For at oprette et virtuelt miljø og opgradere pip, skal du køre:

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Din prompt bør nu have et (.venv) præfiks foran sig.

Installer BeeWare

Nu hvor du har kildekoden, kan du foretage en redigerbar installation af BeeWare i dit udviklingsmiljø. Kør følgende kommando:

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Aktivér pre-commit

BeeWare bruger et værktøj kaldet pre-commit til at identificere enkle problemer og standardisere kodeformatering. Det gør det ved at installere en git-hook, der automatisk kører en række kode-linters, inden en git-commit færdiggøres. For at aktivere pre-commit skal du køre:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Nu er du klar til at begynde at hacke på BeeWare!

Arbejd fra en filial

Før du begynder at arbejde på din ændring, skal du sikre dig, at du har oprettet en gren. Når du kloner din repository-fork, bliver du som standard tjekket ud på din main gren. Dette er en direkte kopi af BeeWare grenen.

Selvom du kan indsende en pull-anmodning fra din main gren, er det at foretrække, at du ikke gør dette. Hvis du indsender en pull-anmodning, der er næsten korrekt, kan det centrale teammedlem, der gennemgår din pull-anmodning, muligvis foretage de nødvendige ændringer i stedet for at give feedback med anmodning om en mindre ændring. Hvis du imidlertid indsender din pull-anmodning fra din main gren, kan gennemgangere ikke foretage ændringer.

At arbejde ud fra din hovedgren gør det også vanskeligt for dig, når du har afsluttet din første pull-anmodning. Hvis du vil arbejde på en anden pull-anmodning, skal du have en "ren" kopi af upstream-projektets hovedgren, som du kan basere dit andet bidrag på. Hvis du har lavet dit første bidrag fra din main gren, har du ikke længere den rene version til rådighed.

I stedet bør du foretage dine ændringer på en feature branch. En feature branch har et simpelt navn, der identificerer den ændring, du har foretaget. Hvis du f.eks. retter en fejl, der forårsager build-problemer på Windows 11, kan du oprette en feature branch fix-win11-build. Hvis din fejl vedrører et specifikt problem, der er blevet rapporteret, er det også almindeligt at henvise til det pågældende problemnummer i branch-navnet (f.eks. fix-1234).

For at oprette en fix-win11-build feature-gren skal du køre:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

Gengiv problemet

Du kan ikke løse et problem, hvis du ikke har problemet i første omgang. Derfor er det en forudsætning for at løse problemet, at det kan gengives. I software betegnes problemer ofte som "bugs", og problemer kaldes ofte "bugrapporter".

Nogen har indsendt en fejlrapport. Du skal kontrollere, at de trin, som rapportøren beskriver, resulterer i den fejl, der rapporteres. Kan du gengive det samme resultat ved at gøre nøjagtigt det, der er beskrevet i rapporten? Hvis du ikke kan, skal du finde ud af hvorfor.

Fejl i koden

I en ideel situation har du samme opsætning som den person, der har rapporteret fejlen, du følger trinene, og du kan gengive fejlen som beskrevet. I mange tilfælde er det dog ikke så ligetil. Mange fejlrapporter indeholder kun vage forklaringer og en række vage betingelser. Problemet er, at mange fejl varierer afhængigt af de involverede betingelser, herunder hvordan de interagerer, forskellige forudsætninger, operativsystem, operativsystemversion, CPU-arkitektur, eller om brugerens maskine er gammel og langsom eller ny og hurtig. Jo flere oplysninger vi har om situationen omkring fejlen, jo bedre. Forsøg at genskabe de betingelser, som rapportøren har angivet. Hvis du ikke er i stand til det, kan det næste skridt være at anmode om flere oplysninger fra den person, der har rapporteret fejlen.

Den bedste måde at gengive en fejl på er med det mindst mulige eksempel, der stadig viser problemet. Oftest giver rapporterende personer ikke et minimalt brugbart eksempel; hvis de overhovedet giver et eksempel, vil det være kopieret direkte fra deres "virkelige" applikation. Dit mål vil være at reducere rapporten til den mest enkle form, der viser problemet. Den bedste reproduktionssag er det mindst mulige program. Denne reduktion er i sig selv nyttig, fordi den bestemmer, hvad det egentlige problem er. Alle kan tage det minimale eksempel, køre det og observere den beskrevne fejl.

Fejl i dokumentationen

Fejl i dokumentationen kan manifestere sig på forskellige måder. Der kan være problemer med formateringen, som medfører problemer med gengivelsen. Nogle gange er det ikke engang en fejl; personen har måske misforstået dokumentationen eller begået en ægte fejl. Det betyder ikke nødvendigvis, at der ikke er noget problem med dokumentationen. Indholdet kan være uklart eller upræcist, hvilket giver plads til forvirring eller fejlagtig fortolkning. Det er muligt, at et koncept, der burde diskuteres, ikke bliver det, fordi det er fuldstændig udokumenteret.

Når der indberettes en fejl vedrørende et dokumentationsproblem, skal du kontrollere, at det indberettede problem stadig eksisterer. I tilfælde af gengivelsesproblemer skal du oprette dokumentationen for at se, om du kan gengive problemet. Indholdsproblemer skal læses igennem for at kontrollere, at ingen har indsendt en opdatering.

Opdater problemet

Det sidste trin i triageprocessen er at dokumentere dine fund ved at skrive en kommentar til problemet.

Hvis du kan gengive problemet nøjagtigt som beskrevet, er det alt, du behøver at sige. Skriv en kommentar om, at du har bekræftet, at du oplever det samme problem, præcis som den oprindelige rapporterende person beskriver det.

Hvis du kan give yderligere kontekst, skal du medtage detaljer om denne kontekst. Dette kan omfatte muligheden for at gengive problemet på et andet operativsystem eller med en anden version af noget af den involverede software eller noget andet, der adskiller sig fra den oprindelige rapport.

Hvis den oprindelige rapport manglede detaljer, som du havde brug for for at kunne gengive rapporten, skal du medtage disse detaljer. Dette kan omfatte oplysninger om operativsystem eller version, som den oprindelige rapport ikke indeholdt, mere komplette logfiler eller stack traces eller klarere instruktioner om den nøjagtige rækkefølge af handlinger, der er nødvendige for at gengive problemet. Hvis du har udviklet en enklere måde at gengive problemet på (eller hvis den oprindelige rapporterende ikke har angivet et reproduktionsscenario), kan du medtage detaljer om denne reproduktionsmetode.

Hvis du ikke kan gengive problemet, skal du også skrive en kommentar, hvor du beskriver, hvad du har prøvet. Det er næsten lige så vigtigt at vide, hvor et problem ikke findes, som at vide, hvor det findes, fordi det hjælper med at indsnævre en mulig årsag. Hvis du har nogen teorier om, hvorfor du ikke kan genskabe problemet – for eksempel hvis du tror, det er en fejl i brugen, eller at problemet er blevet løst ved en nylig opdatering af operativsystemet – så medtag den spekulation i din kommentar.

Til sidst kan du give eventuelle anbefalinger til kerneteamet. Hvis du mener, at den oprindelige rapport er forkert, kan du foreslå, at sagen lukkes. Hvis du har en teori om årsagen til problemet, kan du også foreslå den. Dine kommentarer vil hjælpe kerneteamet med at finde ud af, hvordan sagen kan føres videre til næste trin.

Hvis løsningen af problemet kræver ændringer i koden:

Skriv, kør og test kode

Hvis du skal rette en fejl eller implementere en ny funktion, bliver du nødt til at skrive noget nyt kode.

Vi har en kodestilguide, der beskriver vores retningslinjer for at skrive kode til BeeWare.

Testdrevet udvikling

En god måde at sikre sig på, at din kode kommer til at fungere som forventet, er først at skrive et testscenarie til at teste den. Dette testscenarie bør i første omgang mislykkes, da den kode, det tester, endnu ikke findes. Derefter kan du foretage de nødvendige ændringer i koden, så testen består, og dermed vide, at det, du har skrevet, løser det problem, du havde forventet.

Kør din kode

Når du har skrevet din kode, skal du sikre dig, at den fungerer. Du skal køre koden manuelt for at kontrollere, at den opfører sig som forventet. Hvis du ikke allerede har gjort det, bør du skrive en testcase for dine ændringer; som nævnt ovenfor skal denne test mislykkes, hvis koden er kommenteret ud eller mangler.

Du skal tilføje din testtilfælde til testsuiten, så den kan køres sammen med de øvrige tests. Det næste trin er at køre testsuiten.

Kører test og dækning

BeeWare bruger tox til at styre testprocessen og pytest til sin egen testsuite.

Standardkommandoen tox omfatter følgende:

• pre-commit-hooks
• towncrier kontrol af udgivelsesnoter

• kontrol af dokumentation

• testsuite til tilgængelige Python-versioner

• rapportering af kodedækning

Det er i alt væsentligt det, som CI kører, når du indsender en pull-anmodning.

For at køre hele testsuiten skal du skrive:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

Det kan tage et stykke tid at køre den fulde testsuite. Du kan gøre det betydeligt hurtigere ved at køre tox parallelt, ved at køre tox p (eller tox run-parallel). Når du kører testsuiten parallelt, får du mindre feedback om testsuitenes fremskridt undervejs, men du får stadig en oversigt over eventuelle fundne problemer ved afslutningen af testkørslen. Du bør få en udskrift, der viser, at testene er blevet kørt. Du kan muligvis se SKIPPED test, men bør aldrig få nogen FAIL eller ERROR testresultater. Vi kører vores fulde testsuite, før vi fletter hver patch. Hvis denne proces opdager problemer, fletter vi ikke patchen. Hvis du finder en testfejl eller et testsvigt, er der enten noget mærkeligt i dit testmiljø, eller også har du fundet et grænsetilfælde, som vi ikke har set før – uanset hvad, så lad os det vide!

Ud over at testene er bestået, bør dette vise 100 % testdækning.

Kørsel af testvarianter

Kør test for flere versioner af Python

Som standard vil mange af tox-kommandoerne forsøge at køre testsuiten flere gange, én gang for hver Python-version, der understøttes af BeeWare. For at dette skal lykkes, skal hver af disse Python-versioner dog være installeret på din computer og tilgængelig for tox-programmets Python-discovery-proces. Generelt gælder det, at hvis en Python-version er tilgængelig via PATH, bør tox kunne finde og bruge den.

Kør kun testsuiten

Hvis du arbejder hurtigt med en ny funktion, behøver du ikke køre hele testsuiten; du kan nøjes med kun at køre enhedstestene. For at gøre dette skal du køre:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Kør en delmængde af testene

Som standard kører tox alle testene i enhedstestsuiten. Når du udvikler en ny test, kan det være nyttigt at køre kun den ene test. For at gøre dette kan du angive en hvilken som helst pytest specifikator som et argument til tox. Disse teststier er relative i forhold til briefcase-mappen. Hvis du f.eks. kun vil køre testene i en enkelt fil, skal du køre:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

Du får stadig en dækningsrapport, når du kører en del af testsuiten – men dækningsresultaterne vil kun vise de kodelinjer, der blev udført af de specifikke tests, du kørte.

Kør testsuiten for en bestemt Python-version

Som standard kører tox -e py med den fortolker, der identificeres som python på din computer. Hvis du har flere Python-versioner installeret og ønsker at teste en bestemt version blandt de installerede, kan du angive, hvilken Python-version der skal bruges. Hvis du f.eks. vil køre testsuiten på Python 3.10, skal du køre følgende:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

En delmængde af test kan køres ved at tilføje -- og en testspecifikation til kommandolinjen.

Kør testsuiten uden dækning (hurtigt)

Som standard kører tox pytest-testsuiten i enkeltrådet tilstand. Du kan gøre udførelsen af testsuiten hurtigere ved at køre den parallelt. Denne tilstand genererer ikke dækningsfiler på grund af de tekniske udfordringer, der er forbundet med at registrere dækning i de oprettede processer. For at køre en enkelt Python-version i "hurtig" tilstand skal du køre:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

En delmængde af test kan køres ved at tilføje -- og en testspecifikation til kommandolinjen; en bestemt Python-version kan anvendes ved at tilføje versionen til testmålet (f.eks. py310-fast for at køre fast på Python 3.10).

Kodedækning

BeeWare opretholder 100 % testdækning i sin kodebase. Når du tilføjer eller ændrer kode i projektet, skal du tilføje testkode for at sikre, at alle ændringer, du foretager, bliver testet.

Imidlertid er BeeWare beregnet til flere platforme samt flere versioner af Python, så det er ikke muligt at verificere fuld dækning på en enkelt platform og Python-version. For at imødekomme dette er der defineret flere betingede dækningsregler i tool.coverage.coverage_conditional_plugin.rules-sektionen af pyproject.toml (f.eks. kan no-cover-if-is-windows bruges til at markere en kodeblok, der ikke vil blive udført, når testsuiten køres på Windows). Disse regler bruges til at identificere kodestykker, der kun er dækket på bestemte platforme eller Python-versioner.

Det er værd at bemærke, at dækningsrapportering på tværs af Python-versioner kan være lidt uforudsigelig. Hvis dækningsfilerne f.eks. genereres ved hjælp af én Python-version, men dækningsrapporteringen udføres på en anden, kan rapporten indeholde falske positive resultater for oversete forgreninger. Af denne grund bør dækningsrapporteringen altid baseres på den ældste Python-version, der blev brugt til at generere dækningsfilerne.

Forståelse af dækningsresultater

I slutningen af dækningsprøvens output bør der være en rapport over de indsamlede dækningsdata:

Navn    Stmts   Miss Branch BrPart   Dækning   Mangler
 ---------------------------------------------------
 I ALT    7540 0   1040 0  100,0 %

Dette fortæller os, at testsuiten har gennemgået alle mulige forgreningsveje i koden. Det er ikke en 100 % garanti for, at der ikke er fejl, men det betyder, at vi tester hver eneste kodelinje i kodebasen.

Hvis du foretager ændringer i kodebasen, kan der opstå et hul i dækningen. Når det sker, vil dækningsrapporten vise dig, hvilke linjer der ikke udføres. Lad os for eksempel sige, at vi har ændret some/interesting_file.py og tilføjet noget nyt logik. Dækningsrapporten kan se sådan ud:

Navn Stmts   Miss Branch BrPart  Cover   Mangler
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1 %   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 I ALT 7540 1   1726 0  99,9 %

Dette viser, at linje 170, linjerne 302–307 samt et spring fra linje 320 til linje 335 ikke udføres af testsuiten. Du skal tilføje nye tests (eller ændre en eksisterende test) for at genoprette denne dækning.

Rapport om dækning for værtsplatform og Python-version

Du kan generere en dækningsrapport for din platform og version af Python. Hvis du f.eks. vil køre testsuiten og generere en dækningsrapport for Python 3.10, skal du køre følgende kommando:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Dækningsrapport for værtsplatformen

Hvis alle understøttede versioner af Python er tilgængelige for tox, kan dækningen for værtsplatformen rapporteres ved at køre:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Rapportering af dækning i HTML

Der kan genereres en HTML-dækningsrapport ved at tilføje -html til et hvilket som helst af dækningsmiljønavnene tox, for eksempel:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Det handler ikke kun om at skrive tests!

Selvom vi sørger for at teste al vores kode, handler opgaven ikke kun om at opretholde det testniveau. En del af opgaven består i at gennemgå koden undervejs. Man kunne godt skrive et omfattende sæt tests til en konkret redningsvest… men en konkret redningsvest ville stadig være ubrugelig til det formål, den var beregnet til!

Når du udvikler test, bør du også kontrollere, at kernemodulet er konsistent internt. Hvis du bemærker metodernavne, der ikke er internt konsistente (f.eks. noget, der hedder on_select i et modul, men on_selected i et andet), eller hvor dataene ikke håndteres konsistent, skal du markere det og gøre os opmærksom på det ved at oprette en ticket. Eller, hvis du er sikker på, at du ved, hvad der skal gøres, kan du oprette en pull-anmodning, der løser det problem, du har fundet.

Hvis løsningen af problemet kræver ændringer i dokumentationen:

Opbyg dokumentation

Inden du foretager ændringer i BeeWares dokumentation, er det en god idé at kontrollere, at du kan oprette den eksisterende dokumentation.

Du skal have en Python 3.13 fortolker installeret og tilgængelig på din sti (dvs. python3.13 skal starte en Python 3.13 fortolker).

BeeWare bruger tox til at oprette dokumentation. Følgende tox kommandoer skal køres fra samme placering som tox.ini filen, som findes i projektets rodmappe.

Live dokumentationsforhåndsvisning

For at understøtte hurtig redigering af dokumentation har BeeWare en "live preview"-tilstand.

Live-previewet vil blive opbygget med advarsler!

Live-serveren er tilgængelig til iteration af dine dokumentopdateringer. Mens du er i gang med at opdatere ting, kan du støde på et markup-problem. Problemer, der betragtes som WARNING, vil medføre, at en standardbuild mislykkes, men live-serveren er indstillet til at vise advarsler i konsoloutputtet, mens den fortsætter med at bygge. Dette giver dig mulighed for at iterere uden at skulle genstarte live-previewet.

En WARNING er forskellig fra en ERROR. Hvis du introducerer et problem, der betragtes som en ERROR, vil live-serveren fejle og kræve en genstart. Den vil ikke starte op igen, før WARNING problemet er løst.

Sådan starter du live-serveren:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Dette vil opbygge dokumentationen, starte en webserver til at servere dokumentationen og overvåge filsystemet for eventuelle ændringer i dokumentationskilden.

Når serveren er startet, vil du se noget lignende følgende i konsoludskriften:

INFO    -  [11:18:51] Serveres på http://127.0.0.1:8000/

Åbn en browser, og naviger til den angivne URL. Nu kan du begynde at gentage dokumentationen. Hvis der registreres en ændring, genopbygges dokumentationen, og alle browsere, der viser den ændrede side, opdateres automatisk.

docs-live er et første skridt

Kørsel af docs-live for at arbejde med live-serveren er beregnet til indledende iteration. Du bør altid køre en lokal build, før du indsender en pull-anmodning.

Lokal opbygning

Når du er færdig med iterationen, skal du foretage en lokal kompilering af dokumentationen. Denne kompileringsproces er designet til at mislykkes, hvis der er problemer med markeringen. Dette giver dig mulighed for at fange alt, hvad du måtte have overset med live-serveren.

Generering af en lokal build

For at generere en lokal build:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

Outputtet fra denne build vil være i _build -mappen i projektets rodmappe.

Generering af en lokal oversat build

BeeWare's dokumentation er oversat til flere sprog. Opdateringer af den engelske dokumentation kan potentielt medføre problemer i de andre sprogversioner. Det er vigtigt at kontrollere, at alle versioner fungerer, inden der indsendes en pull-anmodning.

For at generere en build af alle tilgængelige oversættelser:

macOSLinuxWindows

(verbum) $ tox -e docs-all

(verbum) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

Outputtet fra hver sprogversion vil være i det tilknyttede _build/html/<languagecode> bibliotek, hvor <languagecode> er den to- eller fem-tegnede sprogkode, der er tilknyttet det specifikke sprog (f.eks. fr for fransk, it for italiensk osv.).

Hvis du finder et problem med en enkelt build, kan du køre den enkelte build separat ved at køre tox -e docs-<languagecode>. For eksempel, for kun at bygge den franske dokumentation, skal du køre:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

Outputtet fra en enkelt-sprogs build vil være i _build mappen.

Dokumentation linting

Build-processen identificerer Markdown-problemer, men BeeWare udfører nogle yderligere kontroller af stil og formatering, også kaldet "linting". Sådan kører du lint-kontrollerne:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

Dette vil bekræfte, at dokumentationen ikke indeholder:

• døde hyperlinks
• stavede ord

Hvis en gyldig stavning af et ord identificeres som forkert stavet, skal du tilføje ordet til listen i docs/spelling_wordlist. Dette vil tilføje ordet til stavekontrollens ordbog. Når du tilføjer til denne liste, skal du huske:

• Vi foretrækker amerikansk stavning, med nogle undtagelser for programmeringsspecifikke slangudtryk (f.eks. "apps") og verbificering af navneord (f.eks. "scrollable").
• Enhver henvisning til et produktnavn skal bruge produktets foretrukne store bogstaver. (f.eks. "macOS", "GTK", "pytest", "Pygame", "PyScript").
• Hvis et udtryk bruges "som kode", skal det angives som en bogstavelig angivelse (like this) i stedet for at blive tilføjet til ordbogen.

Skriv dokumentation

Dette er de trin, du skal følge for at skrive dit dokumentationsbidrag til BeeWare.

Opdatering af eksisterende dokumentation

Hvis du redigerer eksisterende dokumenter, skal du finde filen i /docs/en -mappen. Filstrukturen følger sidestrukturen, så du kan finde filen ved hjælp af dokumentations-URL'en.

Tilføjelse af ny dokumentation

Hvis du tilføjer et nyt dokument, er der et par ekstra trin, du skal følge.

Du skal oprette dokumentet på det relevante sted i docs/en -mappen. For diskussionens skyld antager vi, at du tilføjer et nyt dokument med filnavnet new_doc.md.

Derefter skal du opdatere docs/en/SUMMARY.md filen for at inkludere din nye fil. SUMMARY.md er organiseret, så den grundlæggende afspejler docs/en mappestrukturen, men, hvad der er endnu vigtigere, den bestemmer direkte strukturen i venstre sidepanel. Hvis du finder det afsnit, hvor du ønsker at inkludere new_doc.md, behøver du ikke ændre noget i SUMMARY.md, hvis du ser en wildcard-sti angivet. For eksempel:

- ./sti/til/mappe/*

Hvis det afsnit, hvor du vil indsætte new_doc.md, er en liste over individuelle Markdown-links, skal du tilføje et eksplicit link til dit. For eksempel:

- [Mit nye dokument](new_doc.md)

Skrivning af din dokumentation

Du kan nu åbne den ønskede fil i din editor og begynde at skrive.

Vi har en dokumentationsstilguide, der beskriver vores retningslinjer for skrivning af dokumentation til BeeWare.

Når du er klar til at indsende dit bidrag:

Tilføj en ændringsnote

Mange BeeWare-værktøjer bruger towncrier til at hjælpe med at oprette release notes for hver udgivelse. Når du indsender en pull request til et af de relevante værktøjer, skal den indeholde en ændringsnote - denne ændringsnote bliver en post i release notes, der beskriver den ændring, der er foretaget.

Hver pull-anmodning skal indeholde mindst én fil i changes/ -mappen, der indeholder en kort beskrivelse af den ændring, der implementeres med pull-anmodningen. Ændringsnotatet skal være i Markdown-format i en fil med navnet <id>.<fragment type>.md. Hvis den ændring, du foreslår, vil rette en fejl eller implementere en funktion, for hvilken der findes et eksisterende problemnummer, vil ID'et være nummeret på den pågældende billet. Hvis ændringen ikke har noget tilsvarende problem, kan PR-nummeret bruges som ID. Du kender ikke dette PR-nummer, før du har sendt pull-anmodningen, så den første CI-test vil fejle towncrier -kontrollen. Tilføj ændringsnoten, send en PR-opdatering, og CI bør derefter bestå.

Der er fem fragmenttyper:

• feature: PR tilføjer en ny funktion eller mulighed, der ikke tidligere var mulig (f.eks. tilføjelse af support til et nyt pakkeformat eller en ny funktion i et eksisterende pakkeformat).
• bugfix: PR retter en fejl i den eksisterende implementering.
• doc: PR er en væsentlig forbedring af dokumentationen.
• removal; PR repræsenterer en bagudkompatibel ændring i BeeWare API; eller
• misc; En mindre eller administrativ ændring (f.eks. rettelse af en stavefejl, en mindre sproglig præcisering eller opdatering af en afhængighedsversion), der ikke behøver at blive annonceret i release notes.

Denne beskrivelse i ændringsnotatet skal være en overordnet "markedsføringsmæssig" sammenfatning af ændringen set fra brugerens perspektiv, ikke en dybdegående teknisk beskrivelse eller implementeringsdetaljer. Den adskiller sig fra en commit-besked – en commit-besked beskriver, hvad der er blevet gjort, så fremtidige udviklere kan følge begrundelsen for en ændring; ændringsnotatet er en beskrivelse til gavn for brugerne, som muligvis ikke har kendskab til de interne forhold.

Hvis du f.eks. retter en fejl relateret til projektnavngivning, kan commit-meddelelsen lyde således:

Anvend en strengere regulær udtryk-kontrol for at forhindre projektnavne, der begynder med cifre.

Den tilsvarende ændringsnote ville lyde nogenlunde således:

Projektnavne kan ikke længere begynde med et tal.

Nogle PR'er introducerer flere funktioner og retter flere fejl eller introducerer flere bagudkompatible ændringer. I så fald kan PR'en have flere ændringsnotatfiler. Hvis du har brug for at knytte to fragmenttyper til samme ID, kan du tilføje et numerisk suffiks. Hvis PR 789 f.eks. tilføjede en funktion beskrevet i billet 123, lukkede en fejl beskrevet i billet 234 og også foretog to bagudkompatible ændringer, kan du have 4 ændringsnotatfiler:

• 123.feature.md
• 234.bugfix.md
• 789.removal.1.md
• 789.removal.2.md

For mere information om towncrier og fragmenttyper, se Nyhedsfragmenter. Du kan også se eksisterende eksempler på nyhedsfragmenter i changes mappen i BeeWare repositoryet. Hvis denne mappe er tom, skyldes det sandsynligvis, at BeeWare for nylig har udgivet en ny version; ændringsnotatfiler slettes og kombineres for at opdatere release notes med hver udgivelse. Du kan se den fil for at se, hvilken stil der kræves for kommentarer. Du kan se nylig sammenlagte PR'er for at se, hvordan du formaterer dine ændringsnoter.

Indsend 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:

macOSLinuxWindows

(.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.

macOSLinuxWindows

(.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.

macOSLinuxWindows

(.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.