created change event should contain a top level description

[xibz]

While git is definitely not the only version control tool, I would say a lot of various tools utilize pull requests. While commits can have a commit message each, having an overarching description for the overall change is really beneficial.

Including a top level description field could give tools an easy way of displaying the description back to users without needing to use the GIT API or something similar.

{
  "context": {
    "version": "0.4.0-draft",
    "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
    "source": "/event/source/123",
    "type": "dev.cdevents.change.created.0.1.2",
    "timestamp": "2023-03-20T14:27:05.315384Z"
  },
  "subject": {
    "id": "mySubject123",
    "description": "description of my changes", # new field here
    "source": "/event/source/123",
    "type": "change",
    "content": {
      "repository": {
        "id": "TestRepo/TestOrg",
        "source": "https://example.org"
      }
    }
  }
}

[afrittoli]

Thanks @xibz - we strive to keep the content of the events as small as possible, as additional data can usually be retrieved via an API call. That said, I don't have an issue with adding an optional description to the spec, if that can help with the performance of visualisation tools. Would you like to propose a PR for this?

[e-backmark-ericsson]

I agree that an optional description field would be suitable in the subject of the change.created event

[e-backmark-ericsson]

One thing to keep in mind is that the description of e.g. a PR in GitHub can be edited. We would not catch such edits with the current events.