From cd78248bffd01724391c9305d4db7a28720dac4a Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 16:05:42 +0000 Subject: [PATCH] Contributing translation --- docs/contributing.md | 64 +++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 34 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 3d02766..1d73758 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -4,7 +4,7 @@ DD is free software under AGPL3+ license, and contributions are welcome. ## Source code -The source code repository and techincal documentation is available at: +The source code repository and technical documentation is available at: [https://gitlab.com/DD-workspace/DD](https://gitlab.com/DD-workspace/DD) ## DD Architecture @@ -13,7 +13,7 @@ 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 +**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 @@ -22,9 +22,9 @@ Code modifications will require you to familiarize yourself with DD architecture 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. +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 build complex software systems, in our case a digital educational environment. +ASD helps building complex software systems, in our case a digital educational environment. It is organized in iterative cycles of three phases : @@ -34,10 +34,10 @@ It is organized in iterative cycles of three phases : - Criticize without hostility - Attend without resentment - Work as hard as possible - - Behave or obtain the necessary skills + - 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 team working on and reporters are a crucial part. +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. @@ -50,33 +50,32 @@ Some free online resources to familiarize yourself with ASD are: ### In practice -- 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: +- 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 **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. + 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 often collaborate with DD? Help with the pending [Merge Request][mr] reviews, keeping in mind the quality control. +- 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 controls +## Quality control ### 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`). +- 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 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. + 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. @@ -84,27 +83,24 @@ To simplify the review work and to ensure certain quality of what is integrated ### Checklist -Before testing a Merge Request, we need to do these tests on the changes introduced: +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. 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)][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 +- [ ] 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. -Si algun d'aquests passos falla, procedirem a ajudar a qui ha proposat els -canvis a solucionar els inconvenients. +If any of these steps fails, we'll try to help who requested the code merging to solve the problems. [buildbot]: https://buildbot.net -[pola]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment +[pola]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment \ No newline at end of file