Create a health evaluation criteria (#1550)

* Creating a command to update metrics - initial step

* Add missing properties to the project model and update the metrics script

* Apply make-check and check-spelling

* Update tests

* Apply coderabbitai suggestion

* Add is_funding_requirements_compliant to the metrics script

* Apply coderabbitai suggestion

* Add owasp_page_last_updated_at to the metrics

* Refactor is_funding_requirements_compliant logic

* Add command to calculate score

* Remove TODO

* Add metrics test

* Add metrics_score test

* Update metrics test

* Apply suggestions and add tests

* Rename score script to be plural

* Change the logic to create multiple ProjectHealthMetrics objects for a project and apply suggestions

* Apply coderabbitai suggestion

* Make open issues count negative direction

* Evaluate the funding and project leaders requirement in the score and add tests

* Apply suggestions

* Apply coderabbitai suggestion

* Apply coderabbitai suggetion

* Fix tests

* Update code

* Apply suggestions

* Fix if condition

* Update code

* Make older projects have higher scores

---------

Co-authored-by: Kate Golovanova <[email protected]>
Co-authored-by: Arkadii Yakovets <[email protected]>
Co-authored-by: Arkadii Yakovets <[email protected]>

Author: 3 people

backend/Makefile

@@ -104,11 +104,15 @@ owasp-process-snapshots:
 	@CMD="python manage.py owasp_process_snapshots" $(MAKE) exec-backend-command
 
 owasp-update-project-health-metrics:
-	@echo "Updating OWASP project health requirements"
+	@echo "Updating OWASP project health metrics"
 	@CMD="python manage.py owasp_update_project_health_metrics" $(MAKE) exec-backend-command
 
+owasp-update-project-health-metrics-scores:
+	@echo "Updating OWASP project health metrics score"
+	@CMD="python manage.py owasp_update_project_health_metrics_scores" $(MAKE) exec-backend-command
+
 owasp-update-project-health-requirements:
-	@echo "Updating OWASP project health metrics"
+	@echo "Updating OWASP project health requirements"
 	@CMD="python manage.py owasp_update_project_health_requirements" $(MAKE) exec-backend-command
 
 owasp-scrape-chapters:

backend/apps/owasp/admin.py

@@ -164,6 +164,30 @@ def custom_field_name(self, obj) -> str:
     custom_field_name.short_description = "Name"
 
 
+class ProjectHealthMetricsAdmin(admin.ModelAdmin):
+    autocomplete_fields = ("project",)
+    list_filter = (
+        "project__level",
+        "nest_created_at",
+    )
+    list_display = (
+        "project",
+        "nest_created_at",
+        "score",
+        "contributors_count",
+        "stars_count",
+        "forks_count",
+        "open_issues_count",
+        "open_pull_requests_count",
+        "recent_releases_count",
+    )
+    search_fields = ("project__name",)
+
+    def project(self, obj):
+        """Display project name."""
+        return obj.project.name if obj.project else "N/A"
+
+
 class SnapshotAdmin(admin.ModelAdmin):
     autocomplete_fields = (
         "new_chapters",
@@ -229,7 +253,7 @@ class SponsorAdmin(admin.ModelAdmin):
 admin.site.register(Event, EventAdmin)
 admin.site.register(Post, PostAdmin)
 admin.site.register(Project, ProjectAdmin)
-admin.site.register(ProjectHealthMetrics)
+admin.site.register(ProjectHealthMetrics, ProjectHealthMetricsAdmin)
 admin.site.register(ProjectHealthRequirements)
 admin.site.register(Snapshot, SnapshotAdmin)
 admin.site.register(Sponsor, SponsorAdmin)

backend/apps/owasp/management/commands/owasp_update_project_health_metrics.py

@@ -0,0 +1,45 @@
+"""A command to update OWASP project health metrics."""
+
+from django.core.management.base import BaseCommand
+
+from apps.owasp.models.project import Project
+from apps.owasp.models.project_health_metrics import ProjectHealthMetrics
+
+
+class Command(BaseCommand):
+    help = "Update OWASP project health metrics."
+
+    def handle(self, *args, **options):
+        metric_project_field_mapping = {
+            "contributors_count": "contributors_count",
+            "created_at": "created_at",
+            "forks_count": "forks_count",
+            "is_funding_requirements_compliant": "is_funding_requirements_compliant",
+            "is_leader_requirements_compliant": "is_leader_requirements_compliant",
+            "last_committed_at": "pushed_at",
+            "last_released_at": "released_at",
+            "open_issues_count": "open_issues_count",
+            "open_pull_requests_count": "open_pull_requests_count",
+            "owasp_page_last_updated_at": "owasp_page_last_updated_at",
+            "pull_request_last_created_at": "pull_request_last_created_at",
+            "recent_releases_count": "recent_releases_count",
+            "stars_count": "stars_count",
+            "total_issues_count": "issues_count",
+            "total_pull_requests_count": "pull_requests_count",
+            "total_releases_count": "releases_count",
+            "unanswered_issues_count": "unanswered_issues_count",
+            "unassigned_issues_count": "unassigned_issues_count",
+        }
+        project_health_metrics = []
+        for project in Project.objects.all():
+            self.stdout.write(self.style.NOTICE(f"Evaluating metrics for project: {project.name}"))
+            metrics = ProjectHealthMetrics(project=project)
+
+            # Update metrics based on requirements.
+            for metric_field, project_field in metric_project_field_mapping.items():
+                setattr(metrics, metric_field, getattr(project, project_field))
+
+            project_health_metrics.append(metrics)
+
+        ProjectHealthMetrics.bulk_save(project_health_metrics)
+        self.stdout.write(self.style.SUCCESS("Evaluated projects health metrics successfully. "))

backend/apps/owasp/management/commands/owasp_update_project_health_metrics_scores.py

@@ -0,0 +1,66 @@
+"""A command to update OWASP project health metrics scores."""
+
+from django.core.management.base import BaseCommand
+
+from apps.owasp.models.project_health_metrics import ProjectHealthMetrics
+from apps.owasp.models.project_health_requirements import ProjectHealthRequirements
+
+
+class Command(BaseCommand):
+    help = "Update OWASP project health metrics score."
+
+    def handle(self, *args, **options):
+        forward_fields = {
+            "age_days": 6.0,
+            "contributors_count": 6.0,
+            "forks_count": 6.0,
+            "is_funding_requirements_compliant": 5.0,
+            "is_leader_requirements_compliant": 5.0,
+            "open_pull_requests_count": 6.0,
+            "recent_releases_count": 6.0,
+            "stars_count": 6.0,
+            "total_pull_requests_count": 6.0,
+            "total_releases_count": 6.0,
+        }
+        backward_fields = {
+            "last_commit_days": 6.0,
+            "last_pull_request_days": 6.0,
+            "last_release_days": 6.0,
+            "open_issues_count": 6.0,
+            "owasp_page_last_update_days": 6.0,
+            "unanswered_issues_count": 6.0,
+            "unassigned_issues_count": 6.0,
+        }
+
+        project_health_metrics = []
+        project_health_requirements = {
+            phr.level: phr for phr in ProjectHealthRequirements.objects.all()
+        }
+        for metric in ProjectHealthMetrics.objects.filter(
+            score__isnull=True,
+        ).select_related(
+            "project",
+        ):
+            # Calculate the score based on requirements.
+            self.stdout.write(
+                self.style.NOTICE(f"Updating score for project: {metric.project.name}")
+            )
+
+            requirements = project_health_requirements[metric.project.level]
+
+            score = 0.0
+            for field, weight in forward_fields.items():
+                if int(getattr(metric, field)) >= int(getattr(requirements, field)):
+                    score += weight
+
+            for field, weight in backward_fields.items():
+                if int(getattr(metric, field)) <= int(getattr(requirements, field)):
+                    score += weight
+
+            metric.score = score
+            project_health_metrics.append(metric)
+
+        ProjectHealthMetrics.bulk_save(project_health_metrics, fields=["score"])
+        self.stdout.write(
+            self.style.SUCCESS("Updated projects health metrics score successfully.")
+        )

backend/apps/owasp/management/commands/owasp_update_project_health_requirements.py

@@ -14,6 +14,8 @@ class Command(BaseCommand):
             "age_days": 15,
             "contributors_count": 1,
             "forks_count": 2,
+            "is_funding_requirements_compliant": True,
+            "is_leader_requirements_compliant": False,
             "last_commit_days": 365,
             "last_pull_request_days": 60,
             "last_release_days": 365,
@@ -32,6 +34,8 @@ class Command(BaseCommand):
             "age_days": 20,
             "contributors_count": 3,
             "forks_count": 5,
+            "is_funding_requirements_compliant": True,
+            "is_leader_requirements_compliant": True,
             "last_commit_days": 270,
             "last_pull_request_days": 45,
             "last_release_days": 365,
@@ -50,6 +54,8 @@ class Command(BaseCommand):
             "age_days": 30,
             "contributors_count": 4,
             "forks_count": 7,
+            "is_funding_requirements_compliant": True,
+            "is_leader_requirements_compliant": True,
             "last_commit_days": 90,
             "last_pull_request_days": 30,
             "last_release_days": 180,
@@ -68,6 +74,8 @@ class Command(BaseCommand):
             "age_days": 30,
             "contributors_count": 5,
             "forks_count": 10,
+            "is_funding_requirements_compliant": True,
+            "is_leader_requirements_compliant": True,
             "last_commit_days": 180,
             "last_pull_request_days": 30,
             "last_release_days": 365,
@@ -84,59 +92,41 @@ class Command(BaseCommand):
         },
     }
 
-    def add_arguments(self, parser) -> None:
-        parser.add_argument(
-            "--level",
-            type=str,
-            choices=[level[0] for level in Project.ProjectLevel.choices],
-            help="Project level to set requirements for",
-        )
-
     def get_level_requirements(self, level):
         """Get default requirements based on project level."""
-        defaults = {
-            "age_days": 0,
-            "contributors_count": 0,
-            "forks_count": 0,
-            "last_commit_days": 0,
-            "last_pull_request_days": 0,
-            "last_release_days": 0,
-            "open_issues_count": 0,
-            "open_pull_requests_count": 0,
-            "owasp_page_last_update_days": 0,
-            "recent_releases_count": 0,
-            "recent_releases_time_window_days": 0,
-            "stars_count": 0,
-            "total_pull_requests_count": 0,
-            "total_releases_count": 0,
-            "unanswered_issues_count": 0,
-            "unassigned_issues_count": 0,
-        }
-
-        return self.LEVEL_REQUIREMENTS.get(level, defaults)
+        return self.LEVEL_REQUIREMENTS.get(
+            level,
+            {
+                "age_days": 0,
+                "contributors_count": 0,
+                "forks_count": 0,
+                "is_funding_requirements_compliant": True,
+                "is_leader_requirements_compliant": True,
+                "last_commit_days": 0,
+                "last_pull_request_days": 0,
+                "last_release_days": 0,
+                "open_issues_count": 0,
+                "open_pull_requests_count": 0,
+                "owasp_page_last_update_days": 0,
+                "recent_releases_count": 0,
+                "recent_releases_time_window_days": 0,
+                "stars_count": 0,
+                "total_pull_requests_count": 0,
+                "total_releases_count": 0,
+                "unanswered_issues_count": 0,
+                "unassigned_issues_count": 0,
+            },
+        )
 
     def handle(self, *args, **options) -> None:
         """Handle the command execution."""
-        level = options.get("level")
-
-        if level:
-            defaults = self.get_level_requirements(level)
-            requirements, created = ProjectHealthRequirements.objects.get_or_create(
-                level=level, defaults=defaults
+        for level_code, level_name in sorted(Project.ProjectLevel.choices):
+            _, created = ProjectHealthRequirements.objects.update_or_create(
+                level=level_code,
+                defaults=self.get_level_requirements(level_code),
             )
 
-            action = "Created" if created else "Updated"
-            print(f"{action} health requirements for {requirements.get_level_display()} projects")
-        else:
-            for level_choice in Project.ProjectLevel.choices:
-                level_code = level_choice[0]
-                defaults = self.get_level_requirements(level_code)
-
-                requirements, created = ProjectHealthRequirements.objects.get_or_create(
-                    level=level_code, defaults=defaults
-                )
-
-                if created:
-                    print(f"Created default health requirements for {level_choice[1]} projects")
-                else:
-                    print(f"Health requirements already exist for {level_choice[1]} projects")
+            print(
+                f"{'Created' if created else 'Updated'} health requirements for "
+                f"{level_name} projects"
+            )

backend/apps/owasp/migrations/0035_rename_total_pull_request_count_projecthealthmetrics_total_pull_requests_count.py

@@ -0,0 +1,17 @@
+# Generated by Django 5.2.1 on 2025-06-03 14:47
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("owasp", "0034_alter_chapter_leaders_and_more"),
+    ]
+
+    operations = [
+        migrations.RenameField(
+            model_name="projecthealthmetrics",
+            old_name="total_pull_request_count",
+            new_name="total_pull_requests_count",
+        ),
+    ]

backend/apps/owasp/migrations/0036_alter_projecthealthmetrics_score.py

@@ -0,0 +1,28 @@
+# Generated by Django 5.2.1 on 2025-06-08 02:58
+
+import django.core.validators
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        (
+            "owasp",
+            "0035_rename_total_pull_request_count_projecthealthmetrics_total_pull_requests_count",
+        ),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="projecthealthmetrics",
+            name="score",
+            field=models.FloatField(
+                help_text="Project health score (0-100)",
+                null=True,
+                validators=[
+                    django.core.validators.MinValueValidator(0.0),
+                    django.core.validators.MaxValueValidator(100.0),
+                ],
+            ),
+        ),
+    ]

backend/apps/owasp/migrations/0037_alter_projecthealthmetrics_project.py

@@ -0,0 +1,22 @@
+# Generated by Django 5.2.1 on 2025-06-08 03:01
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("owasp", "0036_alter_projecthealthmetrics_score"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="projecthealthmetrics",
+            name="project",
+            field=models.ForeignKey(
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="health_metrics",
+                to="owasp.project",
+            ),
+        ),
+    ]

backend/apps/owasp/migrations/0038_remove_projecthealthmetrics_is_project_leaders_requirements_compliant_and_more.py

@@ -0,0 +1,23 @@
+# Generated by Django 5.2.2 on 2025-06-12 23:19
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("owasp", "0037_alter_projecthealthmetrics_project"),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name="projecthealthmetrics",
+            name="is_project_leaders_requirements_compliant",
+        ),
+        migrations.AddField(
+            model_name="projecthealthmetrics",
+            name="is_leaders_requirements_compliant",
+            field=models.BooleanField(
+                default=False, verbose_name="Is project leaders requirements compliant"
+            ),
+        ),
+    ]