Add introduction to CDEvents #34

m-linner-ericsson · 2022-03-11T15:55:40Z

I wanted to create a introduction to CDEvents explaining to a larger audience why we created the project and what it provides.

I have taken inspiration from previous PR material and other markdown documents, but also added a few idea myself.

If you feel the text should live in another document please feel free suggest that.

Signed-off-by: Mattias Linnér mattias.linner@ericsson.com

e-backmark-ericsson

I embrace this initiative, and I believe it captures the background well enough as it is now written.

Maybe this page deserves a ToC now as its content has grown quite a lot?

README.md

afrittoli · 2022-03-18T14:38:37Z

I wanted to create a introduction to CDEvents explaining to a larger audience why we created the project and what it provides.

I have taken inspiration from previous PR material and other markdown documents, but also added a few idea myself.

If you feel the text should live in another document please feel free suggest that.

Signed-off-by: Mattias Linnér mattias.linner@ericsson.com

Thanks @m-linner-ericsson !
I think it's nice to provide a little bit more context in the main README. But I would prefer to keep the READM not too busy, and maybe move some of this content to the CDEvents primer?

afrittoli

Thanks Matthias, it looks good!
I left a few comments

afrittoli · 2022-03-18T14:41:41Z

README.md

+We thus build on top of the work from other players as the following stack
+pictures exemplifies.


I would skip this sentence, I think the picture below ties well with the one on L30.

Updated in 1ad4def

afrittoli · 2022-03-18T14:43:51Z

images/stack.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2022-03-09T14:09:43.285Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/16.5.1 Chrome/96.0.4664.110 Electron/16.0.7 Safari/537.36" etag="WJztc4Q_z2C4iVk_88a6" version="16.5.1" type="device"><diagram id="rZAp1BOKmzg2OGIajMNH" name="Page-1">5ZbdbqMwEIWfhsuVAEM2uUwJTaRVpLap1N1LC0/AG2MjY0rSp69dTAhxK3Wl7Y9aiQv7zNhmvmNsPJSU+6XEVbEWBJgX+mTvoYUXhkEUhp55fHLolJkfd0IuKbFJg7ChD2BF36oNJVCPEpUQTNFqLGaCc8jUSMNSinacthVsvGqFc3CETYaZq95RoopOncb+oK+A5kW/cuDbSIn7ZCvUBSaiPZFQ6qFECqG6VrlPgBl4PZdu3OUL0eOLSeDqNQOK9E+6WM5n02v/7m9THbLfy/aHneUes8YWvLq9vfLCRIu/8HaHu+Z8fX1lq1CHHo0UDSdgZg88dNEWVMGmwpmJtnozaK1QJbNhuw5IBfsXCwiOWPR+AlGCkgedYgegnqTdSnFk++1gTNDnFCemTKyG7V7Ij1MPuHTDEvsHeqFDL2GiIem9rqj+dLyi6UfzQi6vxWeFFX40rNiBdSMaRXnusNJVqzGQWkmxg0QwIbXCBdeZF1vK2JmEGc257jLYmhkMQarPvrmVS0qIWeRZ/oND/v+xIJqcfd9x7FgwecYB9FYOTBwH1lDX5sIwF4nUJ/x3sSKauVYcb7p38eKn48UGSsw1I/fs+KomoLczQXeHP5Gn2Mn/HEofAQ==</diagram></mxfile>


Thanks for including the source!

README.md

afrittoli · 2022-03-18T14:48:56Z

spec.md

 ## Abstract

-CDEvents is a common specification for Continuous Delivery events.
+CDEvents is a common specification for Continuous Delivery events. For more


I would not add this to the abstract.
We could link the README and primer docs in the overview below instead?

Tried to make something in 1ad4def. Do you have any other good ideas?

afrittoli · 2022-03-18T14:57:44Z

README.md

+* Create a coupled architecture - using point-to-point communication creates a
+  tightly intertwined architecture difficult to expand and monitor.
+
+#### Why not webhooks?


I'm not sure about this. I see webhooks as a way to deliver events, and I didn't know we recommended explicitly against them. CloudEvents include a spec for webhooks https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/http-webhook.md and they could be an interesting option in cases where authorization is required.

Felt this was a bit on the edge so I removed it in 1ad4def

Co-authored-by: Emil Bäckmark <emil.backmark@ericsson.com>

afrittoli · 2022-03-25T16:03:07Z

spec.md

 - The [*vocabulary*](vocabulary), which identifies *event types*, structures as
  *subjects* and *predicates*

+For an introduction see [README.md](README.md) and for  more background


NIT: extra space "for more"

Fixed in 5bea30c

afrittoli

Thank for all the updates.
Just a nit but looks good to me

spec.md

afrittoli · 2022-03-30T12:55:35Z

@e-backmark-ericsson ok to merge?

e-backmark-ericsson · 2022-03-31T07:31:03Z

