Issue #1937826 follow-up by marvil07, jredding: Improve the description of output files.

= output files of the drupal contribution analyzer =

=== LOGS === 

The logs folder contains the raw data output in CSV format that is subsequently used to feed codeswarm and the statistic files.

The logs are named with the Drupal version analyzed or with the word "full" to indicate all versions. For example: drupal7-git-logs.csv is an analysis of Drupal 7 and drupalfull-git-logs.csv contains all versions of Drupal. 

Log files contain 4 columns - in order and an example line

commit ID                          , Unix timestamp, file affected, username

b8a1eab1fb8abb1238f1e5a63757f0d93b2a3cc6,1202326708,"INSTALL.txt","Dries"

=== STATS === 

The stats folders contains summary of the log files for faster analysis. 

There are two types of summaries - by commits and by-file-changes. Simiarly to the log files each type of summary contains one for the version of Drupal and a special "full" file that contains everything. Each file contains only 2 columns separated by a colon(:) - username & # of contributions

Ex. 

marvil07:15

--- This can be interpreted as marvil07 contributed 15 times

= by-commits (ex: drupal7-dev-participation-by-commits.txt)

Summarizes contributor information by individual based on the commit ID. If the contributor committed a modification to multiple files as part of a single commit it will count as a single contribution. 

Ex. 

marvil07:15 

--- marvil07 had 15 unique commit contributions to Drupal 7

= by-file-changes (ex: drupal7-dev-participation-by-file-changes.txt)

Summarizes contributor information by individual based on the number of files modified. If the contributor committed a modification to multiple files as part of a single commit each file will be counted as a contribution. This will also result in a higher number of contributions counted as compared to by commit. 

Ex. 

marvil07:156

--- marvil07 contributed modifications to 156 files in Drupal 7

= no-maintainers.txt 

Files ending with no-maintainers are the same files as files without this appended to the end except that core maintainers (Dries, webchick, catch, etc.) are removed from the file to not skew the results. Because core maintainers are the gatekeepers of the core repository and perform each commit they would receive an abnormal amount of credit if not removed. 

It also tries to get as much as possible attribution in commit messages

as possible.

== About output ==

Three scenarios are analyzed: 'Drupal 8.x' (`drupal8`), 'Drupal 7.x' (`drupal7`)

and 'Drupal full history' (`drupalfull`), corresponding to the development

history of `8.x`, `7.x` git branches of drupal core repository, and the full

history.

There is an extra scenario per each of the already mentioned ones, that exclude

main maintainers, for easier use, usually at viualizations generation.

The obtained information (log files) is presented in the following three ways:

'plain statistics', 'tagcloud images' and 'codeswarm videos'.

=== Log files ===

logs files, stored at 'data/logs', are the initial raw data extracted from the

git history, as CSV files.

It is used later to generate more relevant information, like codeswarm input

files or the statistic files.

The log files are named with the pattern '<scenario>-git/logs.csv'. For example:

'drupal7-git-logs.csv' contains the raw data extracted from the the '7.x' branch

of Drupal core, and 'drupalfull-git-logs.csv' contains that information

corresponding with the whole repository history.

Log files contain 4 columns: git commit hash (`%H`), authored unix timestamp

(`%at`), file affected and author (should be drupal.org username).

.CSV format

====

  b8a1eab1fb8abb1238f1e5a63757f0d93b2a3cc6,1202326708,"INSTALL.txt","Dries"

This can be interpreted as 'Dries' participated on the git commit `b8a1eab` and

one of the affected files by that commit was 'INSTALL.txt'

====

=== Plain statistics ===

Statistics files, stored at 'data/stats', contains the results of the analysis

of one of the scenarios and one indicator, as colon separated files.

There are two indicators: number of commits and number of file changes.

The statistics files are named with the pattern

'<scenario>-dev-participation-by-<indicator><|-no-maintainers>.txt'. The

'-no-maintainers' flag is added when maintainer are excluded of the file. In

example: 'drupal7-dev-participation-by-commits-no-maintainers.txt'.

[NOTE]

====

Files ending with no-maintainers are the same files as files without this

appended to the end except that core maintainers (Dries, webchick, catch, etc.)

are removed from the file to not skew the results.

Because core maintainers are the gatekeepers of the core repository and perform

each commit they would receive a lot more participation than normal contributor

mentioned on the commit messages.

This is specially usefully for visualization generation of tagclougs, since

sizes are relative to the maximum number in the set.

====

.Statistic format

====

  Damien Tournoud:414

Assuming this line comes from the file

'drupal7-dev-participation-by-commits-no-maintainers.txt', this can be

interpreted as 'Damien Tournoud' contributed to 414 commits during the

development of Drupal '7.x'.

If the contributor committed a modification to multiple files as part of a

single commit it will count as a single contribution. 

  Damien Tournoud:1437

Assuming this line comes from the file

'drupal7-dev-participation-by-file-changes.txt', this can be

interpreted as 'Damien Tournoud' contributed to 1437 files changes during the

development of Drupal '7.x'.

If the contributor committed a modification to multiple files as part of a

single commit each file will be counted as a contribution.

This will also result in a higher number of contributions counted as compared to by commit.

====

=== Tagcloud images ===

Tagcloud files, stored at 'data/tagclouds' are generated using 'Wordookie', an

extension to the processing library that allows the generation of tagcloud

images.

The generated images are 'tif' files based on each of the plain statistics files

generated before.

=== Codeswarm videos ===

Codeswarm videos, stored at 'data/codeswarm', are generated with the xml file

codeswarm program expects, which is based on the csv raw data files.

Threre are two types of videos: AVI and FLV files.

== Requirements ==

=== Mandatory ===