Cross repo publishing

[gustavohenke]

Motivation

I'm maintaining the express-validator org, and I like keeping docs close to the source, so that external contributors and I can submit PRs that contain the complete change.

Have you read the Contributing Guidelines on pull requests?

👍

Test Plan for Cross Repo publishing

1. Have your source docs in one repo (say foo/foo), and point siteConfig.js to another (e.g. set projectName to foo.github.io);
2. Make sure you're on the master branch;
3. Run the publish-gh-pages script;
4. Note how the script doesn't complain about publishing from master and to master. foo.github.io should now have been updated with the latest version of your awesome docs written with Docusaurus;
5. Make a change, repeat, profit!

Test Plan for same repo publishing

1. Point siteConfig.js to the repo the docs are going to be hosted on -- e.g. set organizationName to foo and projectName to bar, while your git remote is foo/bar);
2. Make sure you're on the master branch;
3. Run the publish-gh-pages script;
4. Note your gh-pages getting updated with your changes. Watch how foo.github.io/bar gets updated with the latest version of your awesome docs written with Docusaurus.

Test Plan for same repo publishing from wrong branch

1. Point siteConfig.js to the repo the docs are going to be hosted on -- e.g. set organizationName to foo and projectName to foo.github.io, while your git remote is foo/foo.github.io;
2. Make sure you're on the master branch;
3. Run the publish-gh-pages script;
4. Watch the script deny publishing from master to master.

Related PRs

I have a related issue actually: #717

[docusaurus-bot]

Deploy preview for docusaurus-preview ready!

Built with commit ee2eb8f

https://deploy-preview-764--docusaurus-preview.netlify.com

[endiliey]

@gustavohenke can you provide a test plan for non cross-repo publishing ? Making sure it does not break

[JoelMarcey]

Yep. If we aren't breaking current sites that use the default publishing, I think this is great to be accepted and pushed.

[gustavohenke]

Hi @endiliey and @JoelMarcey,
I added two more test plans to cover touched code.

[endiliey]

LGTM. Awesome work 😄😁

[JoelMarcey]

This looks good to me too. And doesn't seem to break the current publishing, which is great 😄

[JoelMarcey]

Nice test plan, btw, @gustavohenke

[JoelMarcey]

@gustavohenke - Hey! @chenglou pinged me today about the code in this PR, and I think we may have hit a "this was tested great locally, but not on a CI system" situation. @chenglou noted correctly that the default git version on a Linux build in CircleCI is 2.1.4. The command (git remote get-url) listed at this line is not available in that version.

So I think your solution works for a certain version of git or above and no one has had to cross-publish that uses CircleCI.

We may need to do one of two things here:

1. find another way to run that command that is 2.1.4 friendly
2. Force the config to use a version of git that we install with the build

cc: @yangshun @endiliey

[gustavohenke]

Hi @JoelMarcey,
That's a good point I haven't thought of.
I would discard forcing a specific git version, as the CI is the only environment that is controllable by the Docusaurus team. A user's environment isn't.

I think finding another command is the ideal fix. I imagine extra output parsing will be required though.
For example, git remote -v outputs lines like origin git@github.com:user/repo.git (push), and this is a quite old command (but docs to prove it are a good idea).

Let me know what you think, and I can try working on it!

[JoelMarcey]

I would discard forcing a specific git version, as the CI is the only environment that is controllable by the Docusaurus team. A user's environment isn't.

Just to be clear, I meant forcing the CircleCI config -- we would document how to force a specific git version use on CircleCI. Not the user's local config.

I think finding another command is the ideal fix.

The above said, I think having a more global command (for now, until default distros upgrade their git version) may be the way to go too.

Let me know what you think, and I can try working on it!

Thank you! Would love if you could come up with something in a PR. Thank you 👍

[chenglou]

The command is indeed failing, e.g. https://circleci.com/gh/facebook/metro/2898 (search for get-url in the last section), but the usual non-cross-repo logic happens not to be affected. I've verified that changing it to git config --get remote.origin.url works.

I've tried using a more recent git version, but unfortunately CircleCI 2's Debian images don't have a more recent version of git. And installing and compiling git yourself is even more troublesome. Given that it's just a single command that's failing, I'd say changing it and calling a day is fine.

[JoelMarcey]

#956