Documentation for usage-scorer@1 and ordering in general

[gabriel-vanca]

Please provide more info on how usage-scorer@1

From the documentation:

usage-scorer@1
Repository scorer based on it's usage by RepoM. The more it's used, the higher the score.

Properties:

windows: Specific 'windows' to calculate the score for.
max-score: The maximum score a repository can get.

It's unclear how the windows, until, max-items and max-score fields work.

[coenm]

I'll try to explain by first explaining an other comparer:

  - type: score-comparer@1
    score-provider:
      type: tag-scorer@1
      weight: 1
      tag: work

score-comparer@1 compares two repositories in order to determine the ordering in the UI. How the score of a repository is calculated is defined using the score-provider. In this case, it is the tag-scorer@1 which calculates the score of a repository by using the tags of the repository. For this config, a repository gets the value 1 if it contains the work tag and 0 otherwise.

This configuration results in that repositories with work tags are listed before repositories without.

The usage-scorer@1 creates a score based on the usage of the repository. This 'usage' is the number of times a repository action is performed on the repository. When you click a number of times on an action, this repository will have an higher score than others.

How does this work?

• First, you need to enable the Statistics plugin. Don't forget to restart RepoM.
• After restarting RepoM, you should see a module config file in %AppData%\RepoM\Module\ named Statistics.StatisticsPackage.json. You can leave these settings as is.
• When you click on an action menu item of a repository the repository and the datetime will be stored (in memory) and will be used to calculate repository scores.
• Within 00:05:00 (5 minutes), changes are persisted in a newly created file located in %AppData%\RepoM\Module\Statistics.

How to configure the usage-scorer@1?

I'll try to exmplain using this example:

  - type: score-comparer@1
    score-provider:
      type: usage-scorer@1
      max-score: 15
      windows:
      - until: 00:15:00
        weight: 4
        max-items: 2
      - until: 01:00:00
        weight: 3
        max-items: 3
      - until: 24:00:00
        weight: 2
        max-items: 5
      - until: 168:00:00
        weight: 1
        max-items: 10

This means:

• the max score is 15. (the min score is 0)
• actions recorded within 15 minutes (00:15:00) will increase the total score by 4. So if there are two actions recorded within the last 15 minutes, the first window results in a score of 2x4 = 8
• If there were 5 actions recorded, only 2 would be used for the first window with a weight of 4, and the remaining 3 would be used for the next window(s). In this case, 2 of those actions would be used in the second window resulting in a score of 2x3 = 6. The last action would be used in the third window , resulting in a score of 2.
• The total repository score using the usage-scorer would be 8+6+2 = 16. Because the max was set to 15, the final repository score would be 15.

I'll find in difficult to find the right words to explain this as clear as possible. If you still have some questions, please ask.

[coenm]

By the way,

The statistics module provides a variable (for debug puposes) to show the number of recorded calls of the repository:

  - type: just-text@1
    name: 'Usage counter: {{ statistics.count }}'

Currently, in the main branch, this documentation can be found here