digitaldemocratic/docs/contributing.md

# Contribute

DD is free software under AGPL3+ license, and contributions are welcome.

## Source code

The source code repository and techincal documentation is available at:
[https://gitlab.com/DD-workspace/DD](https://gitlab.com/DD-workspace/DD)

## DD Architecture

Code modifications will require you to familiarize yourself with DD architecture.

![DD Workspace for education - Arquitectura](assets/diagram/dd_workspace_education.png)

**Note** This DD architecture diagram can be found in code respository in [editable][diagramedit] format. Like the rest of the whole code, you can suggest modifications

[diagramedit]: https://gitlab.com/DD-workspace/DD/-/tree/main/docs/assets/diagram


## Methodology: Adaptive software development(ASD)

In order to organize contributions, adaptive software development methodology(ASD) is used.

This methodology focuses on self-organized team dynamics, interpersonal collaboration, and individual and team learning in a way that allows integrate the *Open Source* nature of **DD** with feedback or update cycles in the schools that are part of the pilot project and the technical needs of the project.

ASD helps build complex software systems, in our case a digital educational environment.

It is organized in iterative cycles of three phases :

1. **Speculation**: In this phase a plan is made taking into account limitations and needs of the project, users, etc. writing issues, feedback or failures, in order to define the cycles.
2. **Collaboration**: In this phase we organize and work together, always taking care that working people must:

    - Criticize without hostility
    - Attend without resentment
    - Work as hard as possible
    - Behave or obtain the necessary skills
    - Communicate the issues that prevent finding an effective solution

3. **Learning**: Whether a desired result is reached or not, this process will help everyone involved, as it will increase the understanding of the project and its associated technologies. While working together [Merge Request][mr] and their associated reviews, as well as the communication between team working on and reporters are a crucial part.

By applying this methodology in an iterative way, we improve the project incrementally.

Some free online resources to familiarize yourself with ASD are:

- [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