Merge pull request #20 from aboutcode-org/adaaaam--healthycode-README-updates

Reorganize README.md and grimoirelab-metrics.md

Author: pombredanne

METRICS.md

@@ -0,0 +1,197 @@
+## Project Health Metrics
+
+This is the list of the metrics generated by this tool:
+
+### Pony factor
+
+The metric is defined as the number of individuals, who produce up to the
+first 50% of the total number of code contributions (in descending order)
+within a given time period.
+
+A low Pony Factor implies a high dependency on these individuals, making the
+project vulnerable if they were to leave.
+
+*Also known as: Lottery Factor, Bus Factor, Contributor Absence Factor.*
+
+CHAOSS definition of the [Contributor Abscence Factor](https://www.chaoss.community/kb/metric-contributor-absence-factor/).
+
+### Elephant factor
+
+The metric is defined as the number of unique organizations producing up to the
+first 50% of the total number of code contributions (in descending order)
+within a given time period.
+
+It was first defined by Bitergia, and it applies the concept of the
+Pony Factor metric and takes it to contributing Organizations.
+
+Contributions are focused on Git commits, and the organization
+is determined by the email address of the commit author.
+
+CHAOSS definition of the [Elephant Factor](https://www.chaoss.community/kb/metric-elephant-factor/).
+
+### Number of contributing organizations
+
+This metric quantifies the total number of distinct organizations whose members
+have made contributions to an open source project over a specified period.
+
+Contributions are focused on Git commits, and the organization
+is determined by the email address of the commit author.
+
+CHAOSS definition of the [Organizational Diversity](https://www.chaoss.community/kb/metric-organizational-diversity/).
+
+### Number of organizations contributing recently
+
+This metric quantifies the number of unique organizations whose members have
+actively made contributions to an open source project within the last 90 days.
+
+Contributions are focused on Git commits, and the organization
+is determined by the email address of the commit author.
+
+CHAOSS definition of the [Organizational Diversity](https://www.chaoss.community/kb/metric-organizational-diversity/)
+filtered by a specific timeframe.
+
+### Number of recent contributors
+
+This metric quantifies the total count of unique individuals who contributed
+within the last 90 days.
+
+CHAOSS definition of [Contributors](https://www.chaoss.community/kb/metric-contributors/) filtered by a
+specific timeframe.
+
+
+### Number of recent commits
+
+This metric counts the total number of commits made to the project within the
+last 90 days.
+
+CHAOSS definition of [Code Changes Commits](https://www.chaoss.community/kb/metric-code-changes-commits/) filtered by
+the last 90 days.
+
+### Contributor Growth Rate
+
+This metric measures the growth rate of active contributors, defined as the
+number of people sending one or more code contributions (in this case,
+Git commits) in a given period.
+
+To calculate it, the period is split into two halves, and the number of active
+contributors in each half is compared. The growth rate is the difference
+between the second half and the first half, divided by the number of active
+contributors in the first half.
+
+```math
+GrowthRate (t_1, t_2) = \frac{C_a(t_2) - C_a(t_1)}{C_a(t_1)}
+```
+
+### Contributor Growth
+
+This metric measures the growth of active contributors, defined as the
+number of people sending one or more code contributions (in this case,
+Git commits) in a given period.
+
+To calculate it, the period is split into two halves, and the number of active
+contributors in each half is compared. Growth is the difference between the
+second half and the first half.
+
+```math
+Growth (t_1, t_2) = C_a(t_2) - C_a(t_1)
+```
+
+### Number of active branches
+
+This metric refers to the count of branches within a project's version control
+repository (for this case, Git) that have seen recent development activity,
+usually indicated by new commits.
+
+CHAOSS definition of [Branch Lifecycle](https://www.chaoss.community/kb/metric-branch-lifecycle/).
+
+### Days since last commit
+
+This metric shows the number of days since the last commit was submitted to the
+repository or the project.
+
+CHAOSS definition of [Code Changes Commits](https://www.chaoss.community/kb/metric-code-changes-commits/) 
+taking into account the last commit activity.
+
+### Presence of an adopters file in a standard location
+
+This metric verifies the existence of a file containing the full text of
+the project's adopters.
+
+Standard practice dictates that this file is named `ADOPTERS`, `ADOPTERS.md`,
+or `ADOPTERS.txt`, and is located in the root directory of the project's
+source code repository.
+
+### Presence of a license file in a standard location
+
+This metric verifies the existence of a file containing the full text of
+the project's chosen open source license.
+
+Standard practice dictates that this file is named `LICENSE`, `LICENSE.md`,
+`LICENSE.txt`, or `COPYING` (a convention historically used by GNU projects)
+and is located in the root directory of the project's source code repository.
+
+CHAOSS definition of [License Declared](https://www.chaoss.community/kb/metric-licenses-declared/).
+
+### Rate of contributors contributing infrequently vs. regularly
+
+This metric involves categorizing contributors based on the frequency,
+consistency, and intensity of their contributions over a defined period. It aims
+to distinguish between individuals who contribute episodically
+(infrequent contributors) and those who engage with the project consistently
+and often substantially (regular or core contributors).
+
+The CHAOSS community, for instance, defines
+"[Occasional Contributors](https://www.chaoss.community/kb/metric-occasional-contributors/)" as
+"people who make contributions to a project on an irregular basis".
+
+### Number of contributors who have contributed in previous periods
+
+This metric, often referred to as "returning contributors" or as an indicator
+of "contributor retention," counts the number of unique individuals who were
+active contributors in the last 90 days and had also made contributions in one
+or more defined previous periods.
+
+### Rate of commits over specified periods
+
+This metrics calculates the rate of commits between the last 90 days and
+the last year. The purpose of this metrics is having an estimation of how
+distributed contributions are, and the "momentum" of the project.
+
+### Number of commits per repository
+
+Activity for each of the Git repositories analyzed.
+
+CHAOSS definition of [Code Changes Commits](https://www.chaoss.community/kb/metric-code-changes-commits/) filtered
+by repository.
+
+### Number of developers per repository
+
+Unique participants producing commits in a given repository.
+
+CHAOSS definition of [Contributors](https://www.chaoss.community/kb/metric-contributors/) filtered
+by repository.
+
+### File type metrics (code, documentation, or others)
+
+Type of activity done by developers, mainly split into code, documentation, and others.
+
+### Commit size metrics (added and removed lines)
+
+This provides an overview of the usual size of the code review processes and good practices
+when submitting code.
+
+CHAOSS uses the metric [Change Request Commits](https://www.chaoss.community/kb/metric-change-request-commits/)
+as a way to use this as a filter.
+
+### Message size metrics (total, mean, and median)
+
+This metrics provides information about how extensive a developer is providing information about the
+change in the commit.
+
+### Frequency metrics for commits
+
+This allows to understand the consistency of developers when producing code.
+
+### Developer categories (core, regular and casual)
+
+This metric structures the developers by their activity and consistency. The core developers produce