Pe măsură ce ne apropiem de aniversarea decenală (10 ani) de la înființarea Jumping Rivers în 2016, este un moment bun să reflectăm la ceea ce am realizat în acea perioadă și să împărtășim câteva lecții învățate.
Dacă ați citit anterior blogurile noastre, atunci veți fi conștienți de faptul că Jumping Rivers este un furnizor de consultanță și instruire în toate aspectele științei datelor. Dar știați că oferim peste 50 de cursuri diferite, cuprinzând R, Python, Git, SQL și multe altele?
În acest blog vom oferi o privire asupra procesului nostru intern și vom împărtăși modul în care am simplificat sarcina de a menține atât de multe cursuri. Pe parcurs vom împărtăși câteva bune practici aplicabile oricărui proiect mare de codare, inclusiv ambalarea codului sursă și CI/CD automatizat.
Provocarea
Să începem prin a prezenta provocările cheie cu care ne confruntăm.
1. Suport multilingv
Catalogul nostru de cursuri este format din peste 50 de cursuri. Majoritatea acestora se bazează fie pe R, fie pe Python sau pe ambele:
- 50% R
- 30% Python
- 5% R și Python
- 15% altele (Git, SQL, Tableau, Posit și multe altele)
Cel puțin, orice soluție pe care o găsim pentru standardizarea cursurilor noastre trebuie să fie compatibilă atât cu R, cât și cu Python. În mod ideal, ar trebui să accepte și unele limbi mai puțin predate, inclusiv SQL și Git.
2. Întreținere
Lumea lui R și Python este în continuă schimbare. Limbile în sine primesc actualizări frecvente, la fel ca și pachetele R disponibile public pe CRAN și pachetele Python pe PyPI.
Acest lucru are drept consecință că codul care a funcționat cu un an în urmă (sau chiar o zi) ar putea să nu mai fie funcțional cu cele mai recente versiuni de pachet. Vom avea nevoie de o modalitate de a urmări acest lucru și de a ne asigura că exemplele de cod acoperite în cursurile noastre rămân relevante și fără erori.
3. Cerere
Livrăm peste 100 de cursuri pe an. Pentru o echipă relativ mică de cercetători ai datelor, acest lucru poate fi mult de jonglat!
Într-o lume ideală, procesul de construire a materialelor de curs, de configurare a mediului cloud pentru instruire și de gestionare a întregii administrații care însoțește acest lucru ar trebui automatizat. În acest fel, trainerul se poate concentra pe oferirea unei experiențe de cea mai înaltă calitate pentru participanți, fără a fi nevoit să-și facă griji că lucrurile merg prost în ziua respectivă.
Solutia
Echipa noastră este obișnuită să configureze fluxuri de lucru pentru știința datelor pentru clienți, inclusiv raportarea automată și migrarea codului sursă în pachete. Prin urmare, am aplicat aceste tehnici în procesele noastre interne, inclusiv în formare.
Raportare automată
Scrieți un document care trebuie actualizat în mod regulat; aceasta poate include o prezentare lunară care arată cele mai recente venituri ale companiei. Sună cunoscut acest scenariu?
Noi putea regenerați diagramele și tabelele de date și copiați și lipiți-le manual în documentul de raport. Și mai bine, putem profita de cadrele de raportare automate gratuite, inclusiv R Markdown și Quarto.
R Markdown și Quarto funcționează ambele după cum urmează:
-
Oferim un „antet YAML” în partea de sus a documentului de raport cu opțiuni de configurare și formatare:
--- title: "Introduction to Python" authors: - "Myles Mitchell" date: "2026-04-02" output: pdf ---
-
Corpul raportului este formatat ca Markdown și acceptă un amestec de text simplu și cod:
## Introduction At it's most basic, Python is essentially a calculator. We can run basic calculations as follows: ```{python} 2 + 1 ``` We can also assign the output of a calculation to a variable so that it can be reused later: ```{python} x = 2 + 1 print(x) ```
Observați că am inclus bucăți de cod Python. Făcând uz de opțiuni de bucată putem configura fragmente de cod care să fie executate la randarea raportului. Orice ieșiri din cod (ploturi, tabele, statistici rezumate) pot fi apoi afișate.
Migrând logica codului în raportul însuși, ne putem actualiza elementele raportului cu un clic pe un buton ori de câte ori datele se modifică.
Ne-am inspirat din această abordare cu notele noastre de curs și cu slide-urile de prezentare. Acest lucru ne obligă să fim riguroși cu exemplele de cod. Orice erori de rulare care sunt produse de cod defect sau învechit vor fi vizibile în notele cursului și, prin extensie, pentru participanții la cursurile noastre.
Esențial pentru noi, R Markdown și Quarto sunt ambele compatibile cu R și Python. Aceștia acceptă, de asemenea, evidențierea sintaxelor pentru limbi precum Git și SQL, precum și o varietate de formate de ieșire, inclusiv HTML și PDF.
Pachete R interne
Așa că ne-am hotărât pe o soluție pentru construirea notelor noastre de curs. Dar avem 50 de cursuri diferite și configurarea acestora de la zero de fiecare dată va deveni plictisitoare!
O bună practică în orice proiect de codare este de a evita cât mai mult posibil duplicarea. În loc să copiem și să lipim cod, ar trebui să migrăm codul în funcții care sunt autonome, reutilizabile și ușor de testat. Acest lucru va însemna mai puține locuri de depanat atunci când lucrurile merg prost inevitabil.
Urmând o filozofie similară pentru infrastructura noastră de instruire, am migrat orice active reutilizabile pentru cursurile noastre – inclusiv logo-uri, fișiere șablon și stil – într-o colecție de pachete R interne.
Când construiește un nou curs, dezvoltatorul se poate concentra acum pe aspectele care sunt unice pentru acel curs:
- Exemple de coduri
- Note
- Exerciții
- Diapozitive de prezentare
De orice altceva se ocupă automat:
- Apariția notelor de curs și a diapozitivelor de prezentare.
- Creați rutine, inclusiv conversia fișierelor text R Markdown / Quarto în HTML.
Pe lângă șabloanele de curs, avem și pachete interne pentru gestionarea laturii administrative a formării, inclusiv:
- Calcularea ofertelor de preț pentru clienți.
- Generarea de certificate post-curs.
- Crearea unui mediu Posit Workbench personalizat pentru curs.
- Rezumat feedback-ul participanților.
Și lista continuă!
GitLab CI/CD
Cu raportarea automată și ambalarea codului sursă, am creat rutine standardizate care pot fi aplicate oricărui dintre cursurile noastre.
Acest lucru nu schimbă faptul că avem peste 50 de cursuri de întreținut. Încă avem nevoie de o modalitate de a ne testa cursurile și de a urmări problemele. Aici intervine CI/CD (Continuous Integration/Continuous Development and Deployment).
CI/CD definește un cadru pentru dezvoltarea software, inclusiv:
- Testare unitară automată.
- Ramificarea codului sursă și revizuirea codului.
- Versiune și implementare de software.
- Instrumente CI/CD pentru testarea, construirea și implementarea automată.
- Reguli de ramură pentru aplicarea bunelor practici, cum ar fi revizuirea codului și testarea unitară.
- Versiune și etichetare a codului sursă.
Fiecare dintre cursurile noastre este menținut prin intermediul propriului său depozit GitLab. Conductele CI/CD pentru cursurile noastre sunt definite într-un depozit separat împreună cu pachetele interne R menționate mai sus.
La configurarea unui nou curs, depozitul de curs va fi completat automat cu regulile șablon CI/CD. Prin urmare, toate cursurile sunt supuse acelorași verificări stricte, inclusiv:
- Asigurarea faptului că notele de curs sunt construite fără erori.
- Implementarea revizuirii codului oricăror actualizări de curs înainte ca acestea să fie îmbinate în ramura principală.
- Construirea și depozitarea artefacte (notele HTML redate și scripturile de codare) pentru cea mai recentă versiune a cursului.
Aceste verificări sunt declanșate de orice actualizări ale unui curs. Programăm, de asemenea, conducte lunare CI/CD pentru toate cursurile, cu orice problemă semnalată imediat formatorilor noștri.
De asemenea, am profitat de structura de tip folder a GitLab pentru organizarea depozitelor de cod. În cadrul proiectului Jumping Rivers de pe GitLab, avem un subproiect numit „antrenament”. Toate depozitele noastre legate de curs sunt situate „în aval” de acest proiect. Aceasta înseamnă că orice setări sau variabile de mediu definite la nivel de „antrenament” sunt aplicate automat tuturor cursurilor noastre.
În concluzie
Lecțiile de la acest blog sunt aplicabile oricărui proiect mare de codificare:
- Evitați duplicarea: migrați orice logică sau active reutilizabile în pachete independente.
- Utilizați fluxurile de lucru CI/CD folosind GitLab, GitHub sau similar.
- Concentrează-te pe ceea ce contează prin automatizarea cât mai mult posibil din proces.
Construirea infrastructurii noastre de formare a durat 10 ani și este încă în continuă evoluție; nici măcar nu am acoperit întregul proces în acest blog! Pentru o scufundare mai profundă, consultați această discuție a lui Myles la SatRdays London 2024.
Pentru mai multe despre raportarea automată, consultați:
Pentru mai multe despre ambalarea codului sursă, consultați:
Pentru actualizări și revizuiri ale acestui articol, consultați postarea inițială
