Kihagyás

Hozzájárulás a Klipperhez

Köszönjük, hogy hozzájárultál a Klipperhez! Ez a dokumentum leírja a Klipper változtatásokhoz való hozzájárulás folyamatát.

Kérjük, tekintsd meg a kapcsolat oldalt a probléma bejelentésével kapcsolatos információkért vagy a fejlesztőkkel való kapcsolatfelvételre vonatkozó részletekért.

A hozzájárulási folyamat áttekintése

A Klipperhez való hozzájárulás általában egy magas szintű folyamatot követ:

  1. A benyújtó egy GitHub Pull Request létrehozásával kezdi, amikor egy beadvány készen áll a széles körű telepítésre.
  2. Amikor egy bíráló elérhető a felülvizsgálat benyújtásához, akkor hozzárendeli magát a Pull Requesthez a GitHubon. A felülvizsgálat célja a hibák keresése és annak ellenőrzése, hogy a beadvány követi-e a dokumentált irányelveket.
  3. Sikeres felülvizsgálat után a felülvizsgáló "jóváhagyja a felülvizsgálatot" a GitHub-on, és egy karbantartó átvezeti a módosítást a Klipper master ágába.

Ha fejlesztéseken dolgozol, fontold meg egy téma indítását (vagy a témához való hozzájárulást) a Klipper Társalgó oldalon. A fórumon folyó vita javíthatja a fejlesztési munka láthatóságát, és vonzhat másokat is, akik érdeklődnek az új munka tesztelése iránt.

Mire számíthatsz egy felülvizsgálat során

A Klipperhez való hozzájárulásokat az egyesítés előtt felülvizsgálják. A felülvizsgálati folyamat elsődleges célja a hibák ellenőrzése, valamint annak ellenőrzése, hogy a beadvány megfelel-e a Klipper dokumentációjában meghatározott irányelveknek.

Természetesen egy feladatot sokféleképpen lehet elvégezni; a felülvizsgálat célja nem az, hogy megvitassa a "legjobb" végrehajtást. Ahol lehetséges, a felülvizsgálati megbeszélések inkább a tényekre és a mérésekre összpontosítanak.

A beadványok többsége visszajelzést eredményez egy felülvizsgálatról. Készülj fel a visszajelzések beszerzésére, további részletek megadására és szükség esetén a beadvány frissítésére.

Gyakori dolgok, amiket a bíráló keres:

  1. Hibátlan-e a beadvány, és készen áll-e a széles körű bevezetésre?A benyújtóknak a benyújtás előtt tesztelniük kell a változtatásokat. A bírálók keresik a hibákat, de általában nem tesztelik a beküldött anyagokat. Egy elfogadott beadványt gyakran az elfogadást követő néhány héten belül több ezer nyomtatóhoz juttatunk el. Ezért a beadványok minősége prioritást élvez.

    A fő Klipper3d/klipper GitHub tároló nem fogad el kísérleti munkát. A beküldőknek a kísérletezést, hibakeresést és tesztelést a saját tárolójukban kell elvégezniük. A Klipper Társalgó szerver jó hely arra, hogy felhívjuk a figyelmet az új munkára, és megtaláljuk azokat a felhasználókat, akiket érdekel a valós visszajelzés.

    A beadványoknak át kell menniük az összes regressziós teszteseten.

    A kódban lévő hiba javításakor a benyújtóknak általában véve tisztában kell lenniük a hiba kiváltó okával, és a javításnak ezt a kiváltó okot kell megcéloznia.

    A beküldött kódok nem tartalmazhatnak túlzottan sok hibakeresési kódot, hibakeresési opciót vagy futásidejű hibakeresési naplózást.

    A kódbeadványokhoz fűzött megjegyzéseknek a kód karbantartásának javítására kell összpontosítaniuk. A beadványok nem tartalmazhatnak "kikommentált kódot" vagy túlzottan sok, korábbi megvalósításokat leíró megjegyzést. Nem lehetnek túlzott mértékű "todo" megjegyzések.

    A dokumentáció frissítései nem jelenthetik ki, hogy azok "folyamatban lévő munkák".

  2. A beadott pályázat "nagy hatású" előnyt jelent-e a valós felhasználók számára, akik valós feladatokat látnak el?A bírálóknak - legalábbis a saját fejükben - nagyjából meg kell határozniuk, hogy "ki a célközönség", hogy "mekkora a célközönség", hogy "milyen előnyökhöz" jutnak, hogy "az előnyöket hogyan mérik", és hogy "milyen eredményeket hoznak ezek a mérési tesztek". A legtöbb esetben ez mind a benyújtó, mind a bíráló számára nyilvánvaló, és a bírálat során nem kerül kifejezett kijelentésre.

    A mester Klipper ágba küldött beadványok várhatóan figyelemre méltó célközönséggel rendelkeznek. Általános "ökölszabályként" a beadványoknak legalább 100 valós felhasználóból álló felhasználói bázist kell megcélozniuk.

    Ha egy bíráló részleteket kér egy beadvány "hasznáról", kérjük, ne tekintsd ezt kritikának. Az, hogy képesek legyünk megérteni egy változtatás valós előnyeit, a felülvizsgálat természetes része.

    Az előnyök megvitatásakor előnyösebb a "tények és mérések" megvitatása. Általában véve a bírálók nem a "valaki hasznosnak találhatja az X opciót", sem pedig a "ez a beadvány olyan funkciót ad hozzá, amelyet az X firmware valósít meg" formájú válaszokat keresik. Ehelyett általában előnyösebb, ha részletesen tárgyalják, hogy a minőségjavulást hogyan mérték, és milyen eredményeket hoztak ezek a mérések - például: "az Acme X1000 nyomtatókon végzett tesztek a ...képen látható javuló sarkokat mutatnak ", vagy például "az X valós tárgy nyomtatási ideje egy Foomatic X900 nyomtatón 4 óráról 3,5 órára csökkent". Magától értetődik, hogy az ilyen típusú tesztelés jelentős időt és erőfeszítést igényel. A Klipper legjelentősebb funkcióinak némelyike hónapokig tartott a megbeszélések, átdolgozások, tesztelések és dokumentációk során, mielőtt beolvadt a master ágba.

    Minden új modulnak, konfigurációs opciónak, parancsnak, parancsparaméternek és dokumentumnak "nagy hatással" kell rendelkeznie. Nem akarjuk a felhasználókat olyan opciókkal terhelni, amelyeket nem tudnak ésszerűen konfigurálni, és nem akarjuk őket olyan opciókkal terhelni, amelyek nem nyújtanak számottevő előnyt.

    A bíráló kérhet pontosítást arról, hogy a felhasználónak hogyan kell beállítania egy opciót - az ideális válasz tartalmazza a folyamat részleteit - például: "a MegaX500 felhasználóinak az X opciót 99,3-ra kell beállítaniuk, míg az Elite100Y felhasználóinak az X opciót a ..." eljárással kell kalibrálniuk...".

    Ha az opció célja, hogy a kódot modulárisabbá tedd, akkor inkább használj kódkonstansokat a felhasználóval szembenéző konfigurációs opciók helyett.

    Az új modulok, új opciók és új paraméterek nem biztosíthatnak hasonló funkciókat a meglévő modulokhoz - ha a különbségek önkényesek, akkor inkább a meglévő rendszert kell használni, vagy a meglévő kódot kell átalakítani.

  3. A beadvány szerzői joga egyértelmű, nem hálapénz és összeegyeztethető?Az új C és Python fájloknak egyértelmű szerzői jogi nyilatkozatot kell tartalmazniuk. Az előnyben részesített formátumot lásd a meglévő fájlokban. A meglévő fájl szerzői jogának deklarálása a fájl kisebb módosításai esetén elhanyagolható.

    A harmadik féltől származó kódnak kompatibilisnek kell lennie a Klipper licenszel (GNU GPLv3). A nagyobb, harmadik féltől származó kódkiegészítéseket a lib/ könyvtárba kell helyezni (és a lib/README könyvtárban leírt formátumot kell követni).

    A beküldőknek meg kell adniuk egy Signed-off-by line sort a teljes valódi nevükkel. Ez azt jelzi, hogy a benyújtó egyetért a fejlesztői származási igazolással.

  4. A benyújtás követi a Klipper dokumentációban meghatározott irányelveket?Különösen a kódnak a , a konfigurációs fájloknak pedig a című dokumentumban található irányelveket kell követniük.

  5. A Klipper dokumentáció frissítve van az új változásoknak megfelelően?Legalább a referenciadokumentációt kell frissíteni a kód megfelelő változtatásaival:

  • Minden parancsot és parancsparamétert a dokumentumban kell dokumentálni.
  • Minden felhasználó előtt álló modult és azok konfigurációs paramétereit dokumentálni kell a fájlban.
  • Minden exportált "állapotváltozót" dokumentálni kell .
  • Minden új "webhooks" és paramétereiket dokumentálni kell .
  • Minden olyan módosítás, amely nem visszafelé kompatibilis módosítást hajt végre egy parancs vagy konfigurációs fájl beállításán, dokumentálni kell a dokumentumban.

Az új dokumentumokat hozzá kell adni az fájlhoz, és hozzá kell adni a weboldal indexéhez docs/_klipper3d/mkdocs.yml.

  1. A véglegesítések jól megformáltak, véglegesítésként egyetlen témával foglalkoznak, és függetlenek?A kérelmi üzeneteknek a preferált formátumot kell követniük.

    A kérelmeknek nem lehet összeolvadási konfliktusuk. A Klipper master ágához való új hozzáadások mindig egy "rebase" vagy "squash and rebase" segítségével történnek. A benyújtóknak általában nem szükséges a Klipper főadattár minden egyes frissítésénél újra egyesíteniük a beadványukat. Ha azonban összeolvasztási konfliktus van, akkor a benyújtóknak ajánlott a git rebase használata a konfliktus megoldására.

    Minden egyes kérelemnek egyetlen magas szintű változtatással kell foglalkoznia. A nagyobb változtatásokat több független kérelemre kell bontani. Minden commit-nak "önállóan kell állnia", hogy az olyan eszközök, mint a git bisect és git revert megbízhatóan működjenek.

    A fehér területi változtatásokat nem szabad összekeverni a funkcionális változtatásokkal. Általánosságban elmondható, hogy az indokolatlan szóköz módosításokat nem fogadjuk el, kivéve, ha azok a módosítandó kód megállapított "tulajdonosától" származnak.

A Klipper nem alkalmaz szigorú "kódolási stílusú útmutatót", de a meglévő kód módosításainak követniük kell a meglévő kód magas szintű kódáramlását, kódbehúzási stílusát és formátumát. Az új modulok és rendszerek benyújtása esetén a kódolási stílus rugalmasabb, de előnyösebb, ha az új kód belsőleg konzisztens stílust követ, és általában az iparági kódolási normákat követi.

A felülvizsgálat célja nem a "jobb megvalósítások" megvitatása. Ha azonban egy bírálónak nehézséget okoz egy beadott pályázat megvalósításának megértése, akkor kérhet változtatásokat a megvalósítás átláthatóbbá tétele érdekében. Különösen, ha a bírálók nem tudják meggyőzni magukat arról, hogy egy beadott pályázat hibátlan, akkor változtatásokra lehet szükség.

A felülvizsgálat részeként egy felülvizsgáló létrehozhat egy alternatív kérést egy témához. Ezt azért lehet megtenni, hogy elkerülhető legyen a túlzott "oda-vissza" a kisebb eljárási kérdésekben, és így egyszerűsödjön a benyújtási folyamat. Ez azért is megtörténhet, mert a vita arra ösztönzi a bírálót, hogy egy alternatív implementációt készítsen. Mindkét helyzet a felülvizsgálat normális eredménye, és nem tekinthető az eredeti beadvány kritikájának.

Segítség a felülvizsgálatokban

Nagyra értékeljük a segítséget a véleményekkel kapcsolatban! Nem szükséges listázott értékelőnek lenni az értékelés elvégzéséhez. A GitHub kérelmek benyújtóit is arra ösztönözzük, hogy saját beadványaikat vizsgálják felül.

A felülvizsgálat során segíts, kövesd a mire számíthatsz egy felülvizsgálat során pontban leírt lépéseket a beküldés ellenőrzéséhez. A felülvizsgálat befejezése után adj hozzá egy megjegyzést a GitHub kérésekhez a megállapításokkal. Ha a benyújtás átmegy az ellenőrzésen, akkor kérjük, ezt kifejezetten jelezd a megjegyzésben. Például valami olyasmit, hogy "Átnéztem ezt a módosítást a CONTRIBUTING dokumentumban leírtak szerint, és minden jónak tűnik számomra". Ha nem tudtad elvégezni a felülvizsgálat egyes lépéseit, akkor kérjük, kifejezetten jelezd, hogy mely lépéseket vizsgáltad felül, és melyeket nem. Például valami olyasmit, mint: "Nem ellenőriztem a kódot hibák szempontjából, de minden mást átnéztem a CONTRIBUTING dokumentumban, és úgy tűnik, hogy minden rendben van".

A beadványok tesztelését is értékeljük. Ha a kódot teszteltük, kérjük írj egy megjegyzést a GitHub kérésekhez a tesztelés eredményével - sikerrel vagy sikertelenséggel. Kérjük, kifejezetten jelezd, hogy a kódot tesztelted, és az eredményeket - például valami olyasmit, mint: "Leteszteltem ezt a kódot az Acme900Z nyomtatómon egy váza nyomtatásával, és az eredmények jók voltak".

Értékelők

A Klipper "értékelők" a következők:

Név GitHub azonosító Érdeklődési körök
Dmitry Butyugin @dmbutyugin Bemenetformálás, rezonancia vizsgálat, kinematika
Eric Callahan @Arksine Tárgyasztal szintezése, MCU égetés
James Hartley @JamesH1978 Konfigurációs fájlok
Kevin O'Connor @KevinOConnor Mag mozgási rendszer, mikrokontroller kód

Kérjük, ne "pingelje" a bírálókat, és ne küldjön beadványokat nekik. Az összes bíráló figyelemmel kíséri a fórumokat és a PR-eket, és ha van idejük, akkor vállalják a bírálatokat.

A Klipper "karbantartók" a következők:

Név GitHub név
Kevin O'Connor @KevinOConnor

A megbízási üzenetek formátuma

Minden megbízásnak a következőhöz hasonlóan formázott üzenetet kell tartalmaznia:

modul: Nagybetűs, rövid (legfeljebb 50 karakteres) összefoglaló.

Szükség esetén részletesebb magyarázó szöveg.  Körülbelül 75
karakter.  Bizonyos kontextusokban az első sort úgy kezelik,
mint a az e-mail tárgya, a szöveg többi részét pedig szövegtestként.
Az üres sor, amely elválasztja az összefoglalót a szövegtesttől, kritikus
(kivéve, ha kihagyod a törzsszöveget teljesen); az olyan eszközök,
mint a rebase, összezavarodhatnak, ha a kettőt együtt futtatják.

Az üres sorok után további bekezdések következnek..

Aláírás: Név <myemail@example.org>

A fenti példában module egy fájl vagy könyvtár neve kell, hogy legyen a tárolóban (fájlkiterjesztés nélkül). Például clocksync: Javítsuk ki a pause() hívásban lévő elírást a csatlakozás idején. A modulnév megadásának célja a kérelmi üzenetben az, hogy segítsen kontextust biztosítani a kérelmi megjegyzésekhez.

Fontos, hogy minden kérésnél legyen egy "Signed-off-by" sor. Ez igazolja, hogy egyetértesz a fejlesztői eredetigazolással. Tartalmaznia kell a valódi nevet (sajnálom, nincs álnév vagy névtelen hozzájárulás), és tartalmaznia kell egy aktuális e-mail címet.

Hozzájárulás a Klipper Fordításokhoz

Klipper-fordítási Projekt egy olyan projekt, amely a Klipper különböző nyelvekre való fordítását tűzte ki célul. A Weblate az összes Gettext stringet tárolja a fordításhoz és felülvizsgálathoz. A klipper3d.org oldalon megjeleníthetők a helyi nyelvek, ha megfelelnek a következő követelményeknek:

  • 75% Teljes lefedettség
  • Minden cím (H1) le van fordítva
  • Egy frissített navigációs hierarchia PR a klipper-fordításokban.

A domain-specifikus kifejezések fordításával járó frusztráció csökkentése és a folyamatban lévő fordítások megismerése érdekében küldhetsz PR-t, amely módosítja a Klipper-fordítási Projekt readme.md fájlt. Amint a fordítás elkészült, a Klipper-projekt megfelelő módosítása elvégezhető.

Ha egy fordítás már létezik a Klipper adattárban, és már nem felel meg a fenti ellenőrző listának, akkor egy hónap után frissítés nélkül elavultnak lesz jelölve.

Ha a követelmények teljesülnek, akkor:

  1. klipper-fordítási adattár frissítése active_translations
  2. Opcionális: adjunk hozzá egy manual-index.md fájlt a klipper-translations repository's docs\locals\<lang> mappába a nyelvspecifikus index.md helyett (a generált index.md nem renderelhető helyesen).

Ismert problémák:

  1. Jelenleg a dokumentációban nincs módszer a képek helyes fordítására
  2. Az mkdocs.yml-ben nem lehet címeket fordítani.
Back to top