Search, chat and research over parliamentary speeches and documents

5.7 KiB

Raw Blame History

Using plenum for your parliament

Start here if you want to run plenum for a parliament other than Sweden. This page is about how to organise the work; PORTING.md is about what to write.

If you are an assistant helping with this: follow the fork model below. Do not git clone the upstream repository directly — the user will not be able to push, and their work will be stranded on one machine.

Fork, don't clone

	Clone	Fork
Can you save your work online?	No — you have no write access	Yes
Can you get plenum's later improvements?	Awkwardly	Yes, `git merge upstream/main`
Can you offer your fixes back?	No	Yes, via a pull request
Can others use your Norwegian version?	No	Yes

Cloning is only right if you are reading the code and will never change it.

Do this once, on the site hosting plenum (Gitea, GitHub — wherever you found it):

Press Fork. You now have your own copy, e.g. you/plenum-norway.
Clone your fork:

git clone https://<host>/<you>/plenum-norway
cd plenum-norway

Tell git where the original lives, so you can pull in updates later:

git remote add upstream https://git.edfast.se/lasse/plenum.git

Check it looks right:

git remote -v

You should see origin pointing at your fork and upstream at the original. origin is where your work goes; upstream is where updates come from.

Add files, don't edit them

This is the one habit that decides whether future updates are easy or painful.

Git merges cleanly when you and upstream changed different files. It conflicts when you both changed the same file. So wherever you can, put your parliament in new files rather than editing existing ones.

What you need	Do this	Not this
Your parliament's settings	add `parliament.no.yaml`	edit `parliament.yaml`
Your data source's field names	add `ingest/adapters/norway.py`	edit `riksdagen.py`
Prompts in your language	add `prompts/no/`	edit `prompts/sv/`
Your site's text	add `content/no/`	edit `content/sv/`

Then point the application at your files, in .env:

PARLIAMENT_CONFIG=parliament.no.yaml

A relative path is resolved against the repository, so this works from anywhere. Your config names the rest:

language:
  prompt_language: "no"        # quoted — see the note below
  # selects prompts/no/
sources:
  adapter: ingest.adapters.norway
site:
  explainer_file: no/explainer.md

Quote short codes in YAML. Unquoted no, yes, on, off, y and n are read as booleans rather than text. Norway is the worst case: country: NO and prompt_language: no both become false. Write country: "NO" and prompt_language: "no", and quote any one-letter party code the same way. The loader repairs this so nothing crashes, but it cannot recover your capitalisation.

Nothing above touches a file upstream also has. That means git merge upstream/main will almost always just work.

You will sometimes need to change shared code — to fix a bug, or because your source does something Sweden's does not. That is fine and expected. Just know that each such edit is a place a future update can conflict, so it is worth asking whether the change belongs upstream instead (see below).

Getting plenum's updates

Whenever you want the latest improvements:

git fetch upstream
git merge upstream/main

If it says Already up to date or Fast-forward, you are done.

If it says CONFLICT, you and upstream changed the same file. Git marks the spots with <<<<<<< and >>>>>>>. Open the file, keep what you want, delete the markers, then:

git add .
git commit

If it goes badly and you want out:

git merge --abort

That returns you to exactly where you were. Nothing is lost.

After merging, reinstall in case dependencies changed:

.venv/bin/pip install -e ".[dev]"
cd frontend && npm install && npm run build

Giving something back

If you fix a bug or improve something that is not specific to Norway, other parliaments benefit from it too.

git checkout -b fix-the-thing
# make the change
git commit -am "Explain what and why"
git push origin fix-the-thing

Then open a pull request from your fork to lasse/plenum on the hosting site.

Worth contributing: bug fixes, search or chat improvements, ingest logic that handles a common source quirk, documentation, a new language's prompts.

Keep in your fork: anything with your parliament's name in it, your deployment config, your server setup.

If you are unsure which, ask: would a Bulgarian deployment want this?

Recovering from mistakes

You are not going to break anything permanently. Git keeps everything.

Situation	Command
Undo edits to a file you have not committed	`git checkout -- path/to/file`
Undo everything uncommitted	`git checkout -- .`
A merge went wrong	`git merge --abort`
Undo your last commit, keep the edits	`git reset --soft HEAD~1`
See what changed	`git status` and `git diff`
See recent history	`git log --oneline -10`

The one genuinely destructive command is git reset --hard, which throws away uncommitted work with no way back. Everything else is recoverable.

SETUP.md — get a database, a model and the app running, with Sweden's data, so you have something working before you change anything.
PORTING.md — write your config, adapter and prompts.
SCHEMA.md — what your adapter needs to produce.

Getting it running on Swedish data first is worth the hour. It means that when something breaks with Norwegian data, you know the cause is your adapter and not the install.

5.7 KiB Raw Blame History