Een goede patch schrijven

Afzonderlijke wijzigingen schrijven

Het is heel vervelend als u een massieve patch ontvangt die zegt 11 verschillende problemen te repareren, maar overleg en meningen zijn het niet eens met 10 ervan of 9 ervan waren al op een andere manier gerepareerd. Dan moet de persoon, die deze wijziging moet samenvoegen, die ene interessante patch uitnemen uit die enorme berg met bronnen en dat vraagt heel veel extra werk.

Bij voorkeur zou elke reparatie die een probleem adresseert in zijn eigen patch/commit moeten staan, met zijn eigen beschrijving/commit-bericht, dat exact vermeld wat het corrigeert, zodat alle wijzigingen selectief kunnen worden toegepast door de onderhouder of andere geïnteresseerde partijen.

Bovendien maken afzonderlijke wijzigingen het onderscheiden, voor het bijhouden van problemen en regressie in de toekomst, veel gemakkelijker.

Documentatie

Documentatie kan een vervelende taak zijn; het is echter noodzakelijk dat iemand het voltooid. Het maakt dingen veel gemakkelijker als u de documentatie samen met de wijzigingen in de code indient. Vergeet niet om methoden, complexe codeblokken of voor de gebruiker zichtbare mogelijkheden te documenteren.

Zie ook

Bijdragen aan documentatie voor Weblate

Testgevallen

De testen stellen ons in staat snel te verifiëren dat de mogelijkheden werken zoals ze zijn bedoeld te werken. Voor het behouden van deze situatie en die te verbeteren, moeten alle nieuwe mogelijkheden en functies, die worden toegevoegd, worden getest in de testomgeving. Elke mogelijkheid die wordt toegevoegd zou ten minste een geldig testgeval moeten krijgen, die verifieert dat het werkt zoals het is gedocumenteerd.

Zie ook

Weblate testsuite en doorlopende integratie

Commitberichten

Commits voor Git zouden de specificatie Conventionele commits moeten volgen.

Type controleren

Alle nieuwe code zou hints van het type PEP 484 moeten gebruiken. We gebruiken mypy om ze te controleren, omdat het een plug-in voor Django heeft die het controleren van types voor Django-apps praktisch maakt.

Nieuwe en gewijzigde code zou geen nieuw falen voor mypy moeten introduceren waar de huidige ondersteuning van Django voor typeren dat praktisch maakt. De codebasis is nog niet volledig afgedekt door type-annotaties, en sommige constructies van Django zijn moeilijk om precies te annoteren. CI dwingt daarom mypy alleen af voor geselecteerde modules en rapporteert andere bevindingen afzonderlijk.

Standaard voor coderen en linten van de code

De code zou de richtlijnen voor coderen PEP 8 moeten volgen en zou moeten zijn opgemaakt met de codeopmaker ruff.

Voor het controleren van de kwaliteit van de code kunt u ruff gebruiken, de configuratie ervan is opgeslagen in pyproject.toml.

De gemakkelijkste benadering om dit allemaal af te dwingen is door prek te installeren. Dit is een herimplementatie van het gereedschap pre-commit, gebruikt door Weblate. Het is opgenomen in de afhankelijkheden voor ontwikkeling die zijn vermeld in pyproject.toml, dus het installeren van die afhankelijkheden maakt prek beschikbaar.

Alle bestanden handmatig controleren, voer uit:

uv run prek run --all-files

Wanneer u liever de originele cliënt pre-commit gebruikt, het gebruikt dezelfde configuratie uit .pre-commit-config.yaml.

Zorgvuldig coderen

Alle code voor Weblate zou moeten zijn geschreven met Security by Design Principles in gedachte.

Richtlijnen voor AI

Door het bijdragen van inhoud aan het project, geeft u ons toestemming om die te gebruiken as-is en u moet ervoor zorgen dat u het recht hebt het aan ons door te geven. Door het bij ons indienen van een wijziging stemt u ermee in dat de wijzigingen kunnen en zouden moeten worden geadopteerd door het project en opnieuw worden gedistribueerd onder de licentie van het project. Auteurs zouden zich er expliciet van bewust moeten zijn dat de bewijslast, om ervoor te zorgen dat er geen niet-gelicenseerde code bij het project wordt ingediend, bij hen ligt.

Dat staat los van het feit of er al dan niet AI is gebruikt.

Bij het indienen van een pull request, zou u, natuurlijk, er altijd voor moeten zorgen dat het voorstel van goede kwaliteit is en volgens de beste inspanning volgens onze richtlijnen. Een basisregel is dat als iemand kan zien dat de bijdrage werd gemaakt met de hulp van AI, u nog wat werk hebt te doen.

We kunnen in het project code accepteren die is geschreven met de hulp van AI, maar de code moet nog steeds voldoen aan de standaarden voor coderen, helder zijn geschreven, moet zijn gedocumenteerd, testgevallen bevatten en voldoen aan alle normale eisen die we eraan stellen.