Commit 2b3d58f8 authored by Sergio Merino Hernández's avatar Sergio Merino Hernández Committed by Jose Javier Merchante

[docs] Update documentation

This commit will update the documentation of some charts.
parent dda43dfd
......@@ -15,10 +15,10 @@ This section shows an overview metrics panel about the analyzed data (mainly git
- [\# Issues created](overview/issues-created.md)
- [\# Issues closed](overview/issues-closed.md)
- [Median time to close](overview/median-time-to-close.md)
- [\# Commits over time (chart)](activity/commits-over-time.md)
- [\# Authors per category over time (chart)](overview/authors-evolution.md)
- [\# Issues open/closed (chart)](activity/issues-open-closed.md)
- [\# Reviews open/closed (chart)](activity/reviews-open-closed.md)
- [\# Commits (chart)](activity/commits-chart.md)
- [\# Authors per category (chart)](overview/authors-evolution.md)
- [\# Issues created/closed (chart)](activity/issues-created-closed.md)
- [\# Reviews started/closed (chart)](activity/reviews-created-closed.md)
## Activity
......@@ -26,7 +26,7 @@ This section shows metrics related to the activity of the analyzed data (mainly
- [\# Commits](activity/commits.md)
- [\# Lines/commit](activity/lines-commit.md)
- [\# Lines/commit/file](activity/lines-commit-file.md)
- [\# Commits over time (chart)](activity/commits-over-time.md)
- [\# Commits (chart)](activity/commits-chart.md)
- [\# Lines added/removed (chart)](activity/lines-added-removed.md)
- [\# Commits by hour of the day (chart)](activity/commits-by-hour-of-day.md)
- [\# Commits by weekday (chart)](activity/commits-by-weekday.md)
......@@ -35,7 +35,7 @@ This section shows metrics related to the activity of the analyzed data (mainly
- [\# Issues created](activity/issues-created.md)
- [\# Issues closed](activity/issues-closed.md)
- [\# Issues open](activity/issues-open.md)
- [\# Issues open/closed (chart)](activity/issues-open-closed.md)
- [\# Issues created/closed (chart)](activity/issues-created-closed.md)
- [\# Open issues age (chart)](activity/open-issues-age.md)
- [\# Issues open by weekday (chart)](activity/issues-open-by-weekday.md)
- [\# Issues closed by weekday (chart)](activity/issues-closed-by-weekday.md)
......@@ -46,7 +46,7 @@ This section shows metrics related to the activity of the analyzed data (mainly
- [\# Pull/Merge requests created](activity/pull-merge-requests-created.md)
- [\# Pull/Merge requests closed](activity/pull-merge-requests-closed.md)
- [\# Pull/Merge requests open](activity/pull-merge-requests-open.md)
- [\# Reviews open/closed (chart)](activity/reviews-open-closed.md)
- [\# Reviews started/closed (chart)](activity/reviews-created-closed.md)
- [\# Open reviews age (chart)](activity/open-reviews-age.md)
- [\# Reviews open by weekday (chart)](activity/reviews-open-by-weekday.md)
- [\# Reviews closed by weekday (chart)](activity/reviews-closed-by-weekday.md)
......
# \# Commits (chart)
Number of commits is the most common measure of activity in a git repository. To compute it, we're considering all commits in all branches of all repositories in the project, excluding empty commits. Each commit represents a change to the source code, maybe touching several files. However, commits may be very different in size, complexity and usefulness to the project, so this number should only be considered as an indicator, among others.
**Important details**: Because of the way people work with git repositories, it is usual that the latest commits that developers are producing are still in their personal repositories, maybe following a review process, and were still not merged in the repositories that we track. Because of that, it is usual that for the last few days (or in some cases, weeks), there is a severe underestimation of the number of commits. As time passes, it is usual that the count of commits for that period increases, as all those "pending" commits find their way to the repository.
## Elasticsearch query parameters
```
index: 'git'
filter: 'files' is not 0
range: from_date < 'grimoire_creation_date' < to_date
filter: 'terms', origin=urls
aggregation: 'date_histogram', field: 'grimoire_creation_date', calendar_interval: '1w'
```
# \# Commits over time
Evolution of the number of commits in the period defined by the user, ignoring pull/merge request commits.
```
index: 'git'
filter: 'files' is not 0
range: from_date < 'grimoire_creation_date' < to_date
filter: 'terms', origin=urls
aggregation: 'date_histogram', field: 'grimoire_creation_date', calendar_interval: '1w'
```
# \# Commits
Number of commits, ignoring pull/merge request commits.
Number of commits, ignoring empty commits.
- Last month: from 1 month ago to now.
- Last year: from 1 year ago to now.
- Year-over-year: comparison of commits from last year to the previous year.
## Elasticsearch query parameters
```
index: 'git'
unique count: 'hash'
......
# \# Issues created/closed
Number of issues shows activity in the issue tracking system, usually including bug reports, feature requests, and other tasks that are tracked with issues (tickets). We measure, for each week, the number of issues that were opened (created) or closed during it. Not only the absolute numbers, but also the relationship between open and closed issues is important in this chart: if many more issues are consistently being opened than closed, the project is not dealing with all the new stuff that is entering the issue tracking system.
**Important details**: Some projects using git repositories in GitHub or GitLab are dealing with issues elsewhere (for example, their own instance of Bugzilla or Jira). So, in some cases this chart can be flat, or show a really low activity, just because that activity is happening somewhere else. Also, different projects may use issues in different ways, from only tracking bugs reported by users, to dealing with all the bug fixing, feature implementation, and other tasks performed by the project.
## Elasticsearch query parameters
```
index: 'all'
filter: pull_request:False or is_gitlab_issue:1
filter: 'terms', origin=urls
<open>
aggregation: 'filter': range(from_date < created_at < to_date)
aggregation: 'date_histogram', field: 'created_at', calendar_interval: '1w'
<closed>
aggregation: 'filter': range(from_date < closed_at < to_date)
aggregation: 'date_histogram', field: 'closed_at', calendar_interval: '1w'
```
# \# Issues open/closed
Open and closed issues by date in the period defined by the user.
```
index: 'all'
filter: pull_request:False or is_gitlab_issue:1
filter: 'terms', origin=urls
<open>
aggregation: 'filter': range(from_date < created_at < to_date)
aggregation: 'date_histogram', field: 'created_at', calendar_interval: '1w'
<closed>
aggregation: 'filter': range(from_date < closed_at < to_date)
aggregation: 'date_histogram', field: 'closed_at', calendar_interval: '1w'
```
# \# Reviews open/closed
# \# Reviews started/closed
Open and closed PRs/MRs by date in the period defined by the user.
Number of reviews shows activity related to pull requests (GitHub) or merge requests (GitLab). This chart shows, for each week, the number of merge or pull requests that were submitted (started), and decided (closed). Pull and merge reviews are the mechanism used for reviewing code changes that are proposed to enter repositories. Closing a pull or merge request can be done by accepting the change, or by declining it. As with issues, a larger number of started reviews than closed reviews means that the project is not coping with all proposals for code change that are being submitted.
**Important details**: Even when it is considered a good practice, not all projects are using it, or not for all changes. Also, the code changes in a merge or pull request may include one or more commits, depending on the policies of the project.
## Elasticsearch query parameters
```
index: 'all'
filter: pull_request:True or merge_request:True
......
# \# Authors per category over time
# \# Authors
Evolution of the number of authors (contributors, maintainers, observers, and users) in the period defined by the user.
Number of authors gives an idea of the size of the active developer community for a project. In this case, we're measuring, for each week in the chart, the number of different identities that authored at least one commit in git repositories of the project during that week. Although this is usually a good indicator of developers who are active in the project, it is important to notice that, during any given week, active developers may be busy with some complex code change that will produce no commit during the week, or reviewing code, or in any other task related to the project, but not appearing in this chart. People taking care of other important tasks, such as writing documentation, may also be reflected in this chart, or not, depending on the repositories included in the project, and on the fact that those tasks are reflected in commits, or not.
**Important details**: We say "identities" and not "persons" because, a certain developer could commit with different identities. This happens mainly because developers update their identities (name, email address), or because they use different accounts with slight differences (eg, including or not a middle name, or using their corporate or personal email addresses), and is uncommon during the same week.
## Elasticsearch query parameters
```
index: 'all'
unique count: 'author_uuid'
......
# \# Commits
Number of commits, ignoring pull/merge request commits.
Number of commits, ignoring empty commits.
## Elasticsearch query parameters
```
index: 'git'
unique count: 'hash'
......
......@@ -2,6 +2,7 @@
Number of closed issues in a period of time.
## Elasticsearch query parameters
```
index: 'all'
range: from_date < 'closed_at' < to_date
......
......@@ -2,6 +2,7 @@
Number of created issues in a period of time.
## Elasticsearch query parameters
```
index: 'all'
range: from_date < 'created_at' < to_date
......
......@@ -2,6 +2,7 @@
Median time to merge a pull request or merge request (reviews merged in the period defined by the user that were opened at any time)
## Elasticsearch query parameters
```
index: 'all'
50th percentil: 'time_to_close_days'
......
......@@ -2,6 +2,7 @@
Median time to close issues (issues closed in the period defined by the user that were opened at any time).
## Elasticsearch query parameters
```
index: 'all'
50th percentil: 'time_to_close_days'
......
......@@ -2,6 +2,7 @@
Number of new Pull/Merge Requests in a period of time.
## Elasticsearch query parameters
```
index: 'all'
range: from_date < 'created_at' < to_date
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment