Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a DevHub manifest #15254

Merged
merged 14 commits into from May 14, 2019

Conversation

@chrisvanpatten
Copy link
Member

commented Apr 29, 2019

Not to merge until core Trac tickets are solved

Description

Based on today's WordPress #docs meeting (registration required), this PR adds a new manifest intended for consumption by DevHub.

This is intended to accomplish a few things:

  • Leaves the legacy Gutenberg handbook unchanged
  • Does not actually move any documentation files
  • Moves designer/developer handbook content to the top level in DevHub
  • Preserves the current location of the contributor handbook, now living as a section within the developer handbook

The plan from here would be to…

  1. Re-build DevHub from this new manifest
  2. Add wildcard redirects:
    https://wordpress.org/gutenberg/handbook/designers-developers/* → https://developer.wordpress.org/block-editor/*
    https://wordpress.org/gutenberg/handbook/contributors/* → https://developer.wordpress.org/block-editor/contributors/*
    
  3. Disable manifest syncs at the legacy handbook
  4. Move the contents of ./docs/designers-developers to the top level of ./docs and update toc.json accordingly (not doing this here so we can avoid unnecessarily complicating this PR)
  5. Eventually, move manifest-devhub.json back to just manifest.json (once the above steps are working as expected) and consolidate down to a single build targeted at DevHub.

There may be a further desire to move the packages documentation up to the top level, but I'm avoiding that in this initial PR. I think it's worth seeing how this works first before we go further.

cc @Kenshino and @coffee2code

@chrisvanpatten chrisvanpatten requested review from mkaz and nosolosw Apr 29, 2019

@chrisvanpatten

This comment has been minimized.

Copy link
Member Author

commented Apr 29, 2019

We may also want to look at coordinating with the DevHub team to see if we can have some kind of global notice at developer.wordpress.org/block-editor saying something like

This documentation is for the version of the block editor that's bundled with WordPress core. To view the documentation for the latest version of the Gutenberg plugin, visit the Gutenberg GitHub repo.

@chrisvanpatten

This comment has been minimized.

Copy link
Member Author

commented Apr 29, 2019

Another improvement here might be to allow passing --toc and --manifest flags to npm run docs:build so we can more easily have multiple TOCs building to multiple manifests.

That said, having multiple manifests is hopefully just temporary… so maybe not worth the energy :)

@mkaz

mkaz approved these changes Apr 29, 2019

Copy link
Member

left a comment

Looks good! New manifest file is created and looks to be correct.

One minor thing, after running docs:build there appeared to be a white-space difference in the file
packages/core-data/README.md - you will probably need to commit that or you'll get an error

@nosolosw

This comment has been minimized.

Copy link
Member

commented Apr 30, 2019

With the changes here, the top-level TOC will be:

  • Designers & Developers Handbook
  • Key Concepts
  • Developer Documentation *
  • Data Module Reference *
  • Packages *
  • Components *
  • Designer Documentation *
  • Contributors Guide *

* means it contains subsections.

I'd change a few titles (the H1 in the proper README) and would move the reference docs to the bottom so it becomes:

  • Gutenberg Handbook
  • Key Concepts
  • Developer Documentation *
  • Designer Documentation *
  • Contributor Documentation *
  • Data Module Reference *
  • Package Reference *
  • Component Reference *

I'd like to see the other reference docs also moved to the top-level for coherence (Block API Reference, Filter Reference & Tutorials), but I'm also open to use this as a base and review the rest before launch.

@nosolosw

This comment has been minimized.

Copy link
Member

commented Apr 30, 2019

A few other logistic things:

  • If we merge this, the current handbook TOC will also be modified. I guess we need to provide a toc-devhub.json and manifest-devhub.json for testing in DevHub as a first step (assuming the sync DevHub process is the same).

  • Note that the "previous" / "next" links at the bottom of each page are generated from the manifest order (the current handbook has some issues). I've noticed that the manifest-devhub.json doesn't follow the toc.json section order either, so we need to fix that as well.

@chrisvanpatten

This comment has been minimized.

Copy link
Member Author

commented Apr 30, 2019

@nosolosw The handbook and DevHub don't directly reference toc.json; it's just used as a way to map out how the manifest file should be built.

Because we're changing the output of the manifest generation script to create a manifest-devhub.json, the current manifest.json, and thus the legacy handbook, should remain totally unchanged and effectively frozen. We could provide a second TOC but that would assume we want to change the legacy manifest going forward, which I don't believe we actually want.

Once the redirects are in place, we'll be able to disable new builds on the legacy handbook site entirely so the manifest-devhub.json can be moved so manifest.json is again the canonical manifest, but only consumed by DevHub.

I didn't do a super deep comparison on toc.json and manifest-devhub.json but on a quick skim it seems to all be in the correct order. Is that not actually true? Are there any specific things that are out of order?

@chrisvanpatten

This comment has been minimized.

Copy link
Member Author

commented Apr 30, 2019

(Also my hope is that we don't need to merge this in to actually test the DevHub sync; I wrote the PR this way with the assumption that we would only need to merge it in once we were confident this was the correct path forward.)

@nosolosw

This comment has been minimized.

Copy link
Member

commented Apr 30, 2019

The handbook and DevHub don't directly reference toc.json; it's just used as a way to map out how the manifest file should be built.

Ah, great, that simplifies things a bit (I actually thought the sidebar was created from it).

Also my hope is that we don't need to merge this in to actually test the DevHub sync;

Got it. Wasn't clear if we intended to merge this as it is.

I didn't do a super deep comparison on toc.json and manifest-devhub.json but on a quick skim it seems to all be in the correct order. Is that not actually true? Are there any specific things that are out of order?

The problem wasn't the discrepancy between toc and manifest as I hinted earlier, but pages that are generated automatically (data, packages, components): they are appended to the end of the manifest, so previous/next links will be wrong for their top-level sections and the last page of the handbook.

My old-self to the rescue 😅 #14794

@chrisvanpatten

This comment has been minimized.

Copy link
Member Author

commented Apr 30, 2019

@nosolosw Oh shoot - those placeholder replacements aren’t working? That’s definitely a problem… I understand now. Hmm…

@nosolosw

This comment has been minimized.

Copy link
Member

commented May 2, 2019

As per this Slack convo we agreed to apply these changes and promote tutorials as a top-level section.

Pushed changes as individual commits so we can revert as necessary.

@coffee2code

This comment has been minimized.

Copy link

commented May 3, 2019

The Block Editor handbook on DevHub has been updated to reflect these latest changes.

A request and a suggestion:

  • Please update the slug for "Block Editor Handbook" to "handbook" (instead of "designers-developers"). The page with that slug is treated as the front page of the handbook, and was previously used by the "Gutenberg Handbook" page until it was omitted from the DevHub-specific manifest in favor of having "Block Editor Handbook" be the front page. (DevHub currently has two versions of the page since I manually changed the slug for an instance of that page to ensure there was a front page.)
  • A number of pages still use "Gutenberg" in their titles (but not their slugs), so "Gutenberg" could be omitted or changed to "Block Editor".
@nosolosw

This comment has been minimized.

Copy link
Member

commented May 3, 2019

Please update the slug for "Block Editor Handbook" to "handbook" (instead of "designers-developers")

Done at 740bd75 .

A number of pages still use "Gutenberg" in their titles (but not their slugs), so "Gutenberg" could be omitted or changed to "Block Editor".

I can prepare this change independently, as to have a good signal-to-noise balance in this PR.

@nosolosw

This comment has been minimized.

Copy link
Member

commented May 3, 2019

A number of pages still use "Gutenberg" in their titles (but not their slugs), so "Gutenberg" could be omitted or changed to "Block Editor".

Here's a WIP draft PR to address this #15411

AFAIK the current thinking of project members is that Gutenberg should be used for anything project-related and Block Editor is for the first product that came of Gutenberg. It's a transitional period, so things may be a bit confusing and intertwinned.

Show resolved Hide resolved docs/manifest-devhub.json Outdated

@nosolosw nosolosw force-pushed the add/devhub-manifest branch from 4c74813 to 8dc866c May 6, 2019

@nosolosw

This comment has been minimized.

Copy link
Member

commented May 6, 2019

This has been rebased with the latest changes done to the doc tool.

@nosolosw

This comment has been minimized.

Copy link
Member

commented May 10, 2019

Comment spun from this conversation with @coffee2code that I wanted to post here so people following this can participate.

Now that we're closer to the merge status, I'd like to expand on the plan to roll this:

  • Re-build DevHub from this new manifest. It uses this manifest: https://raw.githubusercontent.com/WordPress/gutenberg/ADD/DEVHUB-MANIFEST/docs/manifest-devhub.json. Note that, when relative paths are working, content is to be pulled from this branch, not master (uppercase used for effect). See Scott comment.
  • Publish existing DevHub content.
  • Add wildcard redirects from the old handbook to DevHub.
  • Merge this branch, but DO NOT DELETE IT. It will be still used to generate the DevHub content and bad things ™️ may happen if it no longer exists.
  • Change DevHub to use the Gutenberg master branch instead: https://raw.githubusercontent.com/WordPress/gutenberg/MASTER/docs/manifest-devhub.json
  • Now it's safe to delete this branch.
  • We can now publicly talk and share about the DevHub migration, etc.
@coffee2code

This comment has been minimized.

Copy link

commented May 10, 2019

What's the overall ongoing plan for the handbook at https://wordpress.org/gutenberg/? That handbook uses a custom importer that differs from the one used on DevHub With the relative link changes applied to its manifest (manifest.json), the handbook content won't update unless I port relative path support to it separately.

Based on the latest comment, it looks like the entire handbook will soon redirect to the Block Editor handbook on DevHub, in which case I would be inclined to not make an effort to update the importer for the legacy Gutenberg handbook. (The legacy handbook will remain as you see it today until redirects are activated, at which point the handbook will no longer be accessible.)

@chrisvanpatten

This comment has been minimized.

Copy link
Member Author

commented May 10, 2019

@coffee2code Yes, the plan is to fully deprecate the custom handbook and move into DevHub permanently! I agree; the old handbook should not be updated at this point, except to disable syncing and add redirects.

@nosolosw nosolosw marked this pull request as ready for review May 14, 2019

@nosolosw nosolosw requested a review from talldan as a code owner May 14, 2019

@nosolosw

This comment has been minimized.

Copy link
Member

commented May 14, 2019

Cross-posting here from https://meta.trac.wordpress.org/ticket/4388#comment:22 for latest updates:

  1. we'll get this branch merged so the manifest can come from master. DO NOT DELETE THIS BRANCH YET. (@nosolosw / @chrisvanpatten)
    1.1. DevHub is updated to use the manifest-devhub in master.
    1.2. This branch can be deleted at this point.
  2. handbook is rebuilt, and presumably goes live after a final sanity check, temporarily there are two handbooks
  3. redirects get enabled (@coffee2code)
  4. some indeterminate testing period just to make sure we're all happy, updates are successful, etc.
  5. handbook gets updated to point to wp/{version} branch
@nosolosw
Copy link
Member

left a comment

This is ready! Let ship this to users :)

@nosolosw nosolosw force-pushed the add/devhub-manifest branch from cc3ed5e to cd8d5b3 May 14, 2019

@nosolosw

This comment has been minimized.

Copy link
Member

commented May 14, 2019

Rebased this from master to force Travis to do its checks dance. For some reason, it didn't when I changed this PR from "draft" to "ready for review".

@@ -1,11 +0,0 @@
# Designer & Developer Handbook

The Gutenberg project is transforming the way content is created on WordPress. A block editor was the first product launched creating a new methodology for working with content. This handbook provides documentation for how designers and developers can extend the editor.

This comment has been minimized.

Copy link
@nosolosw

nosolosw May 14, 2019

Member

Note that the current handbook sync has been disabled so this removal won't trigger any update (nor the other minor content updates).

@nosolosw nosolosw merged commit 599e6bd into master May 14, 2019

1 check passed

Travis CI - Pull Request Build Passed
Details
@nosolosw

This comment has been minimized.

Copy link
Member

commented May 14, 2019

DO NOT DELETE THIS BRANCH YET. See.

@youknowriad youknowriad added this to the 5.7 (Gutenberg) milestone May 14, 2019

@chrisvanpatten

This comment has been minimized.

Copy link
Member Author

commented May 14, 2019

Thanks for seeing this through to the finish line @nosolosw — gold stars for you! ⭐️⭐️⭐️⭐️⭐️

@nosolosw

This comment has been minimized.

Copy link
Member

commented May 14, 2019

For reference: @aduth locked this branch from being deleted. We should remove the lock when we're ready to proceed with the next steps. I'll post here.

@coffee2code

This comment has been minimized.

Copy link

commented May 14, 2019

The manifest location for the new Block Editor handbook now uses the file in master and is now available to all visitors. The legacy handbook now redirects to the new handbook.

It should be safe to delete this branch. Then whenever it is so desired, a meta.trac ticket can be opened to re-point the handbook to a manifest file in a wp/{version} branch.

@chrisvanpatten chrisvanpatten deleted the add/devhub-manifest branch May 14, 2019

@gziolo

This comment has been minimized.

Copy link
Member

commented May 23, 2019

See #15785. New Block Editor handbook should be using wp/5.2 branch which contains the snapshot of docs at the time WordPress 5.2 was released. Otherwise, it will cause more confusion.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.