govoplan-core/docs/GITEA_ISSUES.md

Gitea Issues And Wiki Workflow

Gitea issues are the canonical backlog for GovOPlaN work: bugs, feature requests, tasks, tech debt, TODO migrations, open decisions, and blocked work should live there. Gitea wiki pages are the canonical project reference for durable project context mirrored from repository docs and product-directory notes.

The same pattern is reusable outside GovOPlaN for any project where Codex works in a local checkout, VSCodium or another editor is used for human inspection, and Gitea is the issue tracker. In that setup, Gitea is the durable coordination layer; Codex and the editor are clients of that state.

Initial Setup

The repository contains Gitea issue templates in .gitea/ISSUE_TEMPLATE, a pull request template in .gitea/PULL_REQUEST_TEMPLATE.md, and the label taxonomy in docs/gitea-labels.json.

The scripts infer this repository from origin (git@git.add-ideas.de:add-ideas/govoplan-core.git). Override inference when needed:

export GITEA_URL=https://git.add-ideas.de
export GITEA_OWNER=add-ideas
export GITEA_REPO=govoplan-core
export GITEA_TOKEN=...

The API scripts also read GITEA_* values from the target repository's .env file. That file is gitignored in this repo, so it is suitable for local tokens:

GITEA_TOKEN=...
# Optional if origin inference is not enough:
GITEA_URL=https://git.add-ideas.de
GITEA_OWNER=add-ideas
GITEA_REPO=govoplan-core

For a shared credentials file outside the target repository, pass --env-file:

./scripts/gitea-sync-labels.py --env-file /path/to/private/gitea.env --apply

Create a Gitea token with issue read/write access and label-management permission for the repository. On scoped-token instances, this usually means issue read/write and, if label writes are rejected, repository write permission too.

Preview and apply labels:

cd /mnt/DATA/git/govoplan-core
./scripts/gitea-sync-labels.py
./scripts/gitea-sync-labels.py --apply

After the .gitea files are pushed to the default branch, Gitea will show the issue template chooser. Blank issues are disabled by .gitea/ISSUE_TEMPLATE/config.yaml.

Multiple Repositories And Workspaces

The helper scripts are path-based and can run from this core checkout against any repository with a Gitea remote:

cd /mnt/DATA/git/govoplan-core
./scripts/gitea-sync-labels.py --root /mnt/DATA/git/govoplan-mail --apply
./scripts/gitea-todo-import.py --root /mnt/DATA/git/govoplan-mail
./scripts/gitea-codex-note.py --root /mnt/DATA/git/govoplan-mail --issue 123 --status progress

Each target repository is inferred from its own origin remote. Use GITEA_URL, GITEA_OWNER, or GITEA_REPO only when a workspace has unusual remotes or the Gitea web URL cannot be inferred from SSH.

When one core checkout drives another workspace, prefer --env-file for shared credentials instead of putting GITEA_REPO in the core .env; a repo-specific GITEA_REPO can accidentally override target inference.

For non-GovOPlaN projects, provide a project-specific label file and module/project label:

./scripts/gitea-sync-labels.py \
  --root /path/to/project \
  --labels-file /path/to/project/docs/gitea-labels.json \
  --apply

./scripts/gitea-todo-import.py \
  --root /path/to/project \
  --module-label project/example \
  --extra-label area/backend

If another project does not use area/* labels, disable area inference:

./scripts/gitea-todo-import.py \
  --root /path/to/project \
  --module-label project/example \
  --no-area-labels

Install or refresh the shared issue templates in sibling or external repositories:

./scripts/gitea-install-workflow.py /mnt/DATA/git/govoplan-mail
./scripts/gitea-install-workflow.py /mnt/DATA/git/govoplan-mail --apply

The installer rewrites the default template label from module/core to the module label inferred from the target repository name. Known mappings cover the packaged GovOPlaN repositories, and any other govoplan-<name> checkout maps to module/<name>. For another workspace or repository name, pass an explicit label:

./scripts/gitea-install-workflow.py /path/to/repo --module-label module/example --apply

Use --include-labels-file if a repository should carry its own copy of docs/gitea-labels.json; otherwise keep the shared taxonomy in core and run the sync script from core.

For a fully portable workflow kit, copy these files into the other project:

• scripts/gitea_common.py
• scripts/gitea-sync-labels.py
• scripts/gitea-todo-import.py
• scripts/gitea-codex-note.py
• scripts/gitea-install-workflow.py
• .gitea/ISSUE_TEMPLATE/*
• .gitea/PULL_REQUEST_TEMPLATE.md
• a project-specific docs/gitea-labels.json

Keep credentials out of the repository. Put GITEA_TOKEN in the shell environment, a gitignored .env, a local direnv file, or the user-level Codex/VSCodium environment setup.

Label Taxonomy

Use one type/* label:

• type/bug
• type/feature
• type/task
• type/debt
• type/docs

Use one status/* label while the issue is open:

• status/triage: needs ownership, priority, or acceptance criteria.
• status/ready: ready to implement.
• status/in-progress: actively being worked.
• status/blocked: blocked on an external dependency, credential, or decision.
• status/needs-info: blocked on clarification.

Use one priority/* label when prioritization matters: priority/p0, priority/p1, priority/p2, or priority/p3.

Use module/* and area/* labels to route work. Module labels are not exclusive because cross-module work can exist. Core issues should still preserve ownership boundaries: module-specific implementation belongs in the owning module repository.

Use codex/ready when the issue has enough context for Codex to work from, and codex/needs-human when a human decision is required first.

Moving TODOs Into Gitea

Preview inline markers:

cd /mnt/DATA/git/govoplan-core
./scripts/gitea-todo-import.py

Create missing issues after labels are synced:

./scripts/gitea-todo-import.py --apply

The importer scans TODO, FIXME, XXX, and HACK markers, skips markers that already reference an issue, applies source/todo-scan, and writes a hidden fingerprint into each generated issue body so reruns do not duplicate already imported items.

When touching code with an imported marker, either remove the marker as part of the fix or replace it with a short reference:

# TODO(gitea#123): keep only if the local pointer is still useful

Do not add new untracked TODO comments. Create the Gitea issue first, then reference it inline only when the local pointer materially helps future readers.

For a broader project import across all local repositories hosted on git.add-ideas.de, use the generic backlog importer:

./scripts/gitea-import-all-backlogs.py --env-file /home/zemion/.config/gitea/gitea.env
./scripts/gitea-import-all-backlogs.py --env-file /home/zemion/.config/gitea/gitea.env --apply

It scans repository and product-directory files with backlog-like names, creates the shared generic labels where needed, imports missing open work, and deduplicates reruns by hidden fingerprint and normalized title.

Mirroring Project Docs Into Gitea Wikis

Preview wiki pages for all local repositories hosted on git.add-ideas.de, cross-referenced with product directories under /mnt/DATA/Nextcloud/ADD ideas UG/Products:

cd /mnt/DATA/git/govoplan-core
./scripts/gitea-sync-wiki.py --env-file /home/zemion/.config/gitea/gitea.env

Apply the wiki mirror:

./scripts/gitea-sync-wiki.py --env-file /home/zemion/.config/gitea/gitea.env --apply

The default apply path uses the Gitea wiki git repository, not one REST API request per page. It keeps a local checkout cache below /tmp/codex-gitea-wiki-sync, commits changed pages once per repository, and pushes that commit. This is much faster and avoids REST wiki-page timeouts. Use --transport api only when the wiki git remote is unavailable.

Limit a sync to one repository or one generated page while working:

./scripts/gitea-sync-wiki.py --repo govoplan-core --apply
./scripts/gitea-sync-wiki.py --repo govoplan-core --page Repo-docs-MODULE-ARCHITECTURE --apply

Page-limited syncs do not rewrite Codex-Project-Index; run a full repository sync when the set of mirrored pages changes.

The wiki sync mirrors durable text documents only: root README-style files, docs/codex project docs, and selected product notes such as roadmap, plan, concept, pitch, and whitepaper files. It skips generated folders, dependency/build output, .gitea templates, and filenames that look credential-related.

Each managed wiki page contains a codex-wiki-sync marker and a source path. Reruns update only managed pages unless --overwrite-unmanaged is passed. Each repository also gets a managed Codex-Project-Index page linking the mirrored pages.

Use the wiki for durable context:

• project overviews and architecture
• workflows, operating notes, and setup references
• product concepts, plans, pitches, and whitepapers
• historical context that helps interpret issues

Keep active state in issues:

• open tasks, TODOs, feature requests, and bugs
• priority, blocking status, and acceptance criteria
• Codex progress updates and implementation notes

Codex State Updates

Codex should read the relevant issue before making changes when issue access is available. During or after work, Codex should add issue comments with the state that would otherwise drift into local notes:

• scope understood
• files changed
• tests or manual checks run
• blockers or decisions needed
• follow-up issues created

Preview and post a standardized note:

./scripts/gitea-codex-note.py \
  --issue 123 \
  --status progress \
  --summary "Implemented capability metadata fallback." \
  --changed src/govoplan_core/modules/registry.py \
  --test "./.venv/bin/python -m unittest tests.test_module_system"

./scripts/gitea-codex-note.py \
  --issue 123 \
  --status progress \
  --summary "Implemented capability metadata fallback." \
  --changed src/govoplan_core/modules/registry.py \
  --test "./.venv/bin/python -m unittest tests.test_module_system" \
  --apply

Use --close --apply only when the acceptance criteria are satisfied and verification is recorded.

Ownership Rules

Create the issue in the repository that owns the change:

• govoplan-core: platform runner, DB/session primitives, auth, tenancy, RBAC, governance, module discovery, migrations, shared WebUI shell, and generic WebUI components.
• govoplan-access: access, identity, authentication, sessions, API keys, RBAC, groups, users, and access administration.
• govoplan-mail: mail-specific backend, frontend, message workflows, and mail integrations.
• govoplan-files: files-specific backend, frontend, storage, and file workflows.
• govoplan-campaign: campaign-specific backend, frontend, policy, and template behavior.

For cross-cutting work, create a tracking issue in govoplan-core and link module issues from it. Do not use the core issue as a dumping ground for module-specific implementation details.

Cleaning Up Mirrored Sources

After backlog files have been imported into issues and durable context has been mirrored to wiki, old duplicate sources can be removed from git only when they are tracked files and the Gitea issue/wiki state has been verified. Prefer deleting backlog, TODO, roadmap, and one-off planning files that have become duplicate state.

Do not delete standard repository entry points such as README, LICENSE, SECURITY, or package metadata just because they are mirrored to the wiki. They remain useful for repository browsing, package registries, and developer onboarding.

Do not delete untracked files or files outside git history as part of automated cleanup unless there is a separate backup or explicit human confirmation for that specific path.

Docs Versus Issues

Keep durable facts in docs:

• architecture and extension points
• command references
• module boundaries
• operational conventions

Keep changing state in Gitea:

• TODOs and follow-ups
• bugs and feature requests
• blocked status
• acceptance criteria
• implementation notes from active work

If a decision becomes durable architecture, write the durable result into docs and link back to the issue for history.