Create a migration guide to migrate from Akka to Pekko

[kw217]

Create a migration guide explaining to a user of Akka how to migrate their project to Pekko.

We hope to automate as much of this as possible under #22 but first we need to determine the steps and lay them out so early adopters can follow them and gain experience.

This should be documented in docs/src/main/paradox/project/migration-guide-akka-pekko.md, linked from migration-guides.md in the same location, and also linked prominently from the GitHub homepage README.md and the project homepage docs/src/main/paradox/index.md.

Steps include:

• adapting Akka dependencies "com.typesafe.akka" -> "org.apache.pekko"
• adapting JAR names akka-actor_2.13.jar -> pekko-actor_2.13.jar
• adapting imports import akka.actor -> import org.apache.pekko; import pekko.actor - see #58
• adapting class names Akka* to Pekko* - see #67
• adapting packages and corresponding paths akka -> org.apache.pekko, if the codebase inserts code into the Akka namespace
• updating third-party dependencies to versions that depend on Pekko
• adapting configuration to use the pekko key - see #63
• discussion of how to approach Akka remote applications - see #108

[pjfanning]

• don't forget the pekko name in the jars (akka-actor becomes pekko-actor, etc.)
• the guide will go into the docs - there is a placeholder for the migration section in there (or at least once an inflight PR is merged)

[kw217]

Cool, thanks - added that to the description.

Docs location - presumably you're referring to https://github.com/apache/incubator-pekko/blob/main/docs/src/main/paradox/project/migration-guides.md which just got updated? Perfect. Should we just put the migration guide in that doc, rather than a separate doc linked from there?

[kw217]

Example migration (thanks @pjfanning): https://github.com/pjfanning/micrometer-akka/pull/3

[sam-byng]

Just reviewing the status of this issue, I think that the next steps on this card are to complete the following TODOs:

• Flesh out existing parts of migration guide with more details.
• Address the final three bullets still not covered in issue description.
• Add clear linking from GitHub homepage to migration guide.
• Add clear linking from the project website homepage: The migration guide is on the homepage (index.html) but the link is buried down in the Project Information subheading. Since the large proportion of PEKKO users will initially be migrating from AKKA I think that it is important that we place this in a clearer location e.g. the docs 'Getting Started' Guide.
• Add at link to a clean example migration to this migration guide OR copy snippets of it into the migration guide subsections when we flesh it out.

Following the above, test out the migration guide to identify remaining gaps/issues.

[pjfanning]

We have a migration guide. It's not perfect but we can adjust it. Please raise PRs if you want to suggest changes - or comment on this issue.

https://pekko.apache.org/docs/pekko/current//project/migration-guides.html

Removing the milestone as I want to not have open issues in it.