Tirsvad
57d9b63b3c
TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Skipped
Validate workflows / validate (pull_request) Successful in 57s
Adds the guide, the README section with its diagram, the wiki page in English, Danish and Bahasa Malaysia, the Home and Capabilities rows, the sidebar entry and the changelog entry under Unreleased. Refs #206 Task: MIL-013#10
109 lines
5.6 KiB
Markdown
109 lines
5.6 KiB
Markdown
<!-- translation of EnglishComments.md, source sha256 866ce29fd1ea -->
|
|
|
|
> Dette er en oversættelse af [`EnglishComments`](EnglishComments). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
|
|
|
|
[English](EnglishComments) | Dansk | [Bahasa Melayu](EnglishComments.ms)
|
|
|
|
# Kommentarer i kildekoden på engelsk
|
|
|
|
Sådan kalder en softwareudvikler det fælles workflow, der kontrollerer, at
|
|
kommentarerne og docstrings i en pull request er skrevet på engelsk. Workflowet
|
|
lader kørslen fejle, når én ikke er det, og skriver én kommentar på pull
|
|
requesten, der nævner forfatteren. Det ændrer ingen fil og sender ingen
|
|
kildetekst ud af instansen. Beslutningen bag er ADR-0012 i dette repository.
|
|
|
|
## Kald af workflowet
|
|
|
|
```yaml
|
|
name: English comments
|
|
|
|
on:
|
|
pull_request:
|
|
|
|
jobs:
|
|
english-comments:
|
|
uses: TirSystem/github-action/.gitea/workflows/english-comments.yml@v2
|
|
with:
|
|
exclude: "docs/generated/**"
|
|
allowed-words-file: .english-comments-allowed-words
|
|
```
|
|
|
|
Indtil udgivelse 2.3.0 findes workflowet kun på `main`, så kald det med `@main`; `@v2` indeholder det
|
|
endnu ikke.
|
|
|
|
| Input | Standard | Betydning |
|
|
| --- | --- | --- |
|
|
| `scope` | `changed` | `changed` kontrollerer kommentarerne på de linjer, pull requesten tilføjer; `all` kontrollerer hver sporet fil |
|
|
| `exclude` | | Kommasepareret liste af fil- eller stimønstre, der ikke kontrolleres (`*` og `**` er jokertegn) |
|
|
| `allowed-words-file` | | En fil i repositoryet med ord, der aldrig bedømmes, ét pr. linje; `#` starter en kommentar |
|
|
| `threshold` | `0.6` | Sandsynligheden, over 0 og højst 1, hvorfra en kommentar regnes for ikke at være engelsk |
|
|
| `min-words` | `3` | En kommentar med færre ord bedømmes ikke |
|
|
| `langid-version`, `numpy-version` | `1.1.6`, `2.1.3` | De fastlåste pakker, detektoren bruger |
|
|
| `tools-ref` | den nuværende hovedversion | Det tag i dette repository, hvis scripts køres; fastlås det sammen med workflowet |
|
|
|
|
Den valgfri secret `REPORT_TOKEN` er et Gitea-token, der må kommentere på pull
|
|
requests. Uden den bruger workflowet kørslens eget token, så kommentaren
|
|
skrives af Actions-botten. En pull request fra en fork har et token med kun
|
|
læseadgang: kontrollen får stadig kørslen til at fejle, men der skrives ingen
|
|
kommentar.
|
|
|
|
## Hvad der kontrolleres
|
|
|
|
Kommentarerne og docstrings i filer på de sprog, kodetælleren kender
|
|
([kodemålinger](CodeMetrics)): Python, shell, PowerShell, C, C++, C#, Java,
|
|
JavaScript, TypeScript, Go, Rust og SQL. Strenge og kode læses ikke. Kommentarlinjer
|
|
efter hinanden bedømmes som én blok.
|
|
|
|
Før en blok bedømmes, fjernes alt, der ikke er et ord: stier, URL'er, tilvalg
|
|
(`--output`), filnavne, identifikatorer (`snake_case`, `camelCase`), tal,
|
|
akronymer og konstanter (`JSON`), en indledende etiket som `Usage:` og ordene
|
|
i filen med tilladte ord. En blok med færre end `min-words` ord tilbage
|
|
bedømmes ikke, så en kort kommentar slipper igennem. Kommentarer, der
|
|
konfigurerer et værktøj (`noqa`, `type:`, `pragma`, `shellcheck`), læses ikke.
|
|
|
|
## Når kontrollen fejler
|
|
|
|
Kørslen fejler, hvert fund vises som en annotation (`::error file=...,line=...`)
|
|
og i loggen som `file:line: looks Danish (0.93): "the comment"`, og én kommentar
|
|
på pull requesten opregner dem og nævner forfatteren. En ny kørsel opdaterer den
|
|
kommentar; når pull requesten består, markeres kommentaren som løst og nævner
|
|
ikke længere nogen.
|
|
|
|
Ret det ved at skrive kommentaren om på engelsk. For et citat eller et navn, der
|
|
ikke er engelsk, kan du enten skrive `english-comments: ignore` i kommentaren
|
|
(det springer hele den kommentarblok over, den står i), eller tilføje ordet til
|
|
filen med tilladte ord.
|
|
|
|
## Blokering af sammenfletningen
|
|
|
|
En fejlende kørsel blokerer ikke i sig selv en sammenfletning. Markér kontrollen
|
|
som påkrævet i grenbeskyttelsen af målgrenen: kør workflowet én gang på en pull
|
|
request og vælg dets post på listen over statuskontroller (det præcise navn
|
|
dannes af det kaldende workflow, dets job og hændelsen). At indstille
|
|
grenbeskyttelse er repositoryejerens handling; workflowet ændrer den ikke.
|
|
|
|
## Hvor præcis den er
|
|
|
|
Detektoren er `langid`, begrænset til engelsk, dansk, norsk, svensk, tysk,
|
|
fransk, malajisk, indonesisk og hollandsk. På repositoryets korpus markerer den
|
|
ingen af 300 engelske kommentarer, 44 af 45 danske og 41 af 45 malajiske
|
|
kommentarer og alle 48 tyske, svenske, norske og franske (ADR-0012). Dens
|
|
grænser:
|
|
|
|
- en kommentar på ét eller to ord, eller en der mest består af navne, bedømmes ikke;
|
|
- en kommentar på dårligt engelsk slipper igennem, og en kommentar, der blander
|
|
engelske fagudtryk med få danske eller malajiske ord, kan slippe igennem;
|
|
- korpussets danske og malajiske kommentarer er skrevet til testen og ikke samlet
|
|
fra rigtig kode, så rigtig kode vil vise andre fejl. Meld en misset kommentar
|
|
eller et falsk fund med kommentaren, så kommer den med i korpussen.
|
|
|
|
## Fejlfinding
|
|
|
|
| Besked | Årsag |
|
|
| --- | --- |
|
|
| `[configuration] give --base` | Workflowet blev startet af en hændelse, der ikke er en pull request, med `scope: changed`; kald det på `pull_request` eller brug `scope: all` |
|
|
| `[configuration] git diff failed` | Basisgrenen findes ikke i checkout; workflowet henter hele historikken, så tjek at pull requesten har en målgren |
|
|
| `[configuration] langid is not installed` | Installationstrinnet fejlede; tjek de fastlåste versioner |
|
|
| `[permissions] ... may not comment on pull requests` | Tokenet må ikke kommentere; giv `REPORT_TOKEN` skriveadgang til issues og pull requests |
|
|
| Et fund, der ikke er et fund | Tilføj ordene til filen med tilladte ord, eller `english-comments: ignore` til kommentaren |
|