[ALT-817-core] Add github documentation for the core package #603
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
ryunsong-contentful
force-pushed
the
ALT-817-core
branch
2 times, most recently
from
7d65104
to
636d97d
Compare
packages/core/README.md
Outdated
| ## Documentation | ||
| ### Concepts | ||
| - **Deep binding**: Relates to the ability to resolve n references. Such an entry containing a reference to another entry which may also contain a reference to another entry and so on. | ||
| - **Component Definition** Baseline definition to outline what is needed to define all component types whether it is a structure, built-in, or custom component. |
There was a problem hiding this comment.
Small style suggestion to align with the format of other bullet items
Suggested change
| - **Component Definition** Baseline definition to outline what is needed to define all component types whether it is a structure, built-in, or custom component. | |
| - **Component definition**: Baseline definition to outline what is needed to define all component types whether it is a structure, built-in, or custom component. |
packages/core/README.md
Outdated
| This package provides core internal functionality for the [Experiences SDK](https://www.contentful.com/developers/docs/experiences/set-up-experiences-sdk/). | ||
| ### Purpose | ||
| - To contain shared code and utilities across the Experience-builder packages such as constants, types, transformers, and hooks. | ||
| - This means additions to core should be framework agnostic. For example, code that is only compatible with React do not belong in the core package. |
There was a problem hiding this comment.
Suggested change
| - This means additions to core should be framework agnostic. For example, code that is only compatible with React do not belong in the core package. | |
| - This means additions to core should be framework agnostic. For example, code that is only compatible with React does not belong in the core package. |
packages/core/README.md
Outdated
Comment on lines
28
to
17
| [Data Structures](https://www.contentful.com/developers/docs/experiences/data-structures/) | ||
| [Design Tokens](https://www.contentful.com/developers/docs/experiences/design-tokens/) |
There was a problem hiding this comment.
Should this be a bulleted list so the links are on separate lines? Currently it renders like this:
There was a problem hiding this comment.
My plugin lied to me
There was a problem hiding this comment.
Might be time to delete that extension! Vscode has native support for previewing markdown now and it renders very similar to github
If you want make the two links appear on different line without using bullets, you can add a \ to force a line break after the first link:
### Relevant Contentful Documentation Links
[Data Structures](https://www.contentful.com/developers/docs/experiences/data-structures/)\
[Design Tokens](https://www.contentful.com/developers/docs/experiences/design-tokens/)
packages/core/README.md
Outdated
Comment on lines
14
to
25
| ``` | ||
| "typesVersions": { | ||
| "*": { | ||
| "types": [ | ||
| "./dist/types.d.ts" | ||
| ], | ||
| "constants": [ | ||
| "./dist/constants.d.ts" | ||
| ] | ||
| } | ||
| }, | ||
| ``` |
There was a problem hiding this comment.
IMO - this chunk of code is not important enough to put in the readme. I think the description you added with the package names will suffice
ryunsong-contentful
force-pushed
the
ALT-817-core
branch
from
636d97d
to
4dc2a5e
Compare
ryunsong-contentful
force-pushed
the
ALT-817-core
branch
from
4dc2a5e
to
73419b5
Compare
aromanko
reviewed
May 21, 2024
| @@ -1,7 +1,17 @@ | |||
| # @contentful/experiences-core | |||
|
|
|||
| This package provides core internal functionality for the [Experiences SDK](https://www.contentful.com/developers/docs/experiences/set-up-experiences-sdk/). | |||
| ### Purpose | |||
| - To contain shared code and utilities across the Experience-builder packages such as constants, types, transformers, and hooks. | |||
There was a problem hiding this comment.
Is it currently "Experience-builder packages" or "Experiences packages"?
There was a problem hiding this comment.
Experiences packages is more correct
|
|
||
| ## Documentation | ||
| ### Concepts | ||
| - **Deep binding**: Relates to the ability to resolve n references. Such an entry containing a reference to another entry which may also contain a reference to another entry and so on. |
There was a problem hiding this comment.
n references is using more of a mathematical language, where n represents a variable that conveys any number of references. I'll just update this to say ability to resolve multiple references
| ### Concepts | ||
| - **Deep binding**: Relates to the ability to resolve n references. Such an entry containing a reference to another entry which may also contain a reference to another entry and so on. | ||
| - **Component definition** Baseline definition to outline what is needed to define all component types whether it is a structure, built-in, or custom component. | ||
| - **Entity**: Contentful entries that get converted into an experience object that can be used within the experience builder packages. |
There was a problem hiding this comment.
again: experience builder or experiences packages?
| - **Deep binding**: Relates to the ability to resolve n references. Such an entry containing a reference to another entry which may also contain a reference to another entry and so on. | ||
| - **Component definition** Baseline definition to outline what is needed to define all component types whether it is a structure, built-in, or custom component. | ||
| - **Entity**: Contentful entries that get converted into an experience object that can be used within the experience builder packages. | ||
| - **Fetchers**: The helper classes and functions in the Entity directory get consumed by the fetchers which get bundled up into either `fetchBySlug` or `fetchById`. The listed fetchers are the two main functions that are exposed to the end user in the sdk to fetch a user's experience which is stored in Contentful as an entry. |
| - **Component definition** Baseline definition to outline what is needed to define all component types whether it is a structure, built-in, or custom component. | ||
| - **Entity**: Contentful entries that get converted into an experience object that can be used within the experience builder packages. | ||
| - **Fetchers**: The helper classes and functions in the Entity directory get consumed by the fetchers which get bundled up into either `fetchBySlug` or `fetchById`. The listed fetchers are the two main functions that are exposed to the end user in the sdk to fetch a user's experience which is stored in Contentful as an entry. | ||
| - **Registries**: An in memory storage technique that the user can decide to provide for themselves or other personas in the editor canvas. Design Tokens is an useful example where a user can provide their own thematic values with regards to text size, component sizes, spacing, colors, and borders in a json format that is resolved by the registry and provided as options in the ui editor sidebar. |
There was a problem hiding this comment.
in-memory...Deisgn tokens...JSON...UI editor
|
|
||
| Please refer to our [Documentation](https://www.contentful.com/developers/docs/experiences/) to learn more about it. | ||
| ### Relevant Contentful Documentation Links |
There was a problem hiding this comment.
Relevant Contentful documentation links
|
|
||
| Please refer to our [Documentation](https://www.contentful.com/developers/docs/experiences/) to learn more about it. | ||
| ### Relevant Contentful Documentation Links | ||
| - [Data Structures](https://www.contentful.com/developers/docs/experiences/data-structures/) |
| Please refer to our [Documentation](https://www.contentful.com/developers/docs/experiences/) to learn more about it. | ||
| ### Relevant Contentful Documentation Links | ||
| - [Data Structures](https://www.contentful.com/developers/docs/experiences/data-structures/) | ||
| - [Design Tokens](https://www.contentful.com/developers/docs/experiences/design-tokens/) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Purpose
Adds github documentation for the core package
NOTE: One section that was excluded was the
Deployment Pattern with user_interfacesection because the ui is a private repo whereas experience-builder is a public repo. Therefore the deployment/build explanation probably belongs in a private doc.Approach
Speak to SMEs, take notes, and the perform the README write up