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

DD Architecture

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

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

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 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://www.geeksforgeeks.org/adaptive-software-development-asd/
• https://yewtu.be/watch?v=HXJWwxL2N5A
• https://files.ifi.uzh.ch/rerg/amadeus/teaching/seminars/seminar_ws0304/06_Eberle_ASD_Folien.pdf

In practice

• Do you find any issue? Help us reporting the issue.

• Do you want to add a patch? You'll find useful information in section quality control below. Depending on how complex are your changes:

  • Simple changes: Open a Merge Request explaining what are you adding and why. Doing so a review process will be started.
  • Complex changes: contact us before to decide if your solution is the optimal one for the project. A good way of doing so is opening an issue explaining what are you trying to to do, also why and how.

• Do you often collaborate with DD? Help with the pending Merge Request reviews, keeping in mind the quality control.

Quality controls

Continuous Integration

To simplify the review work and to ensure certain quality of what is integrated in repository:

• Nobody can direct push to main branch (main). Always is necessary to follow the Merge Request review proces.
• ** TO BE REVIEWED ( branch based events?? )** There is a buildbot instance (in ci.dd-work.space, login via GitLab) as a Continuous Integration that reacts to push events in main branch and to Merge Request events in any other branch.
  • When the event is a Merge Request, only static checks are executed, so no complete tests are launched. This is to prevent crypto mining CI/CD abuse. These checks are the same as: [ShellCheck][sc] for shell scripts, [mkdocs][mkdocs] to check that the documentation is generated as it should, soon we'll add linters and standard python checks.
  • When the event is a push to main, additionally to the Merge Request tests, it will start the installation process from the scratch in a virtual machine. This helps in detecting problems and makes sure that DD can be correctly.
• Members of group DD-workspace in Gitlab have administration permissions in Buildbot instance, this allow them to start or cancel build tasks manually if it is required.

Checklist

Before testing a Merge Request, we need to do these tests on the changes introduced:

• CI Tests passing.
• The changes are needed, and solves a real problem. Also the changeset improves the maintenance of the project.
• ConsiderateEs 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)
  • 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.