Indsendelse af et nyt problem¶

At skrive en god fejlrapport kan gøre hele forskellen, når det gælder om at løse et problem. Her er en guide til, hvordan du indsender en god fejlrapport til BeeWare.

Søg efter eksisterende problemer¶

Inden du indsender et nyt problem, skal du søge i indekset efter eksisterende problemer, der matcher dit eget. Hvis der findes et eksisterende åbent problem, der synes at matche dit problem, skal du tilføje en kommentar til det pågældende problem med yderligere oplysninger om din oplevelse. Hvis du f.eks. oplever problemet på en anden Python-version eller et andet operativsystem, kan disse yderligere oplysninger være nyttige til at fastslå problemets omfang eller årsag.

Hvis du finder et lukket problem, der synes at matche dit problem, skal du kontrollere, hvor nyligt problemet blev lukket. Hvis problemet blev lukket for nylig, betyder det sandsynligvis, at din fejl er blevet rettet og vil blive korrigeret i den næste udgivelse. Hvis problemet blev lukket for mere end 4 måneder siden, er det sandsynligt, at det, du oplever, er et andet problem – uanset hvor ens fejlmeddelelsen måtte synes at være.

Hvis du ikke finder et problem, der svarer til det, du ser, kan det være en god idé at oprette et nyt problem.

Start med en diskussion¶

Før du indsender et problem på GitHub, bør du overveje at starte med en diskussion for at spørge, om det, du oplever, faktisk er en fejl eller et problem med din opsætning eller proces. Medmindre du ser en adfærd, der er i direkte modstrid med den dokumenterede adfærd, er det sandsynligvis en god idé at stille et spørgsmål, før du går direkte til at indsende en fejlrapport. Hvis det viser sig, at du har fundet et problem, kan et diskussionsemne nemt omdannes til et problem.

At starte en diskussion kan også hjælpe med at sikre, at du rapporterer et problem det bedste sted. Selvom du måske har oplevet et problem, mens du brugte BeeWare, kan problemet være forårsaget af en fejl i et andet projekt i BeeWare-økosystemet.

Skrivning af en god fejlrapport¶

Hvis et nyt problem er nødvendigt, er det vigtigt at give så mange detaljer som muligt. En god fejlrapport indeholder alle oplysninger, der potentielt kan have relation til fejlen, samt det mindst mulige eksempel på reproduktion.

Reproduktionseksemplet skal være så kort og præcist som muligt, samtidig med at det stadig viser fejlen. Et omfattende eksempel gør det betydeligt sværere at fejlfinde, især hvis det er afhængigt af andre biblioteker eller kræver omfattende viden om den forventede adfærd eller interne logik i eksemplet.

Vi har brug for så mange detaljer som muligt. Dette omfatter, men er bestemt ikke begrænset til:

Din operativsystemversion – ned til mikroversionen (for eksempel macOS 15.7.2).
Din Python-version, også ned til mikroversionen (for eksempel 3.14.1).
Hvordan installerede du Python? Downloadede du det fra python.org? Brugte du Homebrew? uv? pyenv? conda? Noget andet?
Den specifikke version af BeeWare-værktøjerne, du bruger (for eksempel Toga 0.5.3). Hvis du bruger en udviklingsversion, hvilken Git-hash bruger du? Det er ikke nok at sige "den aktuelle hovedgren", fordi den kan ændre sig dagligt.
De specifikke versioner af andre pakker, der skal installeres for at udløse problemet. Du kan inkludere resultaterne af at køre python -m pip freeze for at give disse oplysninger.
Hvis der er genereret en logfil, skal hele logfilen vedhæftes.
Hvis der er genereret et stack trace, skal du angive hele stack trace. Angiv ikke kun den endelige fejlmeddelelse – det er vigtigt at angive hele konteksten for stack trace. Det er også bedst at angive dette i tekstformat og ikke som et skærmbillede.
Er der andet ved din computer eller netværksopsætning, der kan have indflydelse på problemet? Er din computer ældre eller langsommere? Er det en arbejdscomputer, der muligvis har firewalls, viruscheckere eller andre begrænsninger? Er dit netværk særligt langsomt? Kører du dit operativsystem med usædvanlige systemindstillinger (f.eks. en meget stor skriftstørrelse eller anden hjælpende teknologi aktiveret)?

Prøv at tænke ud af boksen og medtag alt, hvad du kan komme i tanke om, der kan have indflydelse på det problem, du oplever. Hvis du giver os mere, end vi har brug for, kan vi nemt ignorere det, vi ikke har brug for. Vi kan ikke finde på noget, du har udeladt.

Et minimalt eksempel¶

Den vigtigste del af en fejlrapport er et minimalt reproduktionsscenario. Det skal være muligt for en tredjepart at læse instruktionerne til dit reproduktionsscenario, følge disse instruktioner og observere det samme problem. Dette kan betyde, at du skal levere et eksempelprojekt, der viser problemet – eller, endnu bedre, bruge et eksisterende eksempel (f.eks. en tutorial eller et eksempelprojekt, der er en del af den eksisterende kodebase).

Dit fulde projekt er ikke et minimalt reproduktionscase. Et minimalt reproduktionscase bør ikke indeholde kode, der ikke er absolut nødvendig for at skabe et problem. Vær kompromisløs, når du sammensætter dit reproduktionscase – hvis en knap ikke er nødvendig for at skabe problemet, skal du ikke medtage den knap.

Ofte vil processen med at udvikle dette minimale reproduktionscase afsløre årsagen til problemet, fordi det at skabe det minimale eksempel tvinger dig til at finde ud af, hvad der præcist forårsager problemet, uanset om det er en fejl i koden eller skyldes forkerte antagelser eller API-brug.

Du bør også være eksplicit i alle reproduktionsinstruktioner. At sige "Luk eksempelappen" kan betyde at klikke på luk-knappen i vinduet, vælge "afslut" i en menu eller skrive Control-C i en terminal. Din rapport bør ikke give anledning til tvetydighed med hensyn til, hvad der skal gøres for at reproducere problemet.

Indsendelse af rapporten¶

Naviger til projektets problemoversigt, klik på knappen "Nyt problem" og vælg "Fejlrapport" for at starte processen.

Du skal udfylde alle felter i skabelonen til problemmeldingen. Vi stiller skabelonen til rådighed som en hjælp til at indtaste de nødvendige oplysninger. Husk, at du altid kan (og bør!) indtaste flere oplysninger, end skabelonen kræver, men vi har som minimum brug for alle de oplysninger, der er angivet i skabelonen.

Når du inkluderer kode, kan du angive et link, hvis du kan gengive den med et eksisterende eksempel, såsom BeeWare-vejledningen. Ellers skal du angive koden i rapporten. Den skal være formateret i Markdown; en kodeblok skal have tre backticks (```) før og efter.

Hvis du har brug for at inkludere en lang tekstblok, kan du gøre den til sammenklappet indhold ved hjælp af følgende syntaks:

<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>

Når du har angivet så mange oplysninger som muligt, skal du klikke på "Opret" for at indsende rapporten.