Brug af værktøjerne¶

En af de mest værdifulde tilbagemeldinger, vi kan få, er fra folk, der prøver at bruge BeeWare-værktøjerne og opdager, at der er et problem eller en manglende funktion. Det er utroligt nyttigt for os at forstå de vanskeligheder, du måtte opleve, når du bruger værktøjerne i praksis.

Tænk på det, du altid har ønsket at bygge, og prøv at bygge det. Hvis det viser sig, at du er i stand til at gennemføre dit projekt, så tillykke! Du har nu det, du altid har ønsket dig.

Hvis det ikke lykkes, så lad os vide, hvad der gik galt. Manglede der en funktion? Er dokumentationen forvirrende eller mangelfuld på nogle punkter? Når du deler din oplevelse, giver du os værdifuld indsigt, som vi kan bruge til at forme vores planlægningsproces.

Hvis du oplever problemer, skal du oprette et nyt diskussionsemne, da det kan være starten på et nyt problem eller et forslag til en ny funktion.

Brug af bidragsværktøj¶

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

Foreslå en ny funktion

Så du har en idé til en forbedring af BeeWare – hvordan indsender du den idé til overvejelse?

Gør din research¶

Det første skridt er at søge i BeeWare issue tracker efter eksisterende feature issues (issues tagged "enhancement"), documentation issues (issues tagged "documentation"), eller Discussion threads for at se, om ideen er blevet foreslået før. Hvis det er tilfældet, og du har nye kontekster eller ideer at tilføje, skal du inkludere dem i den eksisterende tråd. Hvis du ønsker hjælp til din research, kan du spørge i #dev-kanalen på BeeWare Discord. Vi kan muligvis henvise dig til eksisterende tråde, give dig kontekst, som du måske ikke er opmærksom på, eller forbinde din idé med en anden idé, der måske ikke umiddelbart virker relateret.

Diskuter ideen¶

Hvis du ikke finder nogen eksisterende referencer til din idé, skal du starte en diskussionstråd. Giv en overordnet beskrivelse af formålet med og anvendelsesmulighederne for din idé. Inkluder eventuelle tanker om, hvordan funktionen vil se ud, hvis den implementeres, f.eks. den generelle form af en API, det visuelle udseende af en funktion eller det dokument, der vil blive tilføjet. Hvis det er relevant, bør du også medtage eventuelle undersøgelser, du har foretaget af, hvordan din idé ville manifestere sig på forskellige platforme.

Når diskussionstråden er åbnet, vil BeeWare-teamet og resten af fællesskabet svare. Kerneteamet vil forsøge at give et første indtryk af din idé inden for to hverdage. Hvis en idé er særlig kompleks, kan en mere detaljeret analyse tage op til en uge. Begivenheder som helligdage og konferencer kan medføre, at disse tidsfrister bliver lidt længere.

Dette er din mulighed for at deltage i en samtale om din idé. Vi kan bede om flere detaljer eller baggrundsinformation. Andre medlemmer af fællesskabet kan også deltage i diskussionen og bidrage med andre perspektiver, forslag eller modforslag. Resultatet af denne diskussion vil afgøre de næste skridt.

Det er vigtigt at forstå, at ikke alle ideer vil blive accepteret. Grunden til, at denne proces starter med et forslag, er for at undgå, at du lægger alt arbejdet i det, kun for at finde ud af, at der er en grund til, at din ændring ikke vil blive accepteret.

Det betyder ikke, at det ikke var en god idé! Der kan være tekniske årsager til, at den ikke kan implementeres. For eksempel kan vi afvise en idé, hvis:

Det ville være vanskeligt eller umuligt at implementere pålideligt på alle understøttede platforme; eller
Det ville være vanskeligt at vedligeholde, eller vedligeholdelse ville kræve adgang til teknologi eller software, der ikke er bredt tilgængelig; eller
Det betjener en nichepublikum, men påfører andre brugere betydelige omkostninger.

Hvis vi vurderer, at din idé ikke passer ind, betyder det ikke nødvendigvis, at du skal opgive den. Selvom vi måske afviser en specifik idé, kan vi være meget mere åbne over for at tilføje et plugin-interface eller et andet udvidelsespunkt, der giver dig mulighed for at bevare den samme funktion som et eksternt bibliotek. På den måde kan du få funktionen, men uden de specifikke vedligeholdelsesproblemer eller begrænsninger, der kan blive en hindring for selve projektet.

Konverter til en formel funktionsanmodning¶

Når diskussionen har nået enighed om formen af en funktion, kan du oprette en ny funktionsanmodning i BeeWare issue tracker, der opsummerer diskussionen og linker til diskussionen for at give kontekst.

Du behøver ikke selv implementere dit forslag til en funktion; du kan oprette en sag med detaljer om dit forslag. Men det er ikke sikkert, at dit forslag bliver implementeret, bare fordi du opretter en sag. Du skal vente på, at det potentielt bliver taget op af en anden, der er interesseret i den samme funktion, uanset om det er et andet medlem af communityet eller kerneteamet; det er dog ikke garanteret, at det sker. Hvis du vil have garanti for implementeringen, skal du selv implementere den eller betale en anden for at implementere den for dig.