DevDocs: add a Gutenberg blocks section #26065

mmtr · 2018-07-14T10:26:08Z

This adds a new feature flag devdocs/gutenberg and creates a new section in /devdocs (if the feature flag is enabled) with dummy content.

The new section will be used in the future for displaying how the Gutenberg blocks can be used in Calypso

Todo

Create devdocs/gutenberg-blocks feature flag
Create view that displays dummy content when accessing /devdocs/gutenberg-blocks
Create new item in the sidebar for accessing the view previously created
~~Add tests~~ They are not needed as there is no behavior to check yet

Testing instructions

With the `devdocs/gutenberg-blocks` feature flag enabled:

Start calypso in a development environment with npm start
Navigate to /devdocs
New sidebar item "Gutenberg Blocks" appears in the "Live Docs" section
Click on the "Gutenberg Blocks" sidebar item
You are redirected to devdocs/gutenberg-blocks and a page with documentation appears

With the `devdocs/gutenberg` feature flag disabled:

Start calypso in a development environment with DISABLE_FEATURES=devdocs/gutenberg-blocks npm start
Navigate to /devdocs
The sidebar item "Gutenberg blocks" does not appear in the "Live Docs" section
Navigate to /devdocs/gutenberg-blocks
"Error invoking /devdocs/content: File does not exist" error is raised (ideally, it should display a 404 error page, but it's not happening as described on DevDocs: "Error invoking /devdocs/content: File does not exist" #26066)

Questions

Is "Gutenberg Blocks" the best name for this new section? Could it be confused with the "Blocks" section?
Which gridicon best represents the new section? I have used gridicon-grid for the moment

Next steps

Prototype what a single Gutenberg block should look like in this section on an experimental branch, copying over files if we really need to.

matticbot · 2018-07-14T10:26:09Z

Test live: https://calypso.live/?branch=add/gutenberg-devdocs-section

mmtr · 2018-07-17T11:01:44Z

@ehg @gwwar @dmsnell I'd appreciate if you can take a look at this whenever you have time :) Or let me know if I should involve someone else

dmsnell · 2018-07-17T11:47:20Z

client/devdocs/design/test/gutenberg.js

+ * Internal dependencies
+ */
+import DocumentHead from 'components/data/document-head';
+import Gutenberg from '../gutenberg';


we'll probably want to differentiate this name here from the editor itself since Gutenberg is the name of the whole project. we could make ../gutenberg-blocks for example which I think would help clear up the confusion

yep, it makes sense. I have just renamed everything to gutenberg-blocks

dmsnell · 2018-07-17T11:49:01Z

client/devdocs/gutenberg/README.md

+Gutenberg Blocks
+====
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent ut arcu et mauris fermentum tempus. In vel lacinia lorem, nec accumsan tortor. Nulla non tellus interdum, vestibulum nisl sed, placerat metus.


obviously this needs to be filled out before merging 😉

my plan was to do that in a separate PR as I thought it was ok to have "lorem ipsum" content if that is behind a feature flag.

anyway, I have just added a proper documentation in order to get rid of the lorem ipsum ;)

I've just realized a problem we have with this: all the README.md files can be accessed even if the feature flag is not active.

I'll check later how can that be improved, so the documentation is not visible if the feature flag is not enabled

it's not about feature-flagging it. it's about committing code that really has no purpose. it's fine to not include it, it's fine to take the time to write it, but it's not really a Good Thing™️ to ship code that's dead at the get-go.

my philosophy is that code that merges is permanent. there is no such thing as temporary code or "I'll get to it soon."

dmsnell · 2018-07-17T11:50:19Z

client/devdocs/design/test/gutenberg.js

+
+		expect( readmeViewer ).toHaveLength( 1 );
+		expect( readmeViewer.props().readmeFilePath ).toBe( '/client/devdocs/gutenberg/README.md' );
+	} );


I'm not convinced on the value of these tests. I suspect that we'd know if the sections are missing because someone would intentionally be deleting them. further, what behaviors are these tests verifying? if it were me I'd probably leave them out.

you're right, this is not checking any behavior.

I just have the habit of writing unit tests for everything but, as pointed here, that's not the goal if we want to strike the right balance between covering expected and unexpected behaviors, speedy execution and code maintenance.

dmsnell · 2018-07-17T11:51:28Z

config/development.json

 		"devdocs/components-usage-stats": false,
+		"devdocs/gutenberg": true,
+		"devdocs/redirect-loggedout-homepage": true,


it's probably worth reordering the existing items in a separate PR so we don't mix the concerns in this one

dmsnell · 2018-07-17T11:53:16Z

Is "Gutenberg Blocks" the best name for this new section? Could it be confused with the "Blocks" section?

sounds good to me. definitely better than leaving off the Gutenberg part

Which gridicon best represents the new section? I have used gridicon-grid for the moment

also seems like a good choice to me. we can easily change later if we want to.

thanks for this work! it's cool to see it coming into Calypso!

you may already know this but you can jump to the devdocs with the global hotkey sequence g d

gwwar · 2018-07-17T18:39:02Z

client/devdocs/design/gutenberg-blocks.jsx

