Document publishing flow for atoms #115
Conversation
README.md
Outdated
| definition. This enables the user to save their work at any point. At this point in the flow the atom is not in CAPI. | ||
| 3. Every time an atom is saved to the DraftsDynamoDataStore atom workshop also checks if all the required fields have been | ||
| supplied. If they have the atom is put in PreviewDynamoDataStore and put into preview CAPI. This step is not visible to the user. | ||
| 4. The atom is now in a publishable state the 'publish' button in the UI becomes active. |
There was a problem hiding this comment.
Slight grammar tweak here: "The atom is now in a publishable state. The 'Publish' button in the UI becomes active."
README.md
Outdated
| 3. Every time an atom is saved to the DraftsDynamoDataStore atom workshop also checks if all the required fields have been | ||
| supplied. If they have the atom is put in PreviewDynamoDataStore and put into preview CAPI. This step is not visible to the user. | ||
| 4. The atom is now in a publishable state the 'publish' button in the UI becomes active. | ||
| 5. On selecting publish the atom is put in the PublishedDynamoDataStore and in live CAPI. Once published the atom can be embedded in |
There was a problem hiding this comment.
On selecting 'Publish' ...
README.md
Outdated
| is updated to reflect the changes made. It is possible to publish the atom. | ||
| #### Scenario 4: An atom is live and the edit process makes the atom invalid | ||
| If the changes make the atom invalid e.g. deleting the content of a required field it will not be possible to republish the atom. | ||
| The atom will remain in live CAPI as it was before the edit took place. The automatic save process will will remove the atom from |
There was a problem hiding this comment.
Maybe bold around "before the edit took place" to really emphasise it?
README.md
Outdated
| 5. On selecting publish the atom is put in the PublishedDynamoDataStore and in live CAPI. Once published the atom can be embedded in | ||
| composer content. | ||
|
|
||
| ### Editing Rules |
There was a problem hiding this comment.
With these 3 steps, there's no explanation as to what "drafts", "preview" and "live" are. They could be defined in the steps above.
There was a problem hiding this comment.
I agree, I think having what the differences between draft, preview and live is useful. In reading the below steps I had to remind myself why we have preview and it's usecase.
There was a problem hiding this comment.
Looks good, a couple points:
- I'd document this in a new markdown file and link to it from the Readme. I think it could get lost in all the set up notes but it's important for anyone who's contributing to the project.
- As this is an public repo we should use Content API once then use CAPI after. Perhaps also a link to CAPI docs to.
README.md
Outdated
| 5. On selecting publish the atom is put in the PublishedDynamoDataStore and in live CAPI. Once published the atom can be embedded in | ||
| composer content. | ||
|
|
||
| ### Editing Rules |
There was a problem hiding this comment.
I agree, I think having what the differences between draft, preview and live is useful. In reading the below steps I had to remind myself why we have preview and it's usecase.
PublishingProcess.md
Outdated
| is updated to reflect the changes made. It is possible to publish the atom. | ||
| ### Scenario 4: An atom is live and the edit process makes the atom invalid | ||
| If the changes make the atom invalid e.g. deleting the content of a required field it will not be possible to republish the atom. | ||
| The atom will remain in live CAPI as it was ***before the edit took place.*** The automatic save process will will remove the atom from |
PublishingProcess.md
Outdated
| ### Scenario 1: An atom is in drafts only | ||
| Changes are automatically saved to DraftsDynamoDataStore. If the changes have made the atom valid according to the thrift definition, | ||
| i.e. all required fields are provided, the atom is also saved to PreviewDynamoDataStore and preview CAPI is updated | ||
| to include the atom. The user does not have to do anything to transition the atom from Drafts to Preview. It is possible to publish the atom. |
There was a problem hiding this comment.
I think it might be confusing to end a section of draft atoms with this sentence, maybe just add once the atom is in preview or something similar.
PublishingProcess.md
Outdated
| This project uses the [atom maker](https://github.com/guardian/atom-maker/) for publishing, reindexing and saving atoms in a | ||
| DynamoDB. As a result there is the concept of Drafts (atoms where all fields are optional) and Atoms where whether or not a | ||
| field is optional depends on the [thrift definition](https://github.com/guardian/content-atom). | ||
|
|
There was a problem hiding this comment.
Maybe mention that including drafts is optional.
Documenting the publishing flow for atoms. Work has not yet been done on atom workshop to follow these rules but I wanted to get some feedback on the process.