Reformat the spec root page, add subjects and actions #26
Conversation
spec.md
Outdated
| - long running, which stay in a running state until they're purposely stopped or | ||
| encounter a failure or a condition that prevents them from running - for | ||
| example a service or an environment | ||
| - run to completion, which independently stop after they accomplished (or | ||
| failed to) a specific task, or encounter a failure or a condition that | ||
| prevents them from continuing - for example a task run, a build or a test |
There was a problem hiding this comment.
Alternative names could be services vs jobs (or batches) - other idea? Does this distinction make sense?
I introduced these two groups as I think they have similar properties in terms of actions that are associated to them.
There was a problem hiding this comment.
If we are talking about long running jobs we probably need to explain why we recommend the user to use our events instead of using eg. Open Telemetry to monitor the application. Should this be then part of Continuous Operations bucket or something?
There was a problem hiding this comment.
Fair point, but not necessarily continuous operations - there are examples in the existing events - specifically environments and services.
There was a problem hiding this comment.
I guess we could have other subjects as artifact, branch, repository and change. Where would those fall?
There was a problem hiding this comment.
I would say those would all be long running
There was a problem hiding this comment.
Sorry but you lost me. How can an artifact be long running? An artifact could be documentation, that is not something that will be run. It could of course be deployed but I wouldn't define it as long running.
Should we instead talk about "permanent subject" and "temporary subject"?
- "Permanent subjects" would have a long lifespan and nothing will wait for it because it will not complete.
- "Temporary subjects" would have a short lifespan that can have things waiting for it as it will complete.
Not sure about "permanent" and "temporary" but I hope you get the idea what I am out after.
If you think it will drag out this PR. Let us take it in another one.
There was a problem hiding this comment.
Yeah, that's the issue with the term "long running" - an artefact is not "running", but it continue to exists unless someone takes an explicit action to remove it.
The key differentiator between the two categories is that subjects in the first one naturally runs to completion after performing a job of some kind (taskrun, pipelinerun, build, test), while subjects in the second one will continue to exists unless someone of something takes an action to terminate them (service, environment, artifact).
I'm not quite sure what a good terminology could be for this.
There a couple of reasons for introducing the two categories:
- events in each category are likely to share predicates
- producers and consumers may expect different set of predicates
- from a producer point of view, subject that run to completion won't have an explicit trigger when they complete, so setting up links might be challenging in the completion event
Defining the two groups and giving them a name may help reason about their predicates in general.
I created #27 to track this discussion
There was a problem hiding this comment.
ok, lets track it there
| occurrence, or in case of a service, deployed in a valid action. Valid actions | ||
| are defined in the [vocabulary](#vocabulary). | ||
|
|
||
| ## Context |
There was a problem hiding this comment.
I have not added anything to the common context for now. If we agree on the subject name, I will add a "subject id" as part of the optional context.
The context will also be expanded with links based on #10 and as discussed in the WG, but I will setup a dedicated PR for that.
There was a problem hiding this comment.
I will add the subject in a follow-up PR
spec.md
Outdated
| __Note__: CDEvents adopts, wherever applicable, the terminology used by | ||
| [CloudEvents](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#notational-conventions). | ||
|
|
||
| This specification defines the following terms: |
There was a problem hiding this comment.
The below is, I think, a verbatim (or close to verbatim) copy of the linked CloudEvents spec, so it might be nice to make this more clear.
Maybe "This specification borrows the following terms from the CloudEvents specification:"
There was a problem hiding this comment.
Uhm, that's what I was trying to express in L47 :)
I was debating about only including deltas from the CloudEvents spec, but I though I didn't want to create that kind of dependency, so attribution would be enough. I can make more clear in L50.
There was a problem hiding this comment.
The list below is not meant to be only a list of borrowed terms - subject and action for instance are not defined in CloudEvents, and some of the terms have been adapted to CDEvents.
What I could do is, for the terms that are identical, link the original definition on CloudEvents side.
I didn't go down that route though because we might want to change definitions over time.
There was a problem hiding this comment.
Does this sound better?
Note: CDEvents adopts, wherever applicable, the terminology used by
CloudEvents. Some of the definitions below are borrowed
from that specification.
There was a problem hiding this comment.
As I noted in my comments I was a bit confused on where the terms ended. Could we just link to the terminology for CloudEvents or does it help the reader keeping it on this page? What would happen if CloudEvents changes it?
There was a problem hiding this comment.
Heh, nice catch, the title level on "subject" or "action" is one too much :) I will fix that.
We could not just link to the terminology for CloudEvents because it's not an 100% match - CloudEvents terms are more focused on routing, while CDEvents are more focused on the data part and its semantics.
There was a problem hiding this comment.
So, finally I included links to terms which are borrowed from CloudEvents, I hope that make things clearer :)
Thanks for the feedback on this
There was a problem hiding this comment.
Nice, just one question. Why not keep this part of the event definition? I think it adds value but there might be something I am missing.
Events will contain two types of information: the Event Data representing the Occurrence and Context metadata providing contextual information about the Occurrence. A single occurrence MAY result in more than one event.
There was a problem hiding this comment.
I think that part may not be fitting for CDEvents - we haven't fully designed it yet, so I didn't want to include it until I was sure how it was going to be.
spec.md
Outdated
| - long running, which stay in a running state until they're purposely stopped or | ||
| encounter a failure or a condition that prevents them from running - for | ||
| example a service or an environment | ||
| - run to completion, which independently stop after they accomplished (or | ||
| failed to) a specific task, or encounter a failure or a condition that | ||
| prevents them from continuing - for example a task run, a build or a test |
There was a problem hiding this comment.
If we are talking about long running jobs we probably need to explain why we recommend the user to use our events instead of using eg. Open Telemetry to monitor the application. Should this be then part of Continuous Operations bucket or something?
afrittoli
force-pushed
the
root_spec
branch
4 times, most recently
from
bd39761 to
f38a7c8
Compare
|
Once Emil's changes are considered, you can assume approval from me. |
Restructure a the spec root page, add more sections and introduce the initial terminology, including subjects and predicates. This provides the basis for restructuring the vocabulary and defining the schemas that will be used to build the SDKs. Partially addresses: cdevents#12 Related to: cdevents#11 Signed-off-by: Andrea Frittoli <andrea.frittoli@gmail.com>
|
@afrittoli To enable other people outside our group to understand this I think we need full examples of a couple of scenarios. These examples could be based on cloud event bindings. |
I totally agree - this PR is not meant to be comprehensive - I'm trying to set here the base terminology so that we can update the rest, define examples etc |
|
Thanks everyone for the great input on this. I'll go ahead and merge, and start working on the next parts. |
Sync the changes in cdevents/spec#26 Signed-off-by: Andrea Frittoli <andrea.frittoli@gmail.com>
Restructure a the spec root page, add more sections and introduce
the initial terminology, including subjects and actions.
This provides the basis for restructuring the vocabulary and
defining the schemas that will be used to build the SDKs.
Partially addresses: #12
Related to: #11
Signed-off-by: Andrea Frittoli andrea.frittoli@gmail.com