Contributing guide

ARCHITECTURE.md

@@ -0,0 +1,159 @@
+# Architecture
+
+This document provides an overview over the architecture of RDMO and provides information about the different modules.
+
+## Core dependencies
+
+RDMO is a [Django](https://www.djangoproject.com/) application with an integrated [React](https://react.dev/) frontend.
+
+On the backend, it makes heavy use of:
+
+* [Django Rest Framework](https://www.django-rest-framework.org/) (DRF) for the REST API,
+* [rules](https://github.com/dfunckt/django-rules) for object based permissions.
+
+The frontend code relies on:
+
+* [webpack](https://webpack.js.org) for bundling,
+* [Redux](https://redux.js.org/) for state management,
+* [Redux Thunk](https://github.com/reduxjs/redux-thunk) for asynchronous Redux actions,
+* [Bootstrap](https://getbootstrap.com/) as CSS framework,
+* [lodash](https://lodash.com/) for various utilities.
+
+Testing is done with:
+
+* [pytest](https://docs.pytest.org) for the backend,
+* [Playwright](https://playwright.dev) for the frontend.
+
+## File layout
+
+The main `rdmo` package consists of the following modules:
+
+```
+rdmo/
+├── core/              ← Core functionality
+├── accounts/          ← Authentication & user profiles
+├── domain/            ← Domain model
+├── questions/         ← Structure of the questionnaire
+├── conditions/        ← Conditional display of questions or answers
+├── options/           ← Controlled vocabularies for answers
+├── tasks/             ← Follow up actions based on answers
+├── views/             ← Templating for output and export
+├── projects/          ← User projects, snapshots and answers
+├── management/        ← Management editing backend
+└── services/          ← OAuth / external integrations
+```
+
+Each module (an *app* in Django terms) tries to follow the conventional layout and naming conventions:
+
+* `admin.py` → Django admin interface configuration
+* `apps.py` → Django app configuration
+* `assets/` → Source files for the frontend (JavaScript, CSS, ...)
+* `constants.py` → Definition of constant values
+* `exports.py` → Export plugin functionality
+* `filters.py` → Filters for DRF viewsets
+* `forms.py` → Django forms
+* `handlers/` or `handlers.py` → Handlers for Django signals
+* `imports.py` → Helper functionality for the XML import
+* `managers.py` → Managers for Django models
+* `migrations/` → Django database migrations
+* `mixins.py` → Mixins for different classes
+* `models/` or `models.py` → Django database models
+* `permissions.py` → DRF permission classes
+* `providers.py` → Optionset provider plugins
+* `renderers/` or `renderers.py` → Render functionality for the XML export
+* `rules.py` → Object based permissions
+* `serializers/` or `serializers.py` → DRF serializers
+* `signals.py` → Signals for Django signals
+* `static/` → Build front end assets, ignored by Git
+* `templates/` → Django templates
+* `templatetags/` → Django template tags and filters
+* `tests/` → Tests
+* `urls/` or `urls.py` → Django URL mapping
+* `utils.py` → Utility functions
+* `validators.py` → Additional validators for DRF
+* `views/` or `views.py` → Django views
+* `viewsets.py` → DRF viewsets for the REST API
+
+In addition, the `rdmo` repository contains the following notable files or directories:
+
+* `pyproject.toml` → Python package configuration
+* `rdmo/locale` → Translation files
+* `rdmo/share` → Supplemental files
+* `testing` → Test configuration & fixtures
+* `conftest.py` → pytest setup
+* `webpack.config.js` → Frontend build configuration
+* `package.json` and `package-lock.json` → Frontend dependencies
+
+The `assets` directories in the modules use the following structure:
+
+* `assets/js/` → JavaScript front-end code, separated by React app
+    * `actions/` → Actions for the Redux store
+    * `api/` → API classes with methods mapping the endpoints of the REST API
+    * `components/` → React components
+    * `factories/` → Factory functions for front end objects
+    * `hooks/` → React hooks
+    * `reducers/` → Reducers for the Redux store
+    * `store/` → Configuration and initialization of the Redux store
+    * `utils/` → Utility functions
+* `assets/scss/` → Sass files, separated by React app
+* `assets/fonts/`, `assets/img/` → Additional, static assets
+
+## Internal dependencies
+
+```plain
+┌────────────┐         ┌────────────┐
+│ core       │◀───┬────┤ accounts   │
+└────────────┘    │    └────────────┘
+                  │    ┌────────────┐         ┌────────────┐
+                  ├────┤ domain     │◀───┬────┤ projects   │
+                  │    └────────────┘    │    └────────────┘
+                  │    ┌────────────┐    │    ┌────────────┐
+                  ├────┤ conditions │◀───┼────┤ management │
+                  │    └────────────┘    │    └────────────┘
+                  │    ┌────────────┐    │
+                  ├────┤ options    │◀───┤
+                  │    └────────────┘    │
+                  │    ┌────────────┐    │
+                  ├────┤ questions  │◀───┤
+                  │    └────────────┘    │
+                  │    ┌────────────┐    │
+                  ├────┤ tasks      │◀───┤
+                  │    └────────────┘    │
+                  │    ┌────────────┐    │
+                  └────┤ views      │◀───┘
+                       └────────────┘
+```
+
+The modules depend on each other in the following way:
+
+* `core` does not depend on the other modules.
+* `accounts` does only depend on `core`.
+* `conditions`, `domain`, `options`, `questions`, `tasks`, `views` depend only on `core` (with the exception that the `options.Optionset` model and the `conditions.Condition` depend on each other).
+* `project` and `management` depend on `conditions`, `domain`, `options`, `questions`, `tasks`, `views` and `core`.
+
+Besides those dependencies:
+
+* `utils.py` and `managers.py` must not depend on anything inside the module.
+* `models.py` must only depend on `utils.py` and `managers.py`.
+
+If utility functions, which depend on the models are needed, they are put in special files, e.g. `process.py`. Utility functions for tests are placed in `tests/helpers.py`.
+
+Only after careful consideration, functions can use local imports (in the function body) to circumvent the described dependency rules.
+
+## Backend considerations
+
+RDMO tries to follow the conventional style of Django projects. It should work with all database backends and with all common web server setups. The aim is to limit the dependencies and the effort to maintain an instance to a minimum. For the same reason, RDMO does not depend on a caching solution or an infrastructure for asynchronous tasks.
+
+While some parts of RDMO use the common Django MVC-pattern using models, (class-based) views and templates, other parts use the Django Rest Service pattern using viewsets, serializers and renderers. The latter is used by the interactive frontend (see below), but also as scriptable API.
+
+## Frontend considerations
+
+As already mentioned, major parts of RDMO are implemented as separate interactive *single page applications*. In particular:
+
+* the projects table located at `/projects/`,
+* the project dashboard located at `/projects/<id>/`,
+* the management interface located at `/management/`.
+
+The Django template of these pages contain just an empty element, and the functionality is implemented with JavaScript, React and Redux, and makes heavy use of the REST API.
+
+In order to keep the deployment effort low, no node dependencies need to be handled by the maintainers of the instances. Instead, the frontend is build when creating the release and is then shipped as part of the `rdmo` Python package. Frontend source files reside in `rdmo/<module>/assets/` and the build is stored in `rdmo/<module>/static/`, from where Django handles them as regular static files.

CODE_OF_CONDUCT.md

@@ -1,30 +1,33 @@
-Code of Conduct
-===============
+# Code of Conduct
 
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+We as contributors and maintainers pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
 
-Examples of behavior that contributes to creating a positive environment include:
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+Examples of behavior that contributes to a positive environment for our community include:
 
-Examples of unacceptable behavior by participants include:
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
 
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
 * Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Publishing others' private information, such as a physical or email address, without their explicit permission
 * Other conduct which could reasonably be considered inappropriate in a professional setting
 
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+Maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
 
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+This Code of Conduct applies within all spaces maintained by the **RDMO. Research Data Management Organiser e.V.** ("RDMO e.V."), including the GitHub organization at <https://github.com/rdmorganiser>, the RDMO mailing list, the RDMO Matrix space, and any other communication channels operated on behalf of the community. It also applies when an individual is representing the community in public spaces.
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at rdmo-team@listserv.dfn.de. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the RDMO e.V. at <contact@rdmo.org>. All complaints will be reviewed and investigated, and will receive a response that is deemed appropriate to the circumstances. The RDMO e.V. is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
 
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+Maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by the board (*Vorstand*) of the RDMO e.V.
 
-This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.4, available at http://contributor-covenant.org/version/1/4.
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), drawing from versions [1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct/) and [2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).