+
+		return (
+			<Main className={ className }>
+				<DocumentHead title="Gutenberg Blocks"/>


Re: naming I think @mtias suggested "Gutenberg Components" for now, though I'm not sure how strongly he feels about that.

Gutenberg have both blocks and components. It's my understanding that we want to show only the blocks according to the project introduction @ehg gave to me, as nothing was said about the components.

Having that in consideration, do we want to name the blocks from Gutenberg as "Gutenberg components" in Calypso? Wouldn't it be confusing?

Blocks in Calypso (more than pure UI components / handle their own data needs) need to be renamed to something else, but I'll leave it up to the framework group to decide what else.

Wouldn't it be confusing?

Until this is resolved, yes, every variation is a bit confusing. 😄I don't have strong feeling here, but wanted to note earlier suggestions.

gwwar · 2018-07-17T19:03:59Z

client/devdocs/design/gutenberg-blocks.jsx

@@ -0,0 +1,26 @@
+/**


If we add /** @format */ above this line, prettier, will handle whitespace formatting for us.

gwwar · 2018-07-17T19:17:50Z

client/gutenberg-blocks/README.md

+The Gutenberg editor uses 
+[blocks](https://github.com/WordPress/gutenberg/blob/master/blocks/README.md) to create all types
+of content. A Gutenberg block is the abstract term used to describe units of markup that, 
+composed together, form the content or layout of a webpage.


This one is a little hard to condense in a single sentence, but maybe we can link out to additional sources like https://wordpress.org/gutenberg/handbook/language/ in future updates

gwwar

Thanks @mmtr! I've tested this with the feature flag enabled and disabled, and it works as expected. Before merging, when you're ready, grab @ehg or someone from @Automattic/lannister to walk you through the deploy process.

feature flag

mmtr · 2018-07-17T21:09:23Z

thanks @dmsnell @gwwar for the reviews! I have applied some amendments based on your suggestions

Build: new feature flag for gutenberg devdocs

5e4d8e4

mmtr added [Status] In Progress [Type] Task DevDocs [Goal] Gutenberg Working towards full integration with Gutenberg labels Jul 14, 2018

mmtr self-assigned this Jul 14, 2018

Devdocs: new section for Gutenberg blocks

578ac06

mmtr requested review from ehg, gwwar and dmsnell July 14, 2018 14:04

Devdocs: tests covering the new section for Gutenberg blocks

2ff06d9

mmtr changed the title ~~Devdocs: add a Gutenberg blocks section~~ DevDocs: add a Gutenberg blocks section Jul 14, 2018

Applying guidelines to tests covering the Gutenberg blocks in DevDocs

9bd2254

mmtr added [Status] Needs Review The PR is ready for review. This also triggers e2e canary tests and wp-desktop tests automatically. and removed [Status] In Progress labels Jul 15, 2018

This was referenced Jul 16, 2018

DevDocs: show Gutenberg blocks #26064

Closed

Proof of concept: render a Gutenberg component in Calypso DevDocs #26088

Closed

dmsnell reviewed Jul 17, 2018

View reviewed changes

mmtr added 2 commits July 17, 2018 15:17

renaming gutenberg to gutenberg-blocks inside the devdocs

6ae407d

Adding documentation about Gutenberg documentation

86ae127

gwwar reviewed Jul 17, 2018

View reviewed changes

gwwar approved these changes Jul 17, 2018

View reviewed changes

mmtr added 4 commits July 17, 2018 22:39

Removing Gutenberg blocks documentation as it cannot be controlled with

0ffc636

feature flag

removing unit tests that were not checking any behavior

4b3ffff

reverting order of the feature flags

29fbff2

adding @Format so prettier handles whitespace formatting

4d858f0

mmtr merged commit f2edec8 into master Jul 18, 2018

matticbot removed the [Status] Needs Review The PR is ready for review. This also triggers e2e canary tests and wp-desktop tests automatically. label Jul 18, 2018

mmtr deleted the add/gutenberg-devdocs-section branch July 18, 2018 16:50

This was referenced Aug 12, 2018

DevDocs: Gutenberg components - Updating examples #26367

Merged

DevDocs: Render a Gutenberg block #26674

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DevDocs: add a Gutenberg blocks section #26065

DevDocs: add a Gutenberg blocks section #26065

mmtr commented Jul 14, 2018 •

edited

Loading

matticbot commented Jul 14, 2018

mmtr commented Jul 17, 2018

dmsnell Jul 17, 2018

mmtr Jul 17, 2018

dmsnell Jul 17, 2018

mmtr Jul 17, 2018

mmtr Jul 17, 2018

dmsnell Jul 17, 2018

dmsnell Jul 17, 2018

mmtr Jul 17, 2018

dmsnell Jul 17, 2018

dmsnell commented Jul 17, 2018

gwwar Jul 17, 2018

mmtr Jul 17, 2018

gwwar Jul 17, 2018 •

edited

Loading

gwwar Jul 17, 2018

gwwar Jul 17, 2018 •

edited

Loading

gwwar left a comment

mmtr commented Jul 17, 2018

DevDocs: add a Gutenberg blocks section #26065

DevDocs: add a Gutenberg blocks section #26065

Conversation

mmtr commented Jul 14, 2018 • edited Loading

Todo

Testing instructions

With the devdocs/gutenberg-blocks feature flag enabled:

With the devdocs/gutenberg feature flag disabled:

Questions

Next steps

matticbot commented Jul 14, 2018

mmtr commented Jul 17, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmsnell commented Jul 17, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gwwar Jul 17, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gwwar Jul 17, 2018 • edited Loading

Choose a reason for hiding this comment

gwwar left a comment

Choose a reason for hiding this comment

mmtr commented Jul 17, 2018

mmtr commented Jul 14, 2018 •

edited

Loading

With the `devdocs/gutenberg-blocks` feature flag enabled:

With the `devdocs/gutenberg` feature flag disabled:

gwwar Jul 17, 2018 •

edited

Loading

gwwar Jul 17, 2018 •

edited

Loading