feat(ci): continuous releases for main and PRs with pkg.pr.new

[Aslemammad]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

Test Plan

Test links

Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/

Related issues/PRs

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	7d361c1
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/66b4e097fe276400082c7c90
😎 Deploy Preview	https://deploy-preview-10369--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	Report
/	🟠 73	🟢 98	🟢 96	🟢 100	Report
/docs/installation	🟠 58	🟢 97	🟢 100	🟢 100	Report
/docs/category/getting-started	🟠 74	🟢 100	🟢 100	🟠 86	Report
/blog	🟠 69	🟢 96	🟢 100	🟠 86	Report
/blog/preparing-your-site-for-docusaurus-v3	🔴 48	🟢 92	🟢 100	🟢 100	Report
/blog/tags/release	🟠 69	🟢 96	🟢 100	🟠 86	Report
/blog/tags	🟠 74	🟢 100	🟢 100	🟠 86	Report

[slorber]

@Josh-Cena it's me that asked @Aslemammad for his help on setting this up 😄

[pkg-pr-new]

commit: c40b352

create-docusaurus

yarn add https://pkg.pr.new/create-docusaurus@10369

@docusaurus/core

yarn add https://pkg.pr.new/@docusaurus/core@10369

@docusaurus/cssnano-preset

yarn add https://pkg.pr.new/@docusaurus/cssnano-preset@10369

@docusaurus/logger

yarn add https://pkg.pr.new/@docusaurus/logger@10369

@docusaurus/mdx-loader

yarn add https://pkg.pr.new/@docusaurus/mdx-loader@10369

@docusaurus/module-type-aliases

yarn add https://pkg.pr.new/@docusaurus/module-type-aliases@10369

@docusaurus/plugin-client-redirects

yarn add https://pkg.pr.new/@docusaurus/plugin-client-redirects@10369

@docusaurus/plugin-content-blog

yarn add https://pkg.pr.new/@docusaurus/plugin-content-blog@10369

@docusaurus/plugin-content-docs

yarn add https://pkg.pr.new/@docusaurus/plugin-content-docs@10369

@docusaurus/plugin-content-pages

yarn add https://pkg.pr.new/@docusaurus/plugin-content-pages@10369

@docusaurus/plugin-debug

yarn add https://pkg.pr.new/@docusaurus/plugin-debug@10369

@docusaurus/plugin-google-analytics

yarn add https://pkg.pr.new/@docusaurus/plugin-google-analytics@10369

@docusaurus/plugin-google-gtag

yarn add https://pkg.pr.new/@docusaurus/plugin-google-gtag@10369

@docusaurus/plugin-google-tag-manager

yarn add https://pkg.pr.new/@docusaurus/plugin-google-tag-manager@10369

@docusaurus/plugin-ideal-image

yarn add https://pkg.pr.new/@docusaurus/plugin-ideal-image@10369

@docusaurus/plugin-pwa

yarn add https://pkg.pr.new/@docusaurus/plugin-pwa@10369

@docusaurus/plugin-sitemap

yarn add https://pkg.pr.new/@docusaurus/plugin-sitemap@10369

@docusaurus/plugin-vercel-analytics

yarn add https://pkg.pr.new/@docusaurus/plugin-vercel-analytics@10369

@docusaurus/preset-classic

yarn add https://pkg.pr.new/@docusaurus/preset-classic@10369

@docusaurus/remark-plugin-npm2yarn

yarn add https://pkg.pr.new/@docusaurus/remark-plugin-npm2yarn@10369

@docusaurus/theme-classic

yarn add https://pkg.pr.new/@docusaurus/theme-classic@10369

@docusaurus/theme-common

yarn add https://pkg.pr.new/@docusaurus/theme-common@10369

@docusaurus/theme-live-codeblock

yarn add https://pkg.pr.new/@docusaurus/theme-live-codeblock@10369

@docusaurus/theme-mermaid

yarn add https://pkg.pr.new/@docusaurus/theme-mermaid@10369

@docusaurus/theme-search-algolia

yarn add https://pkg.pr.new/@docusaurus/theme-search-algolia@10369

@docusaurus/theme-translations

yarn add https://pkg.pr.new/@docusaurus/theme-translations@10369

@docusaurus/tsconfig

yarn add https://pkg.pr.new/@docusaurus/tsconfig@10369

@docusaurus/types

yarn add https://pkg.pr.new/@docusaurus/types@10369

@docusaurus/utils

yarn add https://pkg.pr.new/@docusaurus/utils@10369

@docusaurus/utils-common

yarn add https://pkg.pr.new/@docusaurus/utils-common@10369

@docusaurus/utils-validation

yarn add https://pkg.pr.new/@docusaurus/utils-validation@10369

@docusaurus/eslint-plugin

yarn add https://pkg.pr.new/@docusaurus/eslint-plugin@10369

@docusaurus/lqip-loader

yarn add https://pkg.pr.new/@docusaurus/lqip-loader@10369

stylelint-copyright

yarn add https://pkg.pr.new/stylelint-copyright@10369

Open in Stackblitz • docusaurus • docusaurus-classic-typescript

[Josh-Cena]

Ah I see. I didn't see any motivation or context in this PR.

[Aslemammad]

Sorry for the confusion, Thank you so much y'all for the opportunity.

[slorber]

@Aslemammad how can I test this?

For example, how can I open the template of this PR in StackBlitz?

Note our examples are not necessarily using the latest version of Docusaurus, and we update them manually (or not) after a Docusaurus publish. They do not necessarily reflect the PR's current changes in practice.

To be sure that it works as expected, could you please do a little change to create-docusaurus docs intro.md`? We'll revert it before merging, and it should help us be sure that it works as intended.

What should rather get published is the result of this command:

yarn create-docusaurus test-website-in-workspace classic --typescript

[Aslemammad]

That's for sure, I'll sort it out for you!

[Aslemammad]

I just did a slight change in create-docusaurus to log something.

Once approved, I guess we can see the reflected change by running the binary.

[slorber]

@Aslemammad I don't think it's going to work that way

What we want in the end is to get our 2 init templates able to run on StackBlitz using the PR code

(by the way, is there a way to make this github comment less verbose? it's not super useful to show 20+ lines on how to add every single monorepo package)

But:

• the code in /examples doesn't use the PR code, it uses stable releases from npm and may be stale. These examples are not part of the workspace and this is what our StackBlitz templates (https://docusaurus.new) use. It's more like an "archive" of the examples than fresh examples. It's exactly the same as what I publish as a standalone separate repo here: https://github.com/slorber/docusaurus-starter (as you can see, 2 months old, only re-generated after a release, not fresh)
• Modifying code in create-docusaurus to init a new template won't do anything because you never run it. That's not part of the Docusaurus runtime code, but is only run once at initialization time. What I wanted is that instead you modify some MDX docs of that init template, because this MDX code will end in the initialized template (vs the Node.js code only being used at init time)

I'm not sure how this work, but what I'd try is something like this instead:

    steps:
      # ... previous steps

      - name: Build packages
        run: yarn build:packages

      - name: Init template project
        run: | 
          yarn create-docusaurus fresh-examples/docusaurus-classic classic 
          yarn create-docusaurus fresh-examples/docusaurus-classic-typescript classic --typescript

      - name: Release
        run: npx pkg-pr-new publish './packages/*' --template './fresh-examples/*' --compact

What we want is that the code of the PR that modifies the init template logic (nodejs init code) or init site content (default config file, mdx files, React files, CSS...) have an impact of the StackBlitz template being proposed to try in the current PR. To do so, you have to publish templates that your CI workflow initializes one step before.

[slorber]

By the way, even with the current code (stale templates), the StackBlitz template using the new dependencies don't work due to a yarn install issue:

docusaurus

I think I clicked on something by mistake locally, and it also opened this file showing something that looks like a S3 or Cloudflare error: https://dizwbyrun-y1dl.w-credentialless-staticblitz.com/blitz.41692973.js:40:195142

This XML file does not appear to have any style information associated with it. The document tree is shown below.
<Error>
<Code>AccessDenied</Code>
<Message>Access Denied</Message>
<RequestId>33G2G06KT4P1VT66</RequestId>
<HostId>Moly+n22hzCHulGU5lLfcjHpWq8J3FYMnvWe1NkXUy+jkfz1U14PL3pCz+TZ2DAS0RNDwknXtD4w9vbfESETsQ==</HostId>
</Error>

---

Using npm install instead of yarn install, it seems able to run.

Note there are image-related warnings, they come from using this lib: https://github.com/image-size/image-size (apparently it's supposed to be related to Yarn though, related comment: yarnpkg/berry#3889 (comment))

[WARNING] The image at "/home/projects/dizwby--run/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg" can't be read correctly. Please ensure it's a valid image.
unsupported file type: undefined (file: /home/projects/dizwby--run/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg)

Otherwise, it works fine: the PR new features can be tried on the StackBlitz playground (minus modifications made to create-docusaurus)

[Aslemammad]

Ok, sorry for the confusion, I'll try again and keep you updated!

[Aslemammad]

We do not need installs, since templates would just be uploaded!

I also use npm here so we avoid that error, at least until I fix the issue with yarn in pkg.pr.new!

[slorber]

Hmmm, wondering if generating a package-lock.json wouldn't be useful?

It looks like a tradeoff: resolve package versions ahead of time in CI vs letting the stackblitz user handle it. Maybe the DX will be better/faster for the end user if versions are already pre-resolved?

[Aslemammad]

I also turned off comments since there are many packages, but still, on each commit, we'll have the Continuous Releases check run.

When clicking details, we can see all the packages there without the need for a comment on each pull request.

[slorber]

Thanks

I think the comment is helpful for discovery, but it has to be more concise to be effective and only post the 2 template links. Until you have a better comment, it's preferable to hide it.

[Aslemammad]

I made some changes, but I'm confused a bit on the templates, don't create-docusaurus bring the examples from git?

So even if I change the classic example (as I did now) and do fresh-examples, create-docusaurus won't reflect the changes since things come from git (unless this is merged).

[slorber]

Hmmm, wondering if generating a package-lock.json wouldn't be useful?

It looks like a tradeoff: resolve package versions ahead of time in CI vs letting the stackblitz user handle it. Maybe the DX will be better/faster for the end user if versions are already pre-resolved?

[slorber]

Thanks

I think the comment is helpful for discovery, but it has to be more concise to be effective and only post the 2 template links. Until you have a better comment, it's preferable to hide it.

[slorber]

I made some changes, but I'm confused a bit on the templates, don't create-docusaurus bring the examples from git?

So even if I change the classic example (as I did now) and do fresh-examples, create-docusaurus won't reflect the changes since things come from git (unless this is merged).

No the templates do not come from Git, they come from npm and are packaged inside create-docusaurus. Doing init template changes requires a release.

The examples folder doesn't do anything apart being the entrypoint of StackBlitz. Removing these folders from the main repo won't break our init CLI.

Most of the init template content is here: https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared