commit array should be present in change events

[xibz]

Currently, the change events include no notion or mention of commit(s). The only time where it would look to be appropriate is to have an id that is the commit. However, that seems odd imo, as things could be multiple commits. You could then say, make it the feature branch, but then you'd need to look up the commits from the feature branch to get that metadata. So I think this shows a little bit of overloading of what an id is.

So this proposal is to add a commits array

"commits": [
  {
    "id": <hash>,
    "author": "xibz", # or email?
    "message": "my commit message"
  }
]

This makes it really clear on what was merged and by who. I think we can include it for created and merged, but there may be other usecases for the other event verbs.

[afrittoli]

Thanks @xibz - indeed until now we've worked with a few simplifications in place, like only one ID in changes and only one artifact in a service/deployment. This needs to be solved by either expecting individual events for each part or by extending the existing data model to include lists of subjects.

Specifically for commits, the minimal approach would be to include the id only.

[xibz]

Yep! So what is the action item here? I can add that to the changed events, or were we thinking of a design doc or something to see how this works? Im for either. Maybe I can setup a meeting and we can do a quick go over on a few ideas on how to solve this.

[e-backmark-ericsson]

The content of the source change events has not been much elaborated yet. Before going into details we'd need to settle on whether a source change event should describe an individual commit or if it should describe a full pull/merge request. So far I believe our discussions have assumed that one source change in CDEvents lingo represents a full pull request, but there could be an option to instead let a source change correspond to an individual commit instead, and then have another event representing a pull request.

[mekhanique]

There is a use case where change sets could be related to or dependent upon change sets in other repositories for services that are somewhat more tightly coupled than what the microservices definition calls for. It is foreseable that some form of merge management could execute upon related change sets. I'd suggest an object that can support a larger change set combination to support this.

With respect to pull requests or merge events, I'd suggest that these both should be superset events, where one or more change sets are mapped to the PR and/or Merge events.

I also feel it would be beneficial to capture commit signatures for auditing and supply chain security purposes. Additionally, capturing the issue ID URL for a change tracking system supports the possibility of change tracking automation across systems that may not have a valid integration. I purposely use a string for the issue ID as not all systems use the standard URL scheme. Lastly, I'd suggest capturing both username and email address. It's possible that a user's account might be deleted making searches difficult and traceability to change owner potentially impossible. Including email address preserves some form of identity for auditing purposes.

Change Set data structure suggestion:

"changeSet": [
   "uuid": <uuid>,
   "commits": [
      {
          "uuid": <uuid>,
          "id": <hash>,
          "repository": "url",
          "issueId": "issue id string",   # support non-standard urls for custom defect tracking systems
          "author": "xibz",
          "email": "user@domain",  
          "signature": <pub.key.fingerprint>,
          "message": "my commit message",
          "forced": < yes || no>
      },
      {
          "uuid": "<uuid>",
          "id": <hash>,
          "repository": "url",
          "issueId": "string",
          "author": "xibz",
          "email": "user@domain",
          "signature": <pub.key.fingerprint>,
          "message": "my commit message",
          "forced": < yes || no>
      }
   ]
]

PR Event data structure suggestion:

"pullRequest": {
   "uuid": <uuid>,
   "status": <string>   # supports 'Open', 'Merged', 'Abandoned', 'Deleted', 'Closed' or the like
   "targetRepo": <url>,
   "targetBranch": <branch name>
   "sourceBranch: <branch name>,
   "sourceRepo": <url>,
   "relatedChangeSet": <change set uuid>,
   "relatedPullRequests": [
       "uuid": <pr uuid>,
       "uuid": <pr uuid>
   ],    
   "commits": [
       "uuid": <commit uuid>,
       "uuid": <commit uuid>
   ],
   "relatedMerges": [
       "uuid": <merge uuid>,
       "uuid": "<merge uuid>"
   ]
}

Merge Event data structure suggestion:

"merge": {
   "uuid": <uuid>,
   "relatedPullRequest": <pull request uuid>,
   "mergeType": <merge type string>  # supports fast-forward, cherry-pick, rebase
   "mergeCommit": <hash>,
   "repo": <repository url>,
   "sourceBranch: <branch name>,
   "targetBranch": <branch name>,
   "relatedChangeSet": <change set uuid>,
   "relatedPullRequest":  <pr uuid>,
   "parentCommits": [
       "uuid": <commit uuid>,
       "uuid": <commit uuid>
   ]
   "relatedMerges": [
       "uuid": <merge uuid>,
       "uuid": "<merge uuid>"
   ]
}