Configure Developers and Teams

Your knowledge maps are based on colors to give you an accessible high-level overview. The system will automatically assign a distinct color to each top-contributor in your codebase on the first analysis.

Sample on colored knowledge maps

Fig. 205 Sample on colored knowledge maps.

The rest of this guide will walk you through the configuration.

Important: Run an Initial Analysis Before You Configure Developers

CodeScene mines a list of all contributing developers. Note that this list is mined and updated during each analysis. That means you need to run one initial analysis before the tool gives you the option to configure developer properties!

Define Your Development Teams

Click the Teams tab in your project configuration to proceed to the teams configuration, as shown in Fig. 206.

Configure teams for a project in the Teams tab.

Fig. 206 Configure teams for a project in the Teams tab.

The only thing you have to do is to specify the name of each team in your organization. Later, when you configure developers, you’ll assign them to the team names you chose here (see Fig. 207).

Configure the teams that reflect your organization.

Tip: Some organizations just use one development team. In that case, introduce virtual teams that depend upon the responsibilities of the different developers. For example, you might want to define a Feature team, a Maintenance team and an Infrastructure team. Using this strategy, you’d be able to identify code at risk for incompatible parallel changes since different forces lead to the changes.

Even Open-Source Software Has Teams

The team definition is straightforward if you analyze a codebase that’s owned by a traditional organization; Just use the information from your organizational chart. However, we find it interesting to apply teams to open-source codebases as well.

So if you happen to analyze an open-source project, consider introducing the following teams to get additional social information:

  • Define a teams for the organization that owns the code. For example, if you analyze the Clojure codebase, you’d define Cognitect as one team. If you analyze one of Microsoft’s open-source codebases, you’d use Microsoft as one team.
  • Define a team for third party developers that contribute to the codebase
  • Consider defining a team of the core maintainers too.

Configure Developer Properties

The developer properties are a bit more tricky than the team configuration, so please let us walk you through them one by one as illustrated in Fig. 208.

Clone developer information

Fig. 208 Specify organizational information for each developer.

CodeScene automatically updates the list of contributing developers; If a new developer starts to contribute code, they’ll be present in the list and the tool lets you configure their properties.

Here are the properties you need to specify:

  1. Active/Ex-Developer: By default, all developers are considered active. If some of them leave your project, mark them as Ex-Developers and CodeScene will include them in the Knowledge Loss Analysis.
  2. Team: The second column lets you assign the developer to a team. This enables CodeScene’s organizational analyses such as the Team Knowledge Distribution Analysis.
  3. Exclude author from analysis: If you check this option, the author will be excluded from all social analyses (although their contributions will still be included in the technical analyses like Hotspots and Code Churn). This is an option you use in case you have roles like System Integrators that only merge code, but never actually make their own contributions.

Once you’ve defined all developer properties you just need to run a new analysis and you’ll get a smorgasbord of interesting social analysis results.

Developers and their Aliases: Mapping Version-Control Names to People

Often, over the lifetime of a project, some developers will sign their commits with different names. This can be a source of inaccuracies for CodeScene’s social analysis tools.

To deal with this, CodeScene provides an interface that allows you to specify the version-control names that correspond with real people. In CodeScene, when we talk about a Developer, we mean the real person. Team membership, author exclusion and ex-developer status belong to the developer. Each developer has at least one Alias, which is how they are identified in version control.

For example, a developer named Jane Doe might have several aliases in version control commits: Doe, Jane, janedoe, J. Doe, etc. This interface allows theses aliases all to refer to the same person, which provides more meaningful results in social analyses and unifies the information we have about the developer in question.

Workflow

To access the interface, click on the Developer identity mapping interface link near the top of the Developers page.

On the left, the interface displays a list of the current developers.

The developer list

Fig. 209 The Developer panel

Choose a developer you want to work on. This is the name that you want to keep.

On the right, a new list will appear. Here you can add (merge) or remove (separate) aliases from the developer you selected.

Developer list with alias list

Fig. 210 When developer is selected, the aliases appear

In this example, we might want to merge the aliases “Aaron Bedra & Stuart Sierra” and “Aaron Bedra and Stuart Halloway” with “Aaron Bedra”. After selecting those two aliases, we would click on the Stage changes button. This updates the list of developers on the left. Now we can either make other modifications or click on “Submit” at the top of the window to finalize the operation.

Separating aliases from their developers

If we change our minds, we can later separate these aliases from the developer that we assigned them to. To do this, we select the corresponding checkbox and click on Stage changes again.

Selecting an alias to unmerge

Fig. 211 Separating an alias from a developer.

After clicking on Submit, the aliases we chose to separate will become full-fledged developers. Because these are new identities, group membership, ex-developer status, and exclusion status will be lost. Merging and unmerging an alias is lossy.

Finding aliases

You can use the “Filter aliases” box to search for matching aliases. Regular expressions are allowed, with whitespace counting as a logical OR.

Use the filter box to search for aliases

Fig. 212 Using a regular expression to filter aliases

Renaming developers

Because the Developer is separate from the version control alias, developers can be renamed without changing how they are detected by CodeScene’s analyses. To change a developer’s name, click on that developer in the left column. You will notice an “Edit name” link next to their name in the box on the right.

The rename field

Fig. 213 Editing a developer’s name

Automatic alias resolution

Often, when a developer changes work environments, they will use slightly different names while keeping the same email address. In these cases, CodeScene can automatically detect aliases that in most cases should be merged together. When you run an analysis, CodeScene provides a warning:

CodeScene warns that 11 authors can be merged

Fig. 214 The early warning in the analysis results

Inside the developer alias interface, when CodeScene has identified merge suggestions, a button is visible that allows all the suggestions to be merged at once:

The button for automatically merging developer aliases

Fig. 215 Merge all suggestions

Clicking on the button will cause all the suggestions to be staged. You will still need to click on “Submit” to save the changes.

CodeScene uses two different criteria for making merge suggestions:

  • If a developer already has more than one alias, CodeScene will suggest adding more aliases to that developer.
  • Otherwise, CodeScene chooses the developer with the longest name (excluding names that are actually email addresses).

If you need more control, the suggestions are also visible in the list of developers and will appear when you select a developer.

Configure for Pair Programming

In case your organization uses practices like pair or mob programming you need to tell CodeScene about it. You do that in the Social part of your project configuration as shown in Fig. 216.

Configure patterns for pair programming

Fig. 216 Configure patterns to extract author information that reflects pair programming.

The pair and mob programming support requires that you specify the name or aliases of the authors in your commit messages. CodeScene will then extract those authors as shown in Fig. 217.

Examples on pair programming

Fig. 217 Pair and mob programming annotations in the commit messages.

Using the configured pattern, CodeScene extracts the author information from your commit messages and adjusts the knowledge maps by splitting the code contributions between the members of each pair.

The configuration is based on a regular expression with the following constraints:

  1. It must contain at least one match group.
  2. Each match group will map to exactly one author.

Most pair programming patterns contain some kind of delimiter in the commit message. The preceding examples used square brackets for the pair programming info, [ and ], and a pipe | to separate the authors, but CodeScene supports any delimiter like Pair: X,Y or (devs: X/Y).

The most common patterns are:

  • Always a pair: Specify a pattern such that you get two match groups. For example, to match the authors in [Author X|Author Y] you use a pattern like [([ws]+)|([ws]+)].
  • Sometimes a pair, sometimes an individual: CodeScene defaults to Git’s Author information field if it cannot match the configured pattern, so this scenario will work with the previous pattern.
  • All author info is in the commit message: In this case you need to make the second match group optional. For example, to match both the pair [Author X|Author Y] and the single developer [Author X] you specify [([ws]+)|?([ws]+)?].
  • Many authors (a mob): To match more than two authors, we recommend that you introduce even more optional match groups. For example, to match [Author X|Author Y|Author Z] you specify [([ws]+)|?([ws]+)?|?([ws]+)?].

Those more elaborate patterns may be a bit tricky, but it’s a one off configuration so once you have it up and running you won’t see it again.

Finally, note that the preceding examples use aliases for each author instead of their full names. You can map those aliases to real author names using CodeScene’s UI for developer identity aliases.

Import or Export a Definition of Development Teams

It may well be impractical to configure each team and developer via the UI, particularly for large organizations. That’s why CodeScene supports importing the team definitions by uploading a csv-file specifying the organization. You can also share teams between projects, by exporting your team definitions and then importing them in another project.

You will find the import and export functionality in the Team configuration:

Import developer information

Fig. 218 Importing developer information by uploading a CSV file.

The input file specifies your organization. The file format used is a CSV with two columns: author and team.