106 lines
6.1 KiB
Markdown
106 lines
6.1 KiB
Markdown
# Contribute
|
|
|
|
DD is free software under AGPL3+ license, and contributions are welcome.
|
|
|
|
## Source code
|
|
|
|
The source code repository and technical 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.
|
|
|
|
|
|
|
|
**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.
|
|
|
|
[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 integrating the *Open Source* nature of **DD** with feedback, technical needs and update cycles in the schools that are part of the pilot project.
|
|
|
|
ASD helps building 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
|
|
- Provide 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 work team 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)
|
|
|
|
### In practice
|
|
|
|
- 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:
|
|
|
|
- Simple changes: Open a [Merge Request][mr]
|
|
explaining what are you adding and why.
|
|
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.
|
|
|
|
- Do you collaborate with DD often? Help us with the pending [Merge Request][mr] reviews, keeping in mind the quality control.
|
|
|
|
[issues]: https://gitlab.com/DD-workspace/DD/-/issues
|
|
[mr]: https://gitlab.com/DD-workspace/DD/-/merge_requests
|
|
|
|
## Quality control
|
|
|
|
### Continuous Integration
|
|
|
|
To simplify the review work and to ensure certain quality of what is integrated in repository:
|
|
|
|
- Nobody can `push` commits directly 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 [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.
|
|
- 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.
|
|
|
|
### Checklist
|
|
|
|
Before integrating a Merge Request, we need to make sure that this checklist is passed:
|
|
|
|
- [ ] CI Tests passing.
|
|
- [ ] 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 whoever has requested the code merge to solve the problems.
|
|
|
|
[buildbot]: https://buildbot.net
|
|
[pola]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment |