[epic] migrate Soroban Docs into Stellar Docs

[ElliotFriend]

Since the Stellar Mainnet validators have affirmatively voted to upgrade the network to protocol version 20, now we begin the task of combining this documentation repository and the stellar/stellar-docs repository.

This issue will serve to track all the work needed to move content, as well as redirect where necessary.

The general process will be:

1. We'll create a PR in the stellar-docs repo that serves to put the content of a section of documentation from this repo into the new one.
2. A corresponding PR will be made in the soroban-docs repo that will redirect URLs and remove content (where applicable) from this repo.

Once that PR is ready, rinse and repeat. Several of these changes may involve merging main back into the feature branch along the way.

Done

• Migrate the content for Tools section ([Soroban Merge] Tools section stellar/stellar-docs#304)
• Redirect tools/SDKs URLs ([Stellar Merge] Tools Section #739)
• Put up a Docusaurus announcement bar on stellar-docs that says "pardon our dust" or something. ([Soroban Merge] add announcement bar about the migration stellar/stellar-docs#311)
• Put up a Docusaurus announcement bar on soroban-docs that says "we're moving" or something. ([Stellar Merge] Announcement Bar #742)
• Look into versioning multiple software products (this stackoverflow question might help)
• Research the ideal way to move content while preserving (at least some?) git history
• Migrate content for Soroban RPC section ([Soroban Merge] Create a "Platforms" section stellar/stellar-docs#325)
• Redirect Soroban RPC section URLs ([Stellar Merge] Redirects for Soroban RPC pages #757)
• Migrate content for Learn section ([Soroban Merge] Create a "Learn" section of the docs stellar/stellar-docs#354)
• Redirect Learn section URLs ([Stellar Merge] Redirects and migration for what will become the "Learn" section of dev docs #769)
• Migrate content for Reference section ([Soroban Merge] Create a "Reference" section stellar/stellar-docs#364)
• Redirect Reference section URLs ([Stellar Merge] Add redirects and external URLs for a new "Reference" section #772)
• Migrate content for Smart Contracts section ([Soroban Merge] Create a "Smart Contracts" section stellar/stellar-docs#388)
• Redirect Smart Contracts section URLs ([Stellar Merge] Redirects and changes for the new "Smart Contracts" section #778)
• Migrate content from Dapps challenge ([Soroban Merge] Dapps Challenge stellar/stellar-docs#497)
• Redirect Dapps challenge URLs ([Stellar Merge] Dapps Challenge #781)

In-Progress

• Consider docusaurus updates (Upgrade to Docusaurus v3 stellar/stellar-docs#355)
  • upgrade to latest v2 version (Docusaurus v3 upgrade preparation stellar/stellar-docs#405)
  • upgrade to latest v3 version (do this after the dapps challenge)

[thisBrian]

Hi Elliot great work,

I was looking into one of the Todo points you mentioned

• Research the ideal way to move content while preserving (at least some?) git history

Have you explored using the --allow-unrelated-histories flag? Might be a way to achieve that.

[ElliotFriend]

Have you explored using the --allow-unrelated-histories flag? Might be a way to achieve that.

Hi, Brian! Thanks for the suggestion!

I've come across the unrelated histories flag as a probable solution, but haven't yet taken the time to figure out precisely how to use it. Do you have any experience with it? If so, I'd love some pointers.

For a quasi-hypothetical example: Suppose I wanted to take all of the files that are located in the /api directory in the soroban-docs repo and bring it into the stellar-docs repo, maybe into a new directory like /api/soroban-rpc. Is it possible to pick and choose just a single directory to do that with? Or, would I need to do it with the whole working tree? Does it matter that the source/destination directories have different paths from the repo root?

Not that you have to have the answers lol, just tossing out some of the thoughts that have been rattling around in my head.

Thanks again!

[thisBrian]

Hi Elliot, those are very good questions.

Our team was doing it when migrating to a monorepo but we had additional tooling in place.
I will look into cloning and creating a test repo from the soroban docs -> stellar-docs directory case and see if I can replicate that specific scenario.
Things are a bit busy at the moment but I will make some time around the next couple of days or so to test it out 👍

[overcat]

Hi, if I want to submit a PR to add Java SDK example here, is it better to wait until the migration is completed and then submit it to stellar-docs, or is it better to submit it to this repo now?

[ElliotFriend]

Things are a bit busy at the moment but I will make some time around the next couple of days or so to test it out 👍

@thisBrian I actually did some toying around with it yesterday, and I think i did reasonably well with the soroban-rpc stuff. It's on this PR: stellar/stellar-docs#325 I found a couple people posting guides for similar stuff online, but I don't exactly recall which ones I used. I'll try to write down a "post-mortem" for how I did it (for future reference) today or tomorrow.

... is it better to wait until the migration is completed and then submit it to stellar-docs, or is it better to submit it to this repo now?

@overcat Is your Java example, already written and just "looking for a home" or will it need some time and iteration? My gut says go ahead and submit it here. We could target the soroban-internals section for the week of March 11 perhaps? Would that be enough time?

[overcat]

@overcat Is your Java example, already written and just "looking for a home" or will it need some time and iteration? My gut says go ahead and submit it here. We could target the soroban-internals section for the week of March 11 perhaps? Would that be enough time?

We have already submitted and merged it.

[gabrieladeniji]

Hi, was not able to access this page again.

After the merging, would the page be moved to another path, or would still be accessible here?

https://developers.stellar.org/docs/anchoring-assets/anchor-platform/sep24/integration?q=anchoring+assets+anchor+platform+sep24+integration

[briwylde08]

Hi there! That page should be available here: https://developers.stellar.org/network/anchor-platform/admin-guide/sep24/integration