Configure Teams and Developers
==============================

By default CodeScene creates a Team and Developer configuration for each new project, 
but you also have the option to share the settings with other projects. Using a shared configuration is recommended
when several projects target the same organization, to avoid having to repeatedly configure the same Teams and Developers.

Access to Team and Developer configuration is based on project configuration access, ie if you have access to configure a project, 
you will also have access to the Team and Developer configuration used by that project.

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

Note that when updating from a version without separate team and developer configuration, 
CodeScene will automatically migrate existing settings (See :ref:`team-and-developer-migration`.)

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 for each project using the Team and Developer configuration. 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 Team and Developer configuration to proceed to the
teams configuration, as shown in :numref:`teams-configuration`.

.. figure:: teams-configuration.png
   :name: teams-configuration
   :alt: Configure teams in the Teams tab.

   Configure teams 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 :numref:`configure-team-properties`).

.. figure:: configure-team-properties.png
   :name: configure-team-properties
   :alt: Configure the teams that reflect your organization.

   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 :numref:`assign-dev-properties`.

.. figure:: GuideAssignDeveloperProperties.png
   :name: assign-dev-properties
   :alt: Clone developer information

   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.

.. _dev-alias-mapping:


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.

.. figure:: DeveloperAliasMappingDevList.png
	:name: developer-alias-mapping-dev-list
	:alt: The developer list

	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.

.. figure:: DeveloperAliasMappingAliasList.png
	    :name: developer-alias-mapping-alias-list
	    :alt: Developer list with alias list

 	    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.

.. figure:: DeveloperAliasMappingUnmerge.png
   :name: developer-alias-mapping-unmerge
   :alt: Selecting an alias to unmerge

   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.

.. figure:: DeveloperAliasMappingFilterBox.png
	    :name: developer-alias-mapping-filter-box
	    :alt: Use the filter box to search for aliases

	    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. 

.. figure:: DeveloperAliasMappingRename.png
   :alt: The rename field
   :name: developer-alias-mapping-rename

   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:

.. figure:: DeveloperAliasMappingWarning.png
   :alt: CodeScene warns that 11 authors can be merged
   :name: developer-alias-mapping-warning      

   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:

.. figure:: DeveloperAliasMappingAutoMerge.png
   :alt: The button for automatically merging developer aliases
   :name: developer-alias-mapping-auto-merge-button

   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.

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 will find the import and export functionality in the Team configuration:

.. figure:: GuideImportDeveloperTeams.png
   :alt: Import developer information

   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.

