Connectors

Connectors link a GLHModel with other models, so that you can navigate, for instance, from a merge request to its Jira ticket, or from a Java class to the commits that modified it. Each connector is an optional Metacello group of the GitLabHealth baseline.

Jira

The Jira connector uses the Jira Pharo API project. It links a commit or a merge request to the Jira issue whose key (for instance WERH-918) appears in the commit message or in the merge request title.

Install

Metacello new
  repository: 'github://moosetechnology/GitProjectHealth:main/src';
  baseline: 'GitLabHealth';
  onConflict: [ :ex | ex useIncoming ];
  onUpgrade: [ :ex | ex useIncoming ];
  onDowngrade: [ :ex | ex useLoaded ];
  load: #( 'default' 'Jira' )

Loading 'default' is optional if GitProjectHealth is already loaded.

Use

GPJCConnector new
  gpModel: aGLHModel;
  jiraModel: aJiraModel;
  connect

connect looks at every GLHCommit and GLHMergeRequest of the model; then commit jiraIssue and mergeRequest jiraIssue return the linked issue. It can be run several times safely. On large models, connect only what you need with connectCommits: or connectMergeRequests:.

Complete example: issue types of the merge requests of a GitLab group

Import the merge requests and commits of the last 30 days.

model := GLHModel new name: 'git-and-jira'.

gitImporter := GitModelImporter
  forGitlabHostOn: '<GITLAB-URL>/api/v4'
  withToken: '<GITLAB-TOKEN>'
  andModel: model.
gitImporter withCommitsSince: 30 days.

group := gitImporter importGroup: <GROUP-ID>.
(group containedEntitiesOfType: GLHProject) do: [ :project |
  gitImporter
    importMergeRequestsOfProject: project
    since: (Date today - 30 days) asDateAndTime
    until: DateAndTime now.
  gitImporter importAndLoadLatestsCommitsOfProject: project ].

Import the Jira issues. Here, the issues of every commit author, matched by e-mail.

jiraApi := JiraPharoAPI new
  endpoint: '<MY-COMPANY>.atlassian.net';
  basePath: 'rest/api/latest';
  beHttps;
  user: '<JIRA-ACCOUNT-EMAIL>';
  apiToken: '<JIRA-TOKEN>';
  yourself.

jiraImporter := JiraPharoImporter new
  model: model;
  api: jiraApi;
  yourself.

authors := ((group containedEntitiesOfType: GLHCommit)
  collect: [ :commit | commit commitCreator ])
  select: [ :user | user isNotNil and: [ user isRealUser ] ].

authors asSet do: [ :user |
  jiraImporter importAllCurrentAndPastIssuesOf: user username , '@mycompany.com' ].

You can also import issues with a JQL query (importAllIssuesFromQuery:) or one by one (importIssue:).

Connect and analyze.

GPJCConnector new
  gpModel: model;
  jiraModel: jiraImporter model;
  connect.

mergeRequests := group containedEntitiesOfType: GLHMergeRequest.
withTicket := mergeRequests select: [ :mr | mr jiraIssue isNotNil ].

"Number of merge requests per Jira issue type"
(withTicket collect: [ :mr | mr jiraIssue type name ]) asBag

Famix

The Famix connector links a GLHProject with a Famix model of its source code (for instance a Java model built with VerveineJ). It matches the files of the Git model with the types of the Famix model using their paths.

Install

Metacello new
  repository: 'github://moosetechnology/GitProjectHealth:main/src';
  baseline: 'GitLabHealth';
  onConflict: [ :ex | ex useIncoming ];
  onUpgrade: [ :ex | ex useIncoming ];
  onDowngrade: [ :ex | ex useLoaded ];
  load: #( 'default' 'Famix' )

Use

Import a Famix model of the code (see Famix Java).
Import the history of the same repository with the local importer, with withFiles: true and withCommitDiffs: true.

Connect them:

GPCGitToFamixConnector new
  famixModel: famixModel;
  glhProject: project;
  connect.

Once connected, Famix classes understand appliedDiffs (the diffs that modified their file), and you can navigate from a Git diff to the corresponding Famix entity. The blog post Mixing up analysis of project architecture (Famix) and its history shows a complete analysis.