Weblate broncode

Weblate wordt ontwikkeld op GitHub. U bent van harte uitgenodigd de code te forken en pull requests te openen. Patches, in welke vorm dan ook, zijn ook van harte welkom.

Zie ook

Bekijk Internen van Weblate om te zien hoe Weblate er van binnen uitziet.

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.

Bij het onderdrukken van diagnostiek ruff, voorkeur voor # ruff: ignore[rule-name] met de voor mensen leesbare naam voor de regel. Plaats de opmerking op de regel boven het logische argument of blokkeer die als dat het bereik voor de onderdrukking niet uitbreidt. Houd de opmerking op de regel als het verplaatsen ervan het bereik zou wijzigen, het sorteren van importeren zou beïnvloeden, of tussen de opmerking disable-next van een ander programma en de code waar die betrekking op heeft, zou komen.

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 de suggestie 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.

Vastleggen feitelijke gebruikers

Gebruik acting_user_context(user) uit weblate.utils.change_origin rondom bewerkingen die instellingen voor het model wijzigen buiten een geauthenticeerd verzoek. Verzoekauthenticatie stelt deze context automatisch vast. Modellen lezen de actor met get_acting_user(); ze behouden niet langer de attributen acting_user. Geneste contexten herstellen de vorige actor, en expliciet doorgeven van None maakt het leeg. Gebruik de anonieme gebruiker voor opzettelijke anonieme wijzigingen en de toepasselijke bot voor geautomatiseerde bewerkingen.

Geef doorlopend een expliciete gebruiker door bij het vastleggen van geschiedenis. De actorcontext verschaft niet automatisch ontbrekende gebruikers aan Change en vervangt geen controles op rechten of auteurschap voor inhoud. Openstaande bestanden schrijven behouden hun eigen volgehouden actors en auteurs.

Laat afgeleide terugaanroepen van transactie doorlopen met capture_change_origin() bij het registreren ervan. Dat legt zowel de oorsprong als de actor vast voordat ze hun bereiken verlaten. Celery-taken geven de actor door met een afzonderlijke interne header; alleen de gebruikeridentificatie wordt geserialiseerd. Metadata voor oorsprong die is opgeslagen in geschiedenis bevat deze identificatie niet. Taken met een ongeldige en verwijderde actor mislukken zonder hun body uit te voeren.

Writing repository files

Create and update repository files atomically. Write the complete content to a temporary file on the destination filesystem, then replace the destination only after writing succeeds. Do not truncate repository files in place or copy over an existing destination directly. Repository locks are still required to coordinate concurrent operations; atomic replacement does not replace locking.

Use TranslationFormat.save_atomic(filename, callback) for file format writers. The callback receives a binary file handle. In add-ons, use BaseAddon.write_repo_file(filename, content) with bytes or UTF-8 text. These helpers select a temporary directory on the destination filesystem and clean up temporary files when writing or replacement fails. Pass the repository temporary directory to save_atomic() when it is available. The add-on helper preserves existing file permissions, including executable bits, before replacement.

Direct external tools to temporary output, check that generation succeeded, and install the completed content using an atomic helper. Keep path validation and repository locking around these operations. Atomic replacement applies to each file separately; these helpers do not provide transactions across multiple files or guarantee durability through power loss.