Bootstrap the architecture documentation #22751
Conversation
youknowriad
added
the
[Type] Developer Documentation
|
|
||
| ## Going further | ||
|
|
||
| - [Journey towards a performant editor](https://riad.blog/2020/02/14/a-journey-towards-a-performant-web-editor/) |
There was a problem hiding this comment.
I'm not sure if it's ok to have a link to my blog like that but I felt that that post doesn't make sense as is in the docs but that it's still good to learn more about the perf work.
There was a problem hiding this comment.
My two cents is that it's okay to have for now as a V1 :)
There was a problem hiding this comment.
An external link policy was discussed in a recent docs meeting and the basic summary: ideally we enhance official docs, but if valuable external resource exists it is ok to link.
There was a problem hiding this comment.
I'm fine copy/pasting like I did for the "modularity" doc, this blog post link here just don't fit in the docs IMO
docs/architecture/index.md
Outdated
| - [Block Editor Performance](docs/architecture/performance.md). | ||
| - What are the decision decisions behind the Data Module? | ||
| - Why puppeteer is the tool of choice for End 2 End tests? | ||
| - What's the difference between the different editor packages? and what's the purpose of each package? |
There was a problem hiding this comment.
I'm hoping that by starting this, other folks can chime-in and document other decisions made on the repo.
|
Size Change: +17.4 kB (1%) Total Size: 1.13 MB
ℹ️ View Unchanged
|
|
Do you think this would fit in the "Project Overview" section of the docs? There are so related docs there, I can see a sub-section for Architecture fitting nicely. See the table of contents as published at: https://developer.wordpress.org/block-editor/ the file structure in the docs doesn't necessarily match the published table of contents due to how docs have grown and been organized over time. |
|
@mkaz While there's definitely overlap when it comes to the decisions behind the block concept (and maybe better moved to the architecture docs), I do think the "architecture" docs are different and more technical and concrete like the examples on the index file while the "project overview" as being more "marketting/high-level". |
|
@youknowriad I would rather see the Project Overview turn into the architecture documents, the "marketing and higher-level" docs were needed when the project was younger and needed to justify itself. I think the more technical docs are a better fit there now as the project matures. |
|
Makes sense @mkaz do you think you can help move this forward? I think you have a better context than me to make better-informed decisions about the potential reorganisation. |
| - [Modularity and WordPress Packages](docs/architecture/modularity.md). | ||
| - [Block Editor Performance](docs/architecture/performance.md). | ||
| - What are the decision decisions behind the Data Module? | ||
| - [Why is Puppeteer the tool of choice for end-to-end tests?](/docs/architecture/automated-testing.md) |
There was a problem hiding this comment.
In dd33523, I added a document addressing this question.
There was a problem hiding this comment.
Thanks these are great.
| - [Block Editor Performance](docs/architecture/performance.md). | ||
| - What are the decision decisions behind the Data Module? | ||
| - [Why is Puppeteer the tool of choice for end-to-end tests?](/docs/architecture/automated-testing.md) | ||
| - [What's the difference between the different editor packages? What's the purpose of each package?](/docs/architecture/modularity.md#whats-the-difference-between-the-different-editor-packages-whats-the-purpose-of-each-package) |
There was a problem hiding this comment.
In 25d906e, I added a section to the existing "Modularity" document to outline the purpose of the editor packages.
|
|
||
| These include: | ||
|
|
||
| - **Interoperability with existing testing framework**. Puppeteer is "just" a tool for controlling a Chrome browser, and makes no assumptions about how it's integrated into a testing environment. While this requires some additional effort in ensuring the test environment is available, it also allows for cohesion in how it integrates with an existing setup. Gutenberg is able to consistently use Jest for both unit testing and end-to-end testing. This is contrasted with other solutions like Cypress, which provide their own testing framework and assertion library as part of an all-in-one solution. |
There was a problem hiding this comment.
I think now it supports Firefox by default too.
There was a problem hiding this comment.
Yes. I wasn't sure how cohesive I could mention that here, without it overcomplicating the messaging. And the support is still pretty early. Puppeteer still markets itself as "Headless Chrome Node.js API", and "a Node library which provides a high-level API to control Chrome or Chromium over the DevTools Protocol. Puppeteer runs headless by default, but can be configured to run full (non-headless) Chrome or Chromium." The text largely reflects that.
There was a problem hiding this comment.
I guess I kinda alluded to Firefox ("not just Chrome") later in the document, "largely":
The fact that Puppeteer largely targets the Chrome browser is non-ideal in how it does not provide full browser coverage.
| - **An expressive but predictable API**. Puppeteer strikes a nice balance between low-level access to browser behavior, while retaining an expressive API for issuing and awaiting responses to those commands using modern JavaScript [`async` and `await` syntax](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await). This is contrasted with other solutions, which either don't support or leverage native language async functionality, don't expose direct access to the browser, or leverage custom domain-specific language syntaxes for expressing browser commands and assertions. The fact that Puppeteer largely targets the Chrome browser is non-ideal in how it does not provide full browser coverage. On the other hand, the limited set of browser targets offers more consistent results and stronger guarantees about how code is evaluated in the browser environment. | ||
| - **Surfacing bugs, not obscuring them**. Many alternative solutions offer options to automatically await settled network requests or asynchronous appearance of elements on the page. While this can serve as a convenience in accounting for unpredictable delays, it can also unknowingly cause oversight of legitimate user-facing issues. For example, if an element will only appear on the page after some network request or computation has completed, it may be easy to overlook that these delays can cause unpredictable and frustrating behavior for users ([example](https://github.com/WordPress/gutenberg/pull/11287)). Given that developers often test on high-end hardware and stable network connections, consideration of resiliency on low-end hardware or spotty network availability is not always on the forefront of one's considerations. Puppeteer forces us to acknowledge these delays with explicit `waitFor*` expressions, putting us in much greater alignment with the real-world experience of an end-user. | ||
| - **Debugging**. It's important that in that case that a test fails, there should be straight-forward means to diagnose and resolve the issue. While its offerings are rather simplistic relative to the competition, Puppeteer does expose options to run tests as "headful" (with the browser visible) and with delayed actions. Combined with the fact that it interoperates well with native language / runtime features (e.g. debugger statements or breakpoints), this provides developers with sufficient debugging access. | ||
|
|
There was a problem hiding this comment.
Maybe we could mention that Cypress didn't support keyboard interactions properly, not sure if it's still the case though.
There was a problem hiding this comment.
Nevermind just saw the link to the PR which describes these.
There was a problem hiding this comment.
I'd initially taken an angle of describing the history of end-to-end testing in Gutenberg, and more specifically "Why we don't use Cypress" and describing all its faults, including what you describe as some of the browser emulation issues. I eventually reoriented it to a more positive "What requirements we want from our testing tool" direction.
But yes, the linked pull request can help illustrate some of those more specific examples.
|
I think there are already some very good docs here. @mkaz do you think we should move forward as is and restructure separately or should we do it all at once? |
| These include: | ||
|
|
||
| - **Interoperability with existing testing framework**. Puppeteer is "just" a tool for controlling a Chrome browser, and makes no assumptions about how it's integrated into a testing environment. While this requires some additional effort in ensuring the test environment is available, it also allows for cohesion in how it integrates with an existing setup. Gutenberg is able to consistently use Jest for both unit testing and end-to-end testing. This is contrasted with other solutions like Cypress, which provide their own testing framework and assertion library as part of an all-in-one solution. | ||
| - **An expressive but predictable API**. Puppeteer strikes a nice balance between low-level access to browser behavior, while retaining an expressive API for issuing and awaiting responses to those commands using modern JavaScript [`async` and `await` syntax](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await). This is contrasted with other solutions, which either don't support or leverage native language async functionality, don't expose direct access to the browser, or leverage custom domain-specific language syntaxes for expressing browser commands and assertions. The fact that Puppeteer largely targets the Chrome browser is non-ideal in how it does not provide full browser coverage. On the other hand, the limited set of browser targets offers more consistent results and stronger guarantees about how code is evaluated in the browser environment. |
There was a problem hiding this comment.
Also note that Cypress doesn't natively support the fetch API.
|
Seems like we're ready to ship the initial version for this. Any approval? |
|
This is a good initiative. I'd also like to see us using more inline comments contextual to the code or entry points like #20257 |
There was a problem hiding this comment.
👍 This is a great start, I committed a change that moved it up under Project Overview. I think this is a good section for it and it doesn't grow the sidebar, which is a problem we ran into before.
We can probably remove and clean up old stuff under Project Overview but can be addressed in other PRs.
|
I think I neglected to include the new automated testing document in the table of contents / manifest. |
I feel like sometimes we repeat ourselves explaining some of the technical decisions on the project and this might come down to the lack of "architecture documentation" on the block editor repository.
This documentation can be very valuable for folks new to the repository or that want to learn more and contribute more heavily.
This PR is an attempt to start this documentation. For now I added two documents: