Add comprehensive guide for migrating issue dependencies from Pagure.io

- Add new documentation page for assign_and_depend.py script usage
- Cover installation, configuration, and usage with practical examples
- Include virtual environment setup and security best practices
- Update navigation to include the new migration guide
- Address critical post-migration step for restoring issue assignments and dependencies

modules/ROOT/nav.adoc

@@ -2,6 +2,7 @@
  ** xref:create_org_profile_page.adoc[How to create an Organization Front Page]
  ** xref:requesting_new_org_or_team.adoc[Requesting a New Organization and/or Team]
  ** xref:using_http_auth.adoc[How to Clone a Repo with HTTPS]
+ ** xref:migrating_issue_dependencies.adoc[Migrating Issue Dependencies and Assignments from Pagure.io]
 * Admin Documentation
  ** xref:creating_a_new_org.adoc[Creating a new Organization]
  ** xref:creating_a_new_team.adoc[Creating a new Team]

modules/ROOT/pages/migrating_issue_dependencies.adoc

@@ -0,0 +1,143 @@
+include::partial$attributes.adoc[]
+
+= Migrating Issue Dependencies and Assignments from Pagure.io to Fedora Forge
+
+== Purpose
+
+This document provides a comprehensive guide for using the `assign_and_depend.py` script to restore issue dependencies and assignments after migrating a project from Pagure.io to Fedora Forge. The built-in migrator does not handle this critical metadata, making this script an essential post-migration step.
+
+== Scope
+
+This guide applies to Fedora Project contributors who have migrated their projects from Pagure.io to Fedora Forge and need to restore:
+
+* Issue assignments (who is assigned to work on each issue)
+* Issue dependencies (which issues depend on other issues)
+
+== Prerequisites
+
+* *Migrated Project:* Your project must already be migrated from Pagure.io to Fedora Forge
+* *Python Environment:* Python 3.6 or later with pip installed
+* *Required Dependencies:* The following Python packages must be installed:
+** `requests` - For making HTTP requests to Pagure API
+** `backoff` - For retry logic with exponential backoff
+** `click` - For command-line interface
+** `pyforgejo` - For interacting with Forgejo API
+* *API Access:* 
+** Forgejo API key with write permissions to the target repository
+** Access to Pagure.io API (publicly accessible)
+
+== Installation
+
+=== Installing Required Dependencies
+
+It's recommended to use a Python virtual environment to avoid conflicts with system packages. Create and activate a virtual environment, then install the required packages:
+
+[source,bash]
+----
+python -m venv migration-env
+source migration-env/bin/activate
+pip install requests backoff click pyforgejo
+----
+
+When you're done with the migration, you can deactivate the virtual environment:
+
+[source,bash]
+----
+deactivate
+----
+
+=== Obtaining the Script
+
+The `assign_and_depend.py` script is available in the official Fedora Forge deployment repository. You can download it directly from:
+
+link:https://codeberg.org/fedora/forgejo-deployment/src/branch/main/scripts/assign_and_depend.py[assign_and_depend.py]
+
+To download the script:
+
+[source,bash]
+----
+curl -O https://codeberg.org/fedora/forgejo-deployment/raw/branch/main/scripts/assign_and_depend.py
+----
+
+== Obtaining Required Information
+
+=== Forgejo API Key
+
+To obtain a Forgejo API key:
+
+. Log in to your Fedora Forge account
+. Navigate to your user settings (click your avatar in the top-right corner)
+. Go to "Applications" → "Generate New Token"
+. Give your token a descriptive name (e.g., "Migration Script")
+. Select the appropriate scopes:
+** `repo` - Required for reading and writing repository data
+** `user` - Required for user-related operations
+. Click "Generate Token"
+. Copy the generated token and store it securely
+
+[WARNING]
+====
+Keep your API key secure and never commit it to version control. Consider using environment variables or a secure configuration file.
+====
+
+=== Project Information
+
+You'll need to identify:
+
+* *Pagure Project:* The original project name on Pagure.io (e.g., `fedora-infra/ansible`)
+* *Forgejo Project:* The migrated project name on Fedora Forge (e.g., `infrastructure/fedora-infrastructure`)
+
+== Usage
+
+=== Basic Command Structure
+
+The script uses the following command structure:
+
+[source,bash]
+----
+python assign_and_depend.py \
+  --pagure-project "PAGURE_PROJECT_NAME" \
+  --forgejo-api-key "YOUR_API_KEY" \
+  --forgejo-project "FORGEJO_PROJECT_NAME"
+----
+
+=== Command-Line Options
+
+* `--pagure-base-url`: Base URL for Pagure API (default: `https://pagure.io/api/0`)
+* `--pagure-project`: Pagure project name, including namespace if applicable (required)
+* `--forgejo-base-url`: Base URL for Forgejo API (default: `https://forge.fedoraproject.org/api/v1`)
+* `--forgejo-api-key`: Your Forgejo API key (required)
+* `--forgejo-project`: Forgejo project name in format `organization/project` (required)
+
+=== Example Usage
+
+==== Example 1: Basic Migration
+
+[source,bash]
+----
+python assign_and_depend.py \
+  --pagure-project "fedora-infra/ansible" \
+  --forgejo-api-key "gitea_abc123def456..." \
+  --forgejo-project "infrastructure/fedora-infrastructure"
+----
+
+==== Example 2: Using Environment Variables
+
+For security, you can use environment variables:
+
+[source,bash]
+----
+export FORGEJO_API_KEY="gitea_abc123def456..."
+python assign_and_depend.py \
+  --pagure-project "fedora-infra/ansible" \
+  --forgejo-api-key "$FORGEJO_API_KEY" \
+  --forgejo-project "infrastructure/fedora-infrastructure"
+----
+
+== Conclusion
+
+The `assign_and_depend.py` script is a critical tool for completing the migration from Pagure.io to Fedora Forge. While the built-in migrator handles the basic project structure, this script ensures that important metadata like issue assignments and dependencies are preserved.
+
+Follow this guide carefully, test with small datasets first, and always verify your results. With proper preparation and execution, you can successfully restore all your project's issue relationships on Fedora Forge.
+
+Last updated in {year}.