digitaldemocratic/docs/contributing.md

111 lines
6.2 KiB
Markdown
Raw Normal View History

2023-04-21 23:48:54 +02:00
# Contribute
DD is free software under AGPL3+ license, and contributions are welcome.
## Source code
2023-04-22 18:18:24 +02:00
The source code repository and techincal documentation is available at:
2023-04-21 23:48:54 +02:00
[https://gitlab.com/DD-workspace/DD](https://gitlab.com/DD-workspace/DD)
## DD Architecture
2023-04-22 18:18:24 +02:00
Code modifications will require you to familiarize yourself with DD architecture.
2023-04-21 23:48:54 +02:00
![DD Workspace for education - Arquitectura](assets/diagram/dd_workspace_education.png)
2023-04-22 18:18:24 +02:00
**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
2023-04-21 23:48:54 +02:00
[diagramedit]: https://gitlab.com/DD-workspace/DD/-/tree/main/docs/assets/diagram
2023-04-22 18:18:24 +02:00
## Methodology: Adaptive software development(ASD)
2023-04-21 23:48:54 +02:00
2023-04-22 18:18:24 +02:00
In order to organize contributions, adaptive software development methodology(ASD) is used.
2023-04-21 23:48:54 +02:00
2023-04-22 18:18:24 +02:00
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.
2023-04-21 23:48:54 +02:00
2023-04-22 18:18:24 +02:00
ASD helps build complex software systems, in our case a digital educational environment.
2023-04-21 23:48:54 +02:00
2023-04-22 18:18:24 +02:00
It is organized in iterative cycles of three phases :
2023-04-21 23:48:54 +02:00
2023-04-22 18:18:24 +02:00
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:
2023-04-21 23:48:54 +02:00
2023-04-22 18:18:24 +02:00
- 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
2023-04-21 23:48:54 +02:00
2023-04-22 18:18:24 +02:00
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.
2023-04-21 23:48:54 +02:00
2023-04-22 18:18:24 +02:00
By applying this methodology in an iterative way, we improve the project incrementally.
2023-04-21 23:48:54 +02:00
2023-04-22 18:18:24 +02:00
Some free online resources to familiarize yourself with ASD are:
2023-04-21 23:48:54 +02:00
- [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)
2023-04-23 16:20:45 +02:00
### In practice
2023-04-21 23:48:54 +02:00
2023-04-23 16:20:45 +02:00
- Do you find any issue? Help us reporting the [issue][issues].
- Do you want to add a patch? You'll find useful information in section quality control below. Depending on how complex are your changes:
2023-04-21 23:48:54 +02:00
2023-04-23 16:20:45 +02:00
- Simple changes: Open a [Merge Request][mr]
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][issues] explaining what are you trying to to do, also why and how.
2023-04-21 23:48:54 +02:00
2023-04-23 16:20:45 +02:00
- Do you often collaborate with DD? Help with the pending [Merge Request][mr] reviews, keeping in mind the quality control.
2023-04-21 23:48:54 +02:00
[issues]: https://gitlab.com/DD-workspace/DD/-/issues
[mr]: https://gitlab.com/DD-workspace/DD/-/merge_requests
2023-04-23 16:20:45 +02:00
## Quality controls
2023-04-21 23:48:54 +02:00
### Continuous Integration
2023-04-23 16:20:45 +02:00
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][mr] review proces.
- ** TO BE REVIEWED ( branch based events?? )** There is a [buildbot][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][mr] events in any other branch.
- When the event is a [Merge Request][mr], 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][mr] 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.
2023-04-21 23:48:54 +02:00
### Checklist
2023-04-23 16:20:45 +02:00
Before testing a Merge Request, we need to do these tests on the changes introduced:
2023-04-21 23:48:54 +02:00
2023-04-23 16:20:45 +02:00
- [ ] 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**
2023-04-21 23:48:54 +02:00
- [ ] 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