Tilføjelse af dokumentation¶

Du har måske verdens bedste software – men hvis ingen ved, hvordan man bruger den, hvad nytter den så? Dokumentationen kan altid forbedres – og vi har brug for din hjælp!

Dokumentationsformularer¶

BeeWare's dokumentation er skrevet ved hjælp af MkDocs og Markdown. Vi tilstræber at følge Diataxis-rammen for strukturering af dokumentation.

Diataxis-rammen beskriver fire "former" for dokumentation:

Tutorial - En guidet læringsoplevelse med et specifikt projektmål.
Vejledning - Instruktioner, der vejleder læseren mod et bestemt mål eller resultat.
Emnevejledning - En diskussion af en enkelt idé, forklaret på en sådan måde, at de underliggende begreber er klare.
Reference - Tekniske beskrivelser af specifikke API'er eller andre grænseflader.

Inden du begynder at bidrage til dokumentationen, er det vigtigt at finde ud af, hvilken form der passer bedst. Mange forslag til dokumentation vil i første omgang blive beskrevet som en anmodning om "en vejledning i X" – men i de fleste tilfælde er det, der faktisk er brug for, en how-to-vejledning, en emneguide eller forbedrede referenceoplysninger.

Som eksempel kan man tage opgaven med at skrive dokumentation om bagning af småkager.

Vejledning¶

En tutorial er en introduktion, især en der er rettet mod begyndere, og hvis mål er at føre læseren fra et rent udgangspunkt til et færdigt produkt. Det kræver meget specifikke instruktioner og detaljerede forklaringer, der sætter tutorialens trin i kontekst. Du må ikke antage noget om læserens erfaring med det værktøj, der forklares, selvom det er rimeligt at antage en vis grundlæggende kendskab til Python.

Vejledningen bør indeholde regelmæssige kontrolpunkter, hvor læseren kan fastslå, at han eller hun har gennemført det beskrevne. Ved hvert kontrolpunkt bør succeskriterierne være klare. Kendte fejlkilder bør beskrives tydeligt, herunder forklaringer på eventuelle fejl eller problemer, som læseren kan støde på. Ting, der ændrer sig som følge af læserens handlinger, bør påpeges, selvom de forekommer indlysende. Gentagelser tilskyndes, især hvis du forsøger at etablere en bedste praksis eller fælles processer. Forklaringer af interne forhold bør undgås, ligesom alternative veje til det samme resultat.

En tutorial om at bage småkager er mere end bare en opskrift. Instruktionerne i en tutorial skal være tilgængelige for nogen, der aldrig har bagt før (f.eks. et barn), og skal tage højde for ting, som en erfaren bager ville tage for givet, såsom hvordan man pisker sukker og smør, processen med at forvarme ovnen, eller hvor længe småkagerne skal køle af, før de kan spises. Målet med vejledningen er ikke at fremstille en cookie, men at formidle de grundlæggende principper for bagning. Den færdige cookie er den lækre godbid, der overbeviser nogen om at følge vejledningen i første omgang.

Vejledning¶

En vejledning bør fokusere på en specifik anvendelsessituation i den virkelige verden og praktiske resultater frem for teoretiske forklaringer. I modsætning til en tutorial kan du antage, at læseren har et vist kendskab til eksisterende værktøjer. Læseren skal kunne følge vejledningen fra start til slut og nå målet, men det kan være nødvendigt med en vis forudgående viden for at kunne gøre det. Vejledningen bør indeholde en række konkrete instruktioner eller logiske trin, der skal følges for at nå vejledningens mål.

En opskrift i en kogebog er et godt eksempel på en vejledning. Der findes mange opskrifter på chocolate chip cookies, og de har alle fælles træk, men enhver specifik opskrift skal kunne følges fra start til slut og give et ensartet resultat. En god opskrift på chocolate chip cookies vil ikke komme ind på de relative fordele ved forskellige typer sukker eller mel eller give detaljerede instruktioner om grundlæggende teknikker eller processer. Den vil kun indeholde ingredienser og instruktioner til at bage en portion cookies, idet den forudsætter, at læseren har grundlæggende kendskab til bagning.

Emnevejledning¶

En emneguide beskriver et enkelt emne eller en idé. Den kan indeholde eksempelkode eller instruktioner, men er i højere grad fokuseret på at give et overordnet billede af et samlet koncept. Den kan indeholde meninger og alternative perspektiver, men fokus på guidens specifikke emne skal bevares.

En emneguide om bagning af småkager kan dykke ned i småkagers historie som bagværk, undersøge, hvordan industrialiserede processer resulterer i andre typer småkager end hjemmelavede småkager, eller foreslå måder, hvorpå småkager kan indgå i en afbalanceret kost. I sig selv ville det ikke være et særlig nyttigt dokument at følge, hvis man ønskede at bage småkager, men det kunne give den baggrundsviden, der gør det muligt for en person, der er fortrolig med bagning, at tilpasse en eksisterende småkageopskrift.

Reference¶

Referencedokumentation er informationsorienteret og beskriver specifikke detaljer om brugen af et værktøjsbibliotek. Den kan ofte genereres ud fra selve koden, men god API-dokumentation kan kræve yderligere forklaringer og kontekst. Selvom den undertiden kan indeholde eksempler på brug, bør detaljerede forklaringer undgås.

En referencevejledning i bagning kan beskrive de typer sukker, der kan bruges, og detaljeret beskrive deres egenskaber, når de bruges i bagning. Den vil beskrive faktiske oplysninger om sukker, men en bredere diskussion om valg mellem forskellige sukkerarter bør være emnet for en vejledning eller emnevejledning. De ernæringsoplysninger, der findes på de fleste emballerede fødevarer, vil blive betragtet som referencedokumentation.

Dokumentationsstil¶

BeeWare's dokumentation følger retningslinjerne i dokumentationsstilguiden. Denne guide indeholder grundlæggende stil og formatering samt processen for stavekontrol. Den dækker også forskellige detaljer om Markdown-syntaks, såsom syntaks for referencelinks, tip til arbejde med kodeblokke og håndtering af billeder.

Bidragende dokumentation¶

Forslag til ny dokumentation

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.

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:

$ python3 --version

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:

$ python3 --version

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/<your username>/beeware.git

(erstatt dit GitHub-brugernavn)

Fork BeeWare repositoryet, og derefter:

$ git clone https://github.com/<your username>/beeware.git

(erstatt dit GitHub-brugernavn)

Fork BeeWare repositoryet, og derefter:

C:\...>git clone https://github.com/<your username>/beeware.git

(erstatt dit GitHub-brugernavn)

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

Undgå scope creep

"Scope creep" opstår, når listen over løste problemer eller implementerede funktioner ved et enkelt bidrag vokser betydeligt ud over det, der var tiltænkt, da arbejdet begyndte. Du starter med et simpelt problem, opdager et tæt relateret problem og beslutter at inkludere den løsning også, og så et tredje… Før du ved af det, har du en pull-anmodning, der lukker 5 problemer og tilføjer 3 nye funktioner, herunder snesevis af filer.

Scope creep sker for alle. Det er et begreb, som erfarne udviklere kender alt for godt; vi har alle gjort det flere gange og oplevet alle de problemer, der følger med.

Der er meget praktiske grunde til at undgå scope creep. Jo større et bidrag bliver, jo sværere er det at arbejde med. Det bliver sværere at identificere grænsetilfælde eller potentielle problemer, hvilket betyder, at den samlede kvalitet af bidraget kan blive forringet. Gennemgange bliver også mere udfordrende, når korrekturlæseren skal håndtere flere, potentielt urelaterede sammenhænge. Et større bidrag betyder flere kommentarer til gennemgangen, og som bidragyder kan det blive svært at følge flere gennemgangstråde. Selv din GitHub-oplevelse vil lide under det – GitHubs brugergrænseflade bliver langsommere, jo større en PR bliver, hvilket betyder, at det bliver stadig sværere at navigere i filerne gennem GitHub-grænsefladen og forsøge at efterlade kommentarer til gennemgangen.

Hver gang du finder en grund til at tilføje noget til dit bidrag, der ikke udtrykkeligt er en del af det oprindelige forslag eller fejlrapport, bør du overveje, om du er på vej mod scope creep. Er der to forskellige funktioner, der kan implementeres separat? Kan en funktion implementeres med en kendt begrænsning eller fejl, og kan fejlen rettes i en opfølgende pull-anmodning? Er en del af en fejlrettelse uafhængig af en anden? Hvis en del af en ændring kan udelades uden at ændre det oprindelige bidrag, bør det sandsynligvis gøres.

Udvikling af software er altid en proces med gradvise forbedringer. Hvert enkelt bidrag bør efterlade kodebasen i en bedre tilstand som følge af sammenlægningen, men det er helt acceptabelt at efterlade fejl eller dele af funktioner som arbejde til fremtidige forbedringer. Det kan betyde, at en pull-anmodning opdeles i flere dele, der kan gennemgås uafhængigt, eller at der logges et problem, så en anden kan undersøge og løse problemet.

At begrænse omfanget af hvert bidrag hjælper alle involverede, inklusive dig selv. Dine korrekturlæsere og endda du selv vil sætte pris på det.

Bygningsdokumentation

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] Serving on 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

(venv) $ tox -e docs-all

(venv) $ 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.

Skrivning af 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:

- ./path/to/directory/*

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:

- [My new document](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.

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.