search

Qiskit / ecosystem

The Ecosystem consists of projects, tools, utilities, libraries and tutorials from a broad community of developers and researchers. The goal of the Ecosystem is to recognize, support and accelerate development of quantum technologies using Qiskit.
https://www.ibm.com/quantum/ecosystem
Apache License 2.0
102 stars 53 forks source link

Migrate projects away from qiskit.org domain #578

Closed Eric-Arellano closed 5 months ago

Eric-Arellano commented 1 year ago

This only impacts sites hosted on qiskit.org. We need to:

  1. Deploy to GitHub Pages using the new action. See https://github.com/qiskit-community/qiskit-qec/pull/399 for an example
  2. Remove the deploy to github.com, such as tools/deploy_documentation.sh and tools/rclone.conf.enc.
  3. Set up in the IBM Cloudflare config repository to redirect from qiskit.org to the new GH page. Make sure you update the existing redirects from qiskit.org/documentation/my_project also.
  4. Update the project's About section to point to the new site.

Simple sites to migrate:

More complex because translations. TBD if we want to continue with this program.

More complex because Previous Releases feature:

For translations and previous releases, the challenge might be if we need to deploy the site as a single atomic unit. Right now, we deploy each subsite distinctly, like /ecosystem/nature for the current English docs, but /ecosystem/nature/locale/es_UN for the Spanish docs; those deploys happen at different times. I'm concerned if GitHub pages makes us copy over the entire /nature folder and all subfolders like translations in a single pass. But my fear might be unfounded! See https://github.com/Qiskit/rustworkx/issues/1035 for some experimentation.

arnaucasau commented 11 months ago

Instructions to set up GitHub Pages:

Here, you can find a quick guide to set up your repository to use GitHub Pages.

[!WARNING] Before starting with the process, you need to add a new branch called gh-pages. This branch needs to have that name to ensure the workflows can deploy successfully. You can create it manually, or, in case you have the new workflows, it will be created automatically after the first deployment (Better option).

Once you have the branch gh-pages created, you can follow the following steps:

  1. Navigate to your site's repository
  2. Click Settings
  3. Go to Pages
  4. Select Deploy from a branch, under the Source section on Build and deployment
  5. Select the gh-pages branch and the / (root) folder in the Branch section on Build and deployment

GitHubPages-example

After following these steps, you will be able to deploy your website. The default URL where you can find your site is https://\<userid>.github.io/\<repository-name>

For further information, you can see the GitHub Pages Quickstart.

Why do we use a publishing source (gh-pages branch)?

As you have probably seen, GitHub launched a new method (currently in Beta) to deploy to GitHub Pages using GitHub actions, but we are still using a publishing source (gh-pages branch) for the deployment of the documentation. The reason behind this is the flexibility we have using a different branch to make incremental deployments.

Some projects have historical API versions and need to publish to the page without modifying what is live or without having to rebuild and re-deploy everything. The deployment with GitHub actions doesn't allow us to do that because the deployment is treated as an atomic operation that has to be performed at once.

Therefore, the more convenient approach is to continue deploying the documentation with a publishing source. Even though not all the projects use historical API versions, it's useful to have all the workflows ready for projects to deploy historical versions in the future and to maintain consistency between the ecosystem.

You can find more information about this in the following issues that explore the possibility of having, in the future, the option to download the live site from GitHub Pages to avoid the problem of rebuilding everything:

  1. https://github.com/actions/deploy-pages/issues/73
  2. https://github.com/actions/upload-pages-artifact/issues/57
mtreinish commented 10 months ago

Rustworkx has been completed with: https://github.com/Qiskit/rustworkx/pull/1037 and the new home of the documentation is: https://www.rustworkx.org/

IvanIsCoding commented 10 months ago

@Eric-Arellano can you make https://qiskit.org/ecosystem/rustworkx/ redirect to https://www.rustworkx.org/? It will help users with the old link. Thanks!

Eric-Arellano commented 10 months ago

@mtreinish is way ahead of you :) He has a PR up for review to set up the redirect. Thanks @IvanIsCoding for your great work on this PR!

woodsp-ibm commented 10 months ago

Qiskit Algorithms docs are now on github pages https://qiskit-community.github.io/qiskit-algorithms/ thanks to @arnaucasau for the updated workflow that does this.

woodsp-ibm commented 9 months ago

At what point are the redirects from ecosystem going to be setup. Algorithms docs have been deployed to github pages for a while but are not yet redirecting. Asking since I am about to redeploy Finance, as the first of the apps, once the backported PR to change things passes and is merged, which will all need redirects once they are live on github pages. I can note here, like I did for the algos, when its done, but like algos they will need the redirects added.

woodsp-ibm commented 9 months ago

Thanks to @arnaucasau Qiskit Finance docs are now published on qithub pages https://qiskit-community.github.io/qiskit-finance/ - English only at present. Do we want to populate the translations that exist before going further - i.e. changing About link and adding ecosystem redirect. Presently selecting anything other than English results in a 404 error since locales is empty for now.

Qiskit Optimization is done https://qiskit-community.github.io/qiskit-optimization/ Qiskit Machine Learning now too https://qiskit-community.github.io/qiskit-machine-learning/

~(Just leaves Nature - I'll update here when its done - needs some other CI failure taken care of first)~

Qiskit Nature is now done too https://qiskit-community.github.io/qiskit-nature/

So that's all the app repos done now; Finance, Machine Learning, Optimization and Nature. ~Except dealing with languages other than English, i.e. translations - see next comment.~

Update: 26 Jan 2024. @arnaucasau did PRs to gh_pages adding the translations. They are merged and now live - so I altered the docs links in the repos' About to the github pages since the docs are complete - well aside from changing some cross sites links either via intersphinx, if they are auto generated, or manually fixing them up. I see in translations interphinx links, like to qiskit, are still to qiskit.org. Changing the interphinx in conf.py will only fixup the English version right when docs are redeployed from the repo. If the translations are not going to be updated maybe its ok that they continue to go via redirects.

Eric-Arellano commented 9 months ago

At what point are the redirects from ecosystem going to be setup.

Arnau will be adding them this week, although it sometimes takes 1-2 days for the cloud team to review and merge.

Do we want to populate the translations that exist before going further - i.e. changing About link and adding ecosystem redirect.

Yeah, I think that's a good idea. The translations team finalized a few days ago the translations, so Arnau is working on setting up the translations in GitHub Pages. Those will be a one-time deploy since we are no longer actively doing the translations program for Qiskit Ecosystem.

coruscating commented 9 months ago

Experiments is done: https://qiskit-extensions.github.io/qiskit-experiments/

woodsp-ibm commented 9 months ago

I noticed this above in the task list against Aer

There are existing redirect rules from qiskit.org/documentation to the aer site; these need to be updated.

This is also true (redirects from qiskit.org/documentation) for the apps as they were moved out of the main qiskit docs to ecosystem where they were before. Eg https://qiskit.org/documentation/nature which redirects to nature in ecosystem etc.

Eric-Arellano commented 9 months ago

This is also true (redirects from qiskit.org/documentation) for the apps as they were moved out of the main qiskit docs to ecosystem where they were before. Eg https://qiskit.org/documentation/nature which redirects to nature in ecosystem etc.

Thanks, Steve. We got those covered, too. Arnau's PR is up for review 🙌

woodsp-ibm commented 9 months ago

Can/should any branch protection rules be setup for gh_pages. I see for a PR @arnaucasau did a to Finance for adding translations its already mergable with no approval - evidently I don't want to do things that get in the way of the auto publication when the docs are rebuilt, but unlike main and stable presently it has no rules at all.

woodsp-ibm commented 9 months ago

For the apps, with the translations being added, I made the About link the github pages one. See the update in this comment https://github.com/Qiskit/ecosystem/issues/578#issuecomment-1908614267 for more info - though that kept things about the apps in one place (in that one comment mainly) I wondered whether it might not get easily noticed hence this additional new comment pointing that out.

arnaucasau commented 9 months ago

Hi @woodsp-ibm , I think you should be able to set up a branch protection rule, and it's a good idea. The only thing to have in mind is to allow the workflow to force push to the branch as you said. I found we can allow specified actors to bypass a rule, so maybe this can help.

Eric-Arellano commented 5 months ago

All sites are now deployed, and we have a PR to set up redirects for the final 3 projects. Excellent job, @arnaucasau, leading this change!