Oversigt

Alle ændringer af kode og dokumentation skal (/contributing/first-time/github/) via en pull-anmodning til projektets GitHub-arkivet for projektet.

De fleste projekter har en dedikeret bidragsguide med detaljer, der er specifikke for det pågældende projekt eller specifikke typer af bidrag. Denne dokumentation kan findes på Read the Docs. For eksempel indeholder [Briefcase's dokumentation] (https://briefcase.readthedocs.io) indeholder bidrags vejledninger for både kode og dokumentation.

Alle indsendelser skal overholde BeeWare Code of adfærdskodeks.

Ændringsnoter

Flere BeeWare-projekter, især Briefcase og Toga, kræver, at hver pull-anmodning indsendes med en ændringsnote. Disse ændringsnoter bliver samles, når en ny udgivelse er klar til projektet, og producerer udgivelsesnoterne for den nye udgivelse.

BeeWare bruger [Towncrier] (https://towncrier.readthedocs.io/en/stable/) til at håndtere ændringsnoter.

En ændringsnotatfil skal oprettes i mappen changes og navngives med navngives ved hjælp af dette format:

<PR/Issue #>.<Change Type>.rst

For eksempel vil en pull request, der løser GitHub-problem #42, få navnet 42.bugfix.rst. Hvis en pull-anmodning ikke er forbundet med et specifikt problem, kan nummeret på pull-anmodningen bruges i stedet. Det kan være nødvendigt at oprette pull-anmodningen uden en ændringsnote for at få et pull-anmodningsnummer nummer tildelt, og derefter skubbe en opdatering, der inkluderer ændringsnotatet med det nyligt tildelte pull request-nummer.

Ændringstyperne for ændringsnoten skal være en af følgende:

  • feature
  • bugfix
  • doc
  • removal
  • misc

Typen misc er reserveret til ændringer, der ikke påvirker brugerne, og som ikke behøver at blive nævnt i udgivelsesnoterne. Mindre typografiske rettelser i dokumentation, opdateringer af CI-konfiguration og fejlrettelser af funktioner, der endnu ikke er blevet formelt udgivet, er eksempler på funktioner, der ville blive beskrevet med misc-markører.

Et ændringsnotat bør være en enkelt linje tekst, der giver et overordnet resumé af ændringen set fra brugerens perspektiv, ikke en dyb 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. En ændringsnote er en "brugervendt" beskrivelse, beskrevet i form af den nye kapacitet der er tilgængelig som følge af ændringen. Det kan hjælpe at tænke på ændringsnote som en pressemeddelelse, der annoncerer ændringen, snarere end en commit-beskrivelse.

Hvis du f.eks. retter en fejl, der skyldes datahåndtering, kan commit-beskeden eller eller pull request-beskrivelsen måske lyde:

Tilføjet en MM-DD-YYYY-formatvalidator til DateWidget-valideringskæden kæde.

Dette beskriver den ændring, der blev foretaget i implementeringen - en detalje som vil være nyttige for den person, der gennemgår koden. Men den tilsvarende ændringsnote kunne lyde noget i retning af:

Datowidgets kan nu acceptere datoer i amerikansk format.

Dette beskriver den funktionelle ændring, som den vil blive oplevet af slutbrugerne. brugere. En bruger kan læse denne beskrivelse uden at behøve at vide noget om implementeringen.

Kodestil

BeeWares projekter bruger [Pre-commit] (https://pre-commit.com/) til at automatisere overholdelse af kodestil. Disse kontroller er defineret i filen .pre-commit-config.yaml-filen for hvert repository og bliver automatisk køres automatisk i CI, når en pull-anmodning åbnes.

For at automatisere Pre-commit-tjekkene i dit lokale udviklingsmiljø med hver git commit, skal du køre pre-commit install.

Inkluderet Pre-commit checks:

  • Sort sikrer ensartet kodeformatering
  • docformatter sikrer ensartet formatering af dokumentstrenge og kommentarer
  • pyupgrade sikrer, at koden bruger den nyeste bedste praksis for Python
  • isort sikrer ensartet import udsagn
  • flake8 tjekker for almindelige kodnings- og og syntaksproblemer
  • Diverse kontroller, der validerer strukturerede dokumenter som TOML-filer og fjerner unødvendige mellemrum

Yderligere retningslinjer:

  • Undgå at bruge "vi" i kommentarer, f.eks. "Loop over" i stedet for "Vi looper over"

  • Brug underscores, ikke camelCase, til variabel-, funktions- og metodenavne navne

  • Brug InitialCaps til klassenavne (eller til fabriksfunktioner, der returnerer klasser)

  • Brug docstrings i Sphinx-stil og 257; typeannotation med 484 er valgfri, men anbefales.

    For eksempel:

    def function_name(param1: int, param2: str) -> bool:
    """Eksempel på funktion med typer og en docstring.

    :param param1: Den første parameter.
    :param param2: Den anden parameter.

    :returnerer: Returværdien. True for succes, False ellers.
    """

  • I testdokumentationerne skal du angive den forventede adfærd, som hver test demonstrerer. Lad være med at inkludere indledninger som "Tester at" eller "Sikrer at".

  • Reserver ticket-referencer til obskure problemer, hvor ticket'en har yderligere detaljer, som ikke let kan beskrives i dokumentationer eller kommentarer. Inkluder billetnummeret i slutningen af en sætning som på denne måde:

    def test_foo():
    """En test-dokumentstreng ser sådan ud (#123456)."""

  • Medmindre andet er angivet, skal du følge 8 (med omhyggelig opmærksomhed på Afsnit 2).