See original 2023 discussion and proposal here: https://groups.google.com/g/quarkus-dev/c/MijWx9HyaWo

At the moment, we put migration guides (which are user-facing content) in with the content on https://github.com/quarkusio/quarkus/wiki, which is otherwise contributor-facing content. This is a bit untidy in terms of information-organisation.

Proposal

User experience

• People visiting quarkus.io can see migration information
• URLs similar to /guides/ so /migration-guides/3.14/ for instance
• Open question: Do we also want to preserve the older github links for migration information? Not doing so is a bit easier, but breaking published links is undesirable.

Contributor experience

• No worse than the current developer experience; life is hard, let's not make it harder :)
• Ability to publish information independent of release cycles; we need to be able to make content available without having to spin a whole release
• Ability for people to propose changes via PRs (new goal - with the current wiki, elevated privileges are need to make PRs)
• Do we care about markdown vs adoc? At the moment old content is .md, new is .asciidoc, it would be nice to continue supporting both
• Ability to edit in a web editor from the page itself, as well an IDE
• Simple structure, just one .adoc document per version
• No need to add new pages to an index (new goal, at the moment we have a hand edited index page )
• Simple/no templates for new pages
• Optional: no need to make new pages at all, release automation makes skeletons :) (new goal)
• Optional: Automatically include a link to the announcement on the migration page
• Optional: Automatically do other cool cross-linking stuff, leveraging the versions Jekyll collection

Implementation plan

No matter which option we go for:

• Search and replace our websites to replace https://github.com/quarkusio/quarkus/wiki links with the new https://quarkus.io/migration/xx version

"Keep stuff the same" option

• Keep the wiki as the source of truth.
• Use newrelic/wiki-sync-action to sync content into the website at build time.
• Do some simple automation/scaffolding pages to make sure Jekyll can build the the wiki (http://hub.quarkiverse.io is built from wiki pages)

This has the advantage that it doesn't worsen the devex, but the disadvantage that it doesn't open up the wiki to PRs from non-committers. The 'edit this link' page on the main quarkus.io site might be a bit non-ideal, because it would have to take potential editors to the wiki source, but the link would only be a valid link for some people; for others it would always give an error, I think?

"Source in quarkus/quarkusio.github.io + sync" option

• Move the source of truth to be https://github.com/quarkusio/quarkusio.github.io; this repo has the benefit of already hosting web content, and it's not coupled to release cycles like the quarkusio/quarkus repo
• Use newrelic/wiki-sync-action to sync content back to the wiki (this is what https://github.com/quarkiverse/quarkiverse/blob/main/.github/workflows/wikisync.yml does)
• Put in place scaffolding, tables of contents, etc
• Add "edit this page" links to the layout to make editing frictionless

"Burn it all down" option

Same as "source in quarkus/quarkusio.github.io + sync" option, but no sync. This has the disadvantage that we break anyone which has linked to the old pages. This isn't as totally reckless as it sounds, because we're the owner of the pages that link to the wiki, we can just update the backlinks.

If we do this, we should leave the old content up for a couple of weeks after standing up the new content and rewriting links, to allow Google indexes to refresh.

It has a few advantages

• No fussing with sync
• No dependency on an external action, since we're trying to reduce the number of those we have (although newrelic should be a trustworthy source)
• It gives us more flexibility because we can hand-edit the markdown/asciidoc files in ways that would break compatibility with the wiki [although Host migration pages on main website instead of/as well as wiki #2108 demonstrated no incompatible edits will be needed]
• Removing the sync also removes some "where am I supposed to edit these files, there are two copies?" confusion and potential for lost work (doing a two-way sync would also somewhat remove the 'lost work' risk)