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:

$ 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

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

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
TOTAL 7540 0 1040 0 100,0 %

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

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

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

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

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

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

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

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

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

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

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

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

/// details-abstract | 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.

/// warning | 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:



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

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

///

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:

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

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.