digitaldemocratic/docs/contributing.md

106 lines
6.1 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-23 18:05:42 +02:00
The source code repository and technical 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-23 18:05:42 +02:00
**Note** This DD architecture diagram can be found at code respository in [editable][diagramedit] format. Like the rest of the whole code, you can suggest modifications.
2023-04-22 18:18:24 +02:00
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-23 18:05:42 +02:00
This methodology focuses on self-organized team dynamics, interpersonal collaboration, and individual and team learning in a way that allows integrating the *Open Source* nature of **DD** with feedback, technical needs and update cycles in the schools that are part of the pilot project.
2023-04-21 23:48:54 +02:00
2023-04-23 18:05:42 +02:00
ASD helps building 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
2023-04-23 18:05:42 +02:00
- Provide or obtain the necessary skills
2023-04-22 18:18:24 +02:00
- Communicate the issues that prevent finding an effective solution
2023-04-21 23:48:54 +02:00
2023-04-23 18:05:42 +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 work team 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 18:05:42 +02:00
- Did you find any issue? Help us reporting the [issue][issues].
- Do you want to add a patch? You'll find useful information in quality control section 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.
2023-04-23 18:05:42 +02:00
Doing so, a new **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 you want to do.
2023-04-21 23:48:54 +02:00
2023-04-23 18:05:42 +02:00
- Do you collaborate with DD often? Help us 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 18:05:42 +02:00
## Quality control
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:
2023-04-23 18:05:42 +02:00
- Nobody can `push` commits directly to `main` branch (`main`).
2023-04-23 16:20:45 +02:00
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.
2023-04-23 18:05:42 +02:00
These checks are [ShellCheck][sc] for shell scripts, [mkdocs][mkdocs] to check that the documentation is generated as it should. Also, we will add soon linters and standard python checks.
2023-04-23 16:20:45 +02:00
- 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 18:05:42 +02:00
Before integrating a Merge Request, we need to make sure that this checklist is passed:
2023-04-21 23:48:54 +02:00
2023-04-23 16:20:45 +02:00
- [ ] CI Tests passing.
2023-04-23 18:05:42 +02:00
- [ ] The changes are needed, and solves a real problem.
- [ ] The changeset improves the maintenance of the project.
- [ ] **Security** implications are considerated and debated.
- [ ] **Manteinance** implications are considerated and debated.
- [ ] **Functional** regressions are reviewed.
- [ ] Tests are not done using real data.
- [ ] Succesful installation result from the scratch in CI.
- [ ] Is possible to create and update groups and users
- [ ] Is possible to start a sessions with SSO in Moodle, Nextcloud and Wordpress.
- [ ] Respect of [Principle Of Least Attonishment / POLA][pola]
- [ ] This includes respecting explicit configurations of operators(defined in `dd.conf`)
- [ ] The new features which may have negative effects, only will be applied by default when operators did have enough time to disable these before.
If any of these steps fails, we'll try to help who requested the code merging to solve the problems.
2023-04-21 23:48:54 +02:00
[buildbot]: https://buildbot.net
2023-04-23 18:05:42 +02:00
[pola]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment