Escrivint un bon pegat

Write separate changes

És molest quan rebeu un pegat massiu que es diu que soluciona 11 problemes estranys, però les discussions i opinions no coincideixen amb 10 d’ells o 9 d’ells ja es van solucionar d’una altra manera. Aleshores, la persona que fusiona aquest canvi ha d’extreure l’únic pegat interessant d’algun lloc de l’enorme pila de fonts, i això crea molt de treball addicional.

Preferiblement, cada solució que solucioni un problema hauria d’estar en el seu propi pedaç/commit amb el seu propi missatge de descripció/commit que indiqui exactament el que corregeix perquè tots els canvis puguin ser aplicats selectivament pel responsable o altres parts interessades.

A més, els canvis separats permeten la bisectació molt millor per fer un seguiment dels problemes i la regressió en el futur.

Documentació

La documentació pot ser una tasca tediosa; tanmateix, és necessari que algú el completi. Facilita molt les coses si envieu la documentació juntament amb els canvis de codi. Recordeu documentar mètodes, blocs de codi complexos o funcions visibles per l’usuari.

Vegeu també

Contribute to Weblate documentation

Casos de prova

Les proves ens permeten comprovar ràpidament que les funcions funcionen com se suposa. Per mantenir aquesta situació i millorar-la, totes les característiques i funcions noves que s’afegeixin s’han de provar a la suite de proves. Cada funció que s’afegeixi hauria d’obtenir almenys un cas de prova vàlid que verifiqui que funciona com està documentat.

Vegeu també

Weblate testsuite i integració contínua

Missatges de les comissions

Les confirmacions de Git haurien de seguir l’especificació Commits convencionals.

Type checking

Qualsevol codi nou hauria d’utilitzar pistes de tipus PEP 484. Estem utilitzant mypy per comprovar-los perquè té un connector de Django que fa que la comprovació de tipus de les aplicacions de Django sigui pràctica.

El codi nou i canviat no hauria d’introduir nous errors de mypy on el suport actual d’escriptura de Django ho fa pràctic. La base del codi encara no està completament coberta per les anotacions de tipus, i algunes construccions de Django són difícils d’anotar amb precisió. Per tant, CI aplica mypy només per als mòduls seleccionats i informa d’altres descobriments per separat.

Estàndard de codificació i llinatge del codi

El codi ha de seguir les directrius de codificació PEP 8 i s’ha de formatar amb el formatador de codi ruff.

Per comprovar la qualitat del codi, podeu utilitzar ruff, la seva configuració s’emmagatzema a pyproject.toml.

When suppressing a ruff diagnostic, prefer # ruff: ignore[rule-name] with the human-readable rule name. Place the comment on the line above the logical statement or block when that does not broaden the suppression scope. Keep the comment inline when moving it would change the scope, affect import sorting, or get between another tool’s disable-next comment and the code it targets.

L’enfocament més fàcil per fer complir tot això és instal·lar prek. Aquesta és una reimplementació de tercers de l’eina pre-commit utilitzada per Weblate. S’inclou a les dependències de desenvolupament declarades a pyproject.toml, de manera que la instal·lació d’aquestes dependències fa que prek estigui disponible.

Per comprovar tots els fitxers manualment, executeu:

uv run prek run --all-files

Si preferiu el client original pre-commit, utilitza la mateixa configuració de .pre-commit-config.yaml.

Coding securely

Qualsevol codi per a Weblate s’ha d’escriure tenint en compte els Security by Design Principles.

AI guidelines

Quan aporteu contingut al projecte, ens doneu permís per utilitzar-lo tal com està i heu d’assegurar-vos que ens el permeten distribuir. En enviar-nos un canvi, accepteu que els canvis poden i han de ser adoptats pel projecte i es redistribueixen sota la llicència del projecte. Els autors han de ser conscients de manera explícita que la càrrega recau sobre ells per assegurar-se que no s’enviï cap codi sense llicència al projecte.

Això és independent de si s’utilitza la IA o no.

Quan aporteu una sol·licitud d’extracció, per descomptat, heu d’assegurar-vos sempre que la proposta sigui de bona qualitat i que el millor esforç segueixi les nostres directrius. Una regla bàsica és que si algú pot detectar que la contribució es va fer amb l’ajuda de l’IA, teniu més feina per fer.

Podem acceptar codi escrit amb l’ajuda de la IA al projecte, però el codi ha de seguir els estàndards de codificació, estar escrit amb claredat, documentar-se, presentar casos de prova i complir amb tots els requisits normals que tenim.