primer.md

 <!-- toc -->
 - [History](#history)
 - [Relations to CloudEvents](#relations-to-cloudevents)
+- [Design reflections](#design-reflections)


This ToC entry should be swapped with the previous line to match the actual content

You can run ./tools/update-toc.sh to keep the ToCs updated - I should probably setup a CI job for that :)

Should be fixed in 610d408

e-backmark-ericsson

Just a very small change needed

Adding docs updates from cdevents/spec#34 Signed-off-by: Andrea Frittoli <andrea.frittoli@gmail.com>

m-linner-ericsson added 3 commits March 11, 2022 16:43

Add introduction to CDEvents

518f020

Move description to README.md

6ba052f

Fix readme link

b6edb6b

m-linner-ericsson requested review from afrittoli, e-backmark-ericsson and erkist March 11, 2022 16:00

e-backmark-ericsson requested changes Mar 15, 2022

View reviewed changes

afrittoli reviewed Mar 18, 2022

View reviewed changes

m-linner-ericsson and others added 2 commits March 25, 2022 14:07

Apply suggestions from code review

7b2d8bd

Co-authored-by: Emil Bäckmark <emil.backmark@ericsson.com>

Updates from review

1ad4def

afrittoli reviewed Mar 25, 2022

View reviewed changes

afrittoli approved these changes Mar 25, 2022

View reviewed changes

m-linner-ericsson commented Mar 30, 2022

View reviewed changes

spec.md Outdated Show resolved Hide resolved

Update spec.md

5bea30c

e-backmark-ericsson reviewed Mar 31, 2022

View reviewed changes

e-backmark-ericsson requested changes Mar 31, 2022

View reviewed changes

Update primer.md

610d408

e-backmark-ericsson approved these changes Apr 1, 2022

View reviewed changes

m-linner-ericsson merged commit 6559231 into cdevents:main Apr 1, 2022

m-linner-ericsson deleted the add_intro branch April 1, 2022 11:21

afrittoli added a commit to cdevents/cdevents.dev that referenced this pull request Apr 5, 2022

Docs updates

0eeb6c5

Adding docs updates from cdevents/spec#34 Signed-off-by: Andrea Frittoli <andrea.frittoli@gmail.com>

afrittoli mentioned this pull request Apr 5, 2022

Docs updates cdevents/cdevents.dev#5

Merged

afrittoli added a commit to cdevents/cdevents.dev that referenced this pull request Apr 5, 2022

Docs updates

5ef6512

Adding docs updates from cdevents/spec#34 Signed-off-by: Andrea Frittoli <andrea.frittoli@gmail.com>

		We thus build on top of the work from other players as the following stack
		pictures exemplifies.

		@@ -0,0 +1 @@
		<mxfile host="Electron" modified="2022-03-09T14:09:43.285Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/16.5.1 Chrome/96.0.4664.110 Electron/16.0.7 Safari/537.36" etag="WJztc4Q_z2C4iVk_88a6" version="16.5.1" type="device"><diagram id="rZAp1BOKmzg2OGIajMNH" name="Page-1">5ZbdbqMwEIWfhsuVAEM2uUwJTaRVpLap1N1LC0/AG2MjY0rSp69dTAhxK3Wl7Y9aiQv7zNhmvmNsPJSU+6XEVbEWBJgX+mTvoYUXhkEUhp55fHLolJkfd0IuKbFJg7ChD2BF36oNJVCPEpUQTNFqLGaCc8jUSMNSinacthVsvGqFc3CETYaZq95RoopOncb+oK+A5kW/cuDbSIn7ZCvUBSaiPZFQ6qFECqG6VrlPgBl4PZdu3OUL0eOLSeDqNQOK9E+6WM5n02v/7m9THbLfy/aHneUes8YWvLq9vfLCRIu/8HaHu+Z8fX1lq1CHHo0UDSdgZg88dNEWVMGmwpmJtnozaK1QJbNhuw5IBfsXCwiOWPR+AlGCkgedYgegnqTdSnFk++1gTNDnFCemTKyG7V7Ij1MPuHTDEvsHeqFDL2GiIem9rqj+dLyi6UfzQi6vxWeFFX40rNiBdSMaRXnusNJVqzGQWkmxg0QwIbXCBdeZF1vK2JmEGc257jLYmhkMQarPvrmVS0qIWeRZ/oND/v+xIJqcfd9x7FgwecYB9FYOTBwH1lDX5sIwF4nUJ/x3sSKauVYcb7p38eKn48UGSsw1I/fs+KomoLczQXeHP5Gn2Mn/HEofAQ==</diagram></mxfile> No newline at end of file

Add introduction to CDEvents #34

Add introduction to CDEvents #34

Uh oh!

Conversation

m-linner-ericsson commented Mar 11, 2022

Uh oh!

e-backmark-ericsson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

afrittoli commented Mar 18, 2022

Uh oh!

afrittoli left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

afrittoli left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

afrittoli commented Mar 30, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

e-backmark-ericsson left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants