Stashed Contribute translation
Aleix Quintana Alsius
parent
04bfebf2e9
commit
fa765bbc66
|
|
@ -0,0 +1,143 @@
|
|||
# Contribute
|
||||
|
||||
DD is free software under AGPL3+ license, and contributions are welcome.
|
||||
|
||||
## Source code
|
||||
|
||||
The source code repository and techincal documentation are in:
|
||||
[https://gitlab.com/DD-workspace/DD](https://gitlab.com/DD-workspace/DD)
|
||||
|
||||
## DD Architecture
|
||||
|
||||
Per molts canvis serà necessari que us familiaritzeu amb l'arquitectura del DD.
|
||||
|
||||
El diagrama d'arquitectura del DD es troba al repositori en format
|
||||
[editable][diagramedit], i hi podeu contribuir com amb qualsevol altre canvi.
|
||||
|
||||
|
||||
|
||||
[diagramedit]: https://gitlab.com/DD-workspace/DD/-/tree/main/docs/assets/diagram
|
||||
|
||||
|
||||
## Metodología: Desenvolupament Adaptatiu de Software (ASD)
|
||||
|
||||
Per tal d'organitzar-nos fem servir la metodologia de
|
||||
Desenvolupament Adaptatiu de Software
|
||||
(o ASD per les seves sigles en anglès Adaptive Software Development).
|
||||
|
||||
Aquesta metodologia posa el focus en les dinàmiques d'equips auto-organitzats,
|
||||
la col·laboració interpersonal i l'aprenentatge individual i dels equips
|
||||
de manera que ens permet integrar fàcilment la naturalesa *Open Source*
|
||||
del **DD** amb els cicles de feedback o d'actualització a les escoles que fan
|
||||
part del projecte Pilot i les necessitats tècniques del projecte.
|
||||
|
||||
ASD ajuda a construir sistemes de software complexes, en el nostre cas un
|
||||
entorn educatiu digital.
|
||||
|
||||
S'organitza en cicles iteratius de 3 fases:
|
||||
|
||||
1. **Especulació**: En aquesta fase planegem tenint en compte les limitacions i
|
||||
necessitats del projecte, dels usuaris, etc. (en forma de [Issues][issues],
|
||||
feedback o incidències) per tal de definir els cicles que volem.
|
||||
2. **Col·laboració**: En aquesta fase ens organitzem i treballem conjuntament,
|
||||
sempre tenint en compte que les persones que treballen juntes han de:
|
||||
|
||||
- Criticar sense hostilitat
|
||||
- Assistir sense ressentiment
|
||||
- Treballar el més fortament possible
|
||||
- Tenir o obtenir les habilitats necessàries
|
||||
- Comunicar els problemes que eviten trobar una solució efectiva
|
||||
|
||||
3. **Aprenentatge**: Tant si arribem al resultat desitjat com si no, aquest
|
||||
procés haurà incrementat l'enteniment del projecte i les tecnologies
|
||||
associades de totes les persones que hi participen.
|
||||
En aquest procés una part crucial són les [Merge Request][mr] i les revisions
|
||||
(**Reviews**) associades, així com la comunicació de l'equip que hi treballa.
|
||||
|
||||
Aplicant aquesta metodologia de manera iterativa anem millorant el projecte
|
||||
incrementalment.
|
||||
|
||||
Alguns recursos online gratuïts per familiaritzar-s'hi són:
|
||||
|
||||
- [https://users.exa.unicen.edu.ar/catedras/agilem/cap23asd.pdf](https://users.exa.unicen.edu.ar/catedras/agilem/cap23asd.pdf)
|
||||
- [https://www.geeksforgeeks.org/adaptive-software-development-asd/](https://www.geeksforgeeks.org/adaptive-software-development-asd/)
|
||||
- [https://yewtu.be/watch?v=HXJWwxL2N5A](https://yewtu.be/watch?v=HXJWwxL2N5A)
|
||||
- [https://files.ifi.uzh.ch/rerg/amadeus/teaching/seminars/seminar_ws0304/06_Eberle_ASD_Folien.pdf](https://files.ifi.uzh.ch/rerg/amadeus/teaching/seminars/seminar_ws0304/06_Eberle_ASD_Folien.pdf)
|
||||
|
||||
### En la pràctica
|
||||
|
||||
- Has detectat un problema? Ajuda'ns reportant un [problema/issue][issues].
|
||||
- Vols afegir un parche? Et pot ser útil l'apartat dels controls de qualitat
|
||||
tot seguit. En funció de la complexitat dels teus canvis:
|
||||
|
||||
- Si en són senzills, obre directament una [Merge Request][mr]
|
||||
explicant el que vols afegir i per què.
|
||||
D'aquesta manera iniciarà el procés de **revisió/review**.
|
||||
- Si en són més complicats, potser posa't en contacte abans perquè puguem
|
||||
avaluar si la teva solució és la que més s'adjusta al projecte.
|
||||
Una bona manera de fer-ho és obrint una [issue][issues] explicant el que
|
||||
vols fer, per què i com.
|
||||
|
||||
- Col·labores habitualment amb el DD? Ajuda amb les revisions de codi de les
|
||||
[Merge Request][mr] pendents, tenint en compte els controls de qualitat.
|
||||
|
||||
[issues]: https://gitlab.com/DD-workspace/DD/-/issues
|
||||
[mr]: https://gitlab.com/DD-workspace/DD/-/merge_requests
|
||||
|
||||
## Controls de qualitat
|
||||
|
||||
### Continuous Integration
|
||||
|
||||
Per simplificar la feina de revisió de codi i assegurar una certa qualitat del
|
||||
que entra al repositori:
|
||||
|
||||
- Ningú pot fer `push` a la branca principal (`main`) directament.
|
||||
Sempre és necessari passar pel procés de [Merge Request][mr] i review.
|
||||
- Disposem d'una instància de [buildbot][buildbot] com a Continuous Integration
|
||||
(a `ci.dd-work.space`, login amb GitLab) que reacciona a esdeveniments de
|
||||
tipus `push` al repositori principal, i de tipus [Merge Request][mr] des de
|
||||
qualsevol repositori.
|
||||
- Quan es tracta d'un [Merge Request][mr], només s'executen comprovacions
|
||||
de estàtiques, que no executen el codi del repositori.
|
||||
Això és per evitar abús de tipus mineria de criptomonedes i demés.
|
||||
Aquestes comprovacions ara mateix són:
|
||||
[ShellCheck][sc] per scripts de shell, [mkdocs][mkdocs] per comprovar
|
||||
que la documentació es genera correctament, i aviat hi afegirem linters i
|
||||
comprovadors estàndard de Python.
|
||||
- Quan es tracta d'un esdeveniment `push` al repositori principal,
|
||||
addicionalment a les comprovacions anteriors, es comença el procés
|
||||
d'instal·lació des de zero en una màquina virtual.
|
||||
Això ajuda a detectar quan s'introdueixen problemes i a assegurar que el
|
||||
DD es pot instal·lar correctament.
|
||||
- Els membres del grup `DD-workspace` a GitLab tenen permisos d'administració a
|
||||
la instància de Buildbot, això els permet iniciar builds manualment o
|
||||
cancel·lar tasques si és necessari.
|
||||
|
||||
### Checklist
|
||||
|
||||
Abans d'aprovar una Merge Request, hem de fer les següents comprovacions als
|
||||
canvis que es volen introduir:
|
||||
|
||||
- [ ] Passen les comprovacions a la CI
|
||||
- [ ] Les modificacions introduïdes són necessàries, solucionen un problema
|
||||
real, o milloren la mantenibilitat del projecte
|
||||
- [ ] Es consideren i debaten les implicacions de **seguretat**
|
||||
- [ ] Es consideren i debaten les implicacions de **mantenibilitat**
|
||||
- [ ] Es revisen possibles regressions de funcionalitat
|
||||
- [ ] No s'utilitzen dades reals en les proves
|
||||
- [ ] El resultat de la instal·lació des de zero en el CI és satisfactori
|
||||
- [ ] És possible crear i modificar grups i usuaris
|
||||
- [ ] És possible iniciar sessió amb SSO a Moodle, Nextcloud i Wordpress
|
||||
- [ ] Es respecta el [Principi de mínima sorpresa (Principle Of Least Attonishment / POLA)][pola]
|
||||
- [ ] Això inclou que es respectin les configuracions explícites
|
||||
dels operadors (`dd.conf`)
|
||||
- [ ] Les funcionalitats noves que puguin tenir efectes negatius, només
|
||||
s'aplicaran per defecte, quan els operadors hagin tingut temps
|
||||
suficient de desactivar-les abans
|
||||
|
||||
|
||||
Si algun d'aquests passos falla, procedirem a ajudar a qui ha proposat els
|
||||
canvis a solucionar els inconvenients.
|
||||
|
||||
[buildbot]: https://buildbot.net
|
||||
[pola]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment
|
||||
Loading…
Reference in New Issue