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.

How can I help?

Our project board, UIPA.org Development Board, is how we keep track of the work to be done. 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.

If you are setting up your development environment for the first time, please follow the Setting Up Your Development Environment section below.

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.

Caution

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

Setting Up Your Development Environment

Set up your development environment by following the Getting Started section in the CodeWithAloha/uipa repository.

• We are using Django 4.2 so refer to the Django 4.2 Documentation with suggestions for First steps and links to tutorials. The mainstream support for Django 4.2 ended 12/04/2023 but extended support will end after April 2026.

Work on an issue

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".

To start working on a task, go to the project board, pick one from the "TODO" column, and assign it to yourself. If you're going to work on a task that someone else is already assigned to, check with them about working together, and then either one can assign you to that task. There can be multiple people assigned to a task.

To load data into UIPA.org, follow the Seeding the Database runbook.

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/