Technical Onboarding

Note: This document's purpose is meant to serve as a technical onboarding guide for new developers to the UIPA.org project. For a top level view of the project, start with the Wiki.

Need help or want to discuss things?

The #project-uipa channel in the codewithaloha.slack.com is the right place to chat. If you are setting up your development environment for the first time, please follow one of the guides (to be done) to start contributing.

How can I help?

The UIPA.org Development Board is how we keep track of the work to be done. It's a Github Task Board but let's call it our project board. It can be difficult to understand all of the issues so this project board will be kept up to date so we can all see what needs to be done and what's being worked on.

Overview

Froide is a Freedom of Information portal software written in Python using the Django framework. It uses the built-in Django Admin interface to manage and update entities. User management and authentication are also handled by the Django framework.

The name, Froide, comes from "Freedom of Information de" where de stands for Germany.

For more information about Froide, check out its docs and repository. Unfortunately, the docs are stuck in 2018 as can be seen by the reference to Django 1.11 (the last version to support Python 2.7) vs 5.0.3 (released 03/04/2024).

If you aren't familiar with Django, some of the commands used can be explained by referring to https://docs.djangoproject.com/en/4.2/ref/django-admin/. It is preferrable to use python manage.py instead of django-admin because it is more specific to the project that you are currently working on.

UIPA.org is built from the core repo is CodeWithAloha/uipa which is a modified Froide theme. The theme pulls in the portal software CodeWithAloha/froide which is a modified Froide. uipa pulls in froide when the Python requirements are installed.

For the most part, you'll be working with CodeWithAloha/uipa, and not CodeWithAloha/froide. See Theming Froide for a quick explanation.

This is how this all works together:

flowchart LR
    t1[Froide Theme]
    a1[/fork/]
    u1[uipa theme]
    f1[Froide]
    a2[/fork/]
    u2[uipa froide]
    a3[/install requirements/]
    u3[working code base]
    t1 --> a1 --> u1
    f1 --> a2 --> u2
    u1 --> a3
    u2 --> a3
    a3 --> u3

Loading

Since this is a project with some history, there are various old artifacts present in each of the repositories. The UIPA.org repositories are:

• CodeWithAloha/uipa
  • main branch - Contains the code for the new and updated UIPA.org theme including a fresh pull from https://github.com/okfde/froide-theme
  • master branch - Last touched by @ryankanno as of 2018, should be feature complete and contains the features added on top of the initial fork
• CodeWithAloha/froide
  • main branch - Contains the code from a fresh pull of https://github.com/okfde/froide
  • master branch - Last touched by @ryankanno as of 2018, the code of the current portal

Note: As part of the revamping UIPA.org project, we are planning on pulling updated versions of both forks. This is so we can absorb new features, bugfixes, and patches naturally.

If you are wondering what this looks like in practice (other than UIPA.org), https://fragdenstaat.de/ and it's related code repository: https://github.com/okfde/fragdenstaat_de/ is a good place to start. This is an up to date platform that uses the same froide-theme/froide relationship, so if you are wondering if something is possible, take a peek and see how that repo does it.

Getting Started

Note: If you are just looking to pick up a task and don't need an explanation, go to the project board, pick a task from the "TODO" column, and assign it to yourself.

Set up your development environment by following the Development section in the CodeWithAloha/froide repository.

The work that needs to be done for UIPA.org is described in the [INITIATIVE] A new and improved UIPA.org issue. Details are linked to issues grouped into bodies of work by labels (Epics, Tasks, etc.) related to the scope of the work. You can click through the various issues to see how everything will eventually fit together. Most of the time, you will be picking up a "Task" which will lead into a larger "Epic". These "Epic"s focus on delivering larger bodies of work, while tasks focus on individual work items. For a brief explanation of epics, tasks, etc. see Atlassian's "Stories, epics, and initiatives".

Related Items

• Froide's Documentation: https://froide.readthedocs.io/en/latest/
• Fragdenstaat_de's Code Repository: https://github.com/okfde/fragdenstaat_de
• Frequently Asked Questions about UIPA.org: https://uipa.org/help/faq/