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

Initial documentation of entity configuration #55103

Merged
merged 10 commits into from
Oct 9, 2023

Conversation

oandregal
Copy link
Member

@oandregal oandregal commented Oct 5, 2023

Part of #55153

What?

This PR aims to create some initial docs explaining what is an entity and what it needs in terms of configuration.

Why?

It's a crucial part of Gutenberg. Having some introductory high level documentation would help folks to navigate this part of our codebase.

How?

Adds a new section in the README.md of the core-data package.

See

Read the section "What's an entity".

@oandregal
Copy link
Member Author

Pinging some folks that have worked with the core-data package recently. Note this PR doesn't aim to be comprehensive not cover all the properties, but a starting point to be iterated upon.

@@ -40,6 +40,60 @@ function MyAuthorsListBase() {
}
```

## What's an entity?

An entity represents a WordPress REST API endpoint. Each item within the entity is called entity record. Available entities are defined in `rootEntitiesConfig` at ./src/entities.js.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For me REST API is just an implementation detail and my ultimate Goal has always been to decouple from the WordPress REST API using an adapter layer, so in that sense, I'm not a big fan for tieing a definition of an entity to the backend.

I'd define an entity as a type of "model/data" or something like that that the data layer provides to the consumers. Granted that the current definition is tied to the REST API though but this is consequential to me.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pushed an update that tones down the WordPress REST API in favor of a more general approach.

@github-actions
Copy link

github-actions bot commented Oct 5, 2023

Flaky tests detected in ae108b4.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/6433339008
📝 Reported issues:

Copy link
Contributor

@aaronrobertshaw aaronrobertshaw left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's great seeing all the new documentation lately, nice work 👍

I'd define an entity as a type of "model/data" or something like that that the data layer provides to the consumers

FWIW this aligns with what I sort of expected for the entity definition.

Other than that, there were a few minor nits and typos I've left as inline suggestions. Hope that helps 🙂

packages/core-data/README.md Outdated Show resolved Hide resolved
packages/core-data/README.md Outdated Show resolved Hide resolved
packages/core-data/README.md Outdated Show resolved Hide resolved
packages/core-data/README.md Outdated Show resolved Hide resolved
Copy link
Contributor

@youknowriad youknowriad left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

Copy link
Member

@tyxla tyxla left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think these are some very useful docs 👍 Couldn't find anything beyond a minor grammar fix.

Thanks @oandregal 🚀

packages/core-data/README.md Outdated Show resolved Hide resolved
@oandregal oandregal merged commit ccf4286 into trunk Oct 9, 2023
49 checks passed
@oandregal oandregal deleted the add/docs-for-entity-config branch October 9, 2023 07:53
@github-actions github-actions bot added this to the Gutenberg 16.9 milestone Oct 9, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Package] Core data /packages/core-data [Type] Developer Documentation Documentation for developers
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants