nixos/forgejo: document migration version restrictions (#406169)

Which might lead to an even more involved migration.

:::

::: {.warning}

The last supported version of Forgejo which supports migration from Gitea is

*10.0.x*. You should *NOT* try to migrate from Gitea to Forgejo `11.x` or

higher without first migrating to `10.0.x`.

See [upstream migration guide](https://forgejo.org/docs/latest/admin/gitea-migration/)

The last supported version of *Gitea* for this migration process is *1.22*. Do

*NOT* try to directly migrate from Gitea *1.23* or higher, as it will likely

result in data loss.

See [upstream news article](https://forgejo.org/2024-12-gitea-compatibility/)

:::

In order to migrate, the version of Forgejo needs to be pinned to `10.0.x`

*before* using the latest version. This means that nixpkgs commit

[`3bb45b041e7147e2fd2daf689e26a1f970a55d65`](https://github.com/NixOS/nixpkgs/commit/3bb45b041e7147e2fd2daf689e26a1f970a55d65)

or earlier should be used.

To do this, temporarily add the following to your `configuration.nix`:

```nix

{ pkgs, ... }:

let

  nixpkgs-forgejo-10 = import (pkgs.fetchFromGitHub {

    owner = "NixOS";

    repo = "nixpkgs";

    rev = "3bb45b041e7147e2fd2daf689e26a1f970a55d65";

    hash = "sha256-8JL5NI9eUcGzzbR/ARkrG81WLwndoxqI650mA/4rUGI=";

  }) {};

in

{

  services.forgejo.package = nixpkgs-forgejo-10.forgejo;

}

```

### Full-Migration {#module-forgejo-migration-gitea-default}

This will migrate the state directory (data), rename and chown the database and

systemctl restart forgejo

```

Afterwards, the Forgejo version can be set back to a newer desired version.

### Alternatively, keeping the gitea user {#module-forgejo-migration-gitea-impersonate}

Alternatively, instead of renaming the database, copying the state folder and