From 1424f058706f95f3339210f50bb93da08094613a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jordi=20G=C3=B3mez?= <jordi.gomez@eclipse-foundation.org>
Date: Tue, 29 Apr 2025 11:01:39 +0200
Subject: [PATCH 1/2] docs: adding mermaid sequence diagram displaying the
current picture
---
README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 91 insertions(+)
diff --git a/README.md b/README.md
index cffc1110..142636cc 100644
--- a/README.md
+++ b/README.md
@@ -152,3 +152,94 @@ The `Volatile` column denotes whether the property is subject to change once ini
| parent_project | integer/null | ✓ | Denotes whether the project has a parent, which indicates a fork. However, the user can remove the relation to the parent project. |
| creation_date | string | x | The project's creation date. |
| deletion_date | string/null | ✓ | The project's deletion date. Subject to change. |
+
+## Current Picture
+
+```mermaid
+sequenceDiagram
+ participant Git as Git Providers (GitHub/GitLab)
+ participant ECA as Git ECA Rest API
+ participant Cache as Cache Layer
+ participant DB as Database
+ participant Projects as Eclipse Projects API
+ participant Users as Eclipse Accounts API
+ participant Bots as Eclipse Bots API
+
+ Git->>ECA: Send PR/Push event
+ activate ECA
+
+ alt GitHub PR
+ ECA->>Git: Fetch PR details
+ Git-->>ECA: PR data
+ else GitLab Push
+ ECA->>Git: Fetch repository details
+ Git-->>ECA: Repository data
+ end
+
+ ECA->>Git: Fetch all commit details
+ Git-->>ECA: Commits data
+
+ loop For each commit in PR/Push
+ ECA->>Cache: Check cached validation
+ activate Cache
+ Cache->>DB: Query if not in cache
+ DB-->>Cache: Return data
+ Cache-->>ECA: Return validation status
+ deactivate Cache
+
+ par Eclipse Foundation API Checks
+ ECA->>Projects: Validate project status
+ Projects-->>ECA: Project validation
+ and
+ ECA->>Users: Check ECA status
+ Users-->>ECA: User agreements
+ and
+ ECA->>Bots: Verify bot accounts
+ Bots-->>ECA: Bot validation
+ end
+ end
+
+ ECA->>DB: Store validation results
+
+ alt GitHub PR
+ ECA->>Git: Update PR status with combined results
+ ECA->>Git: Add review comments if needed
+ else GitLab Push
+ ECA->>Git: Update status for each commit
+ end
+
+ ECA-->>Git: Return validation result
+ deactivate ECA
+
+```
+
+The git-eca service acts as a central validation gateway for Git contributions to Eclipse Foundation projects. Here's how it works:
+
+1. **Contribution Event**:
+ - A developer submits a PR (GitHub) or push (GitLab)
+ - The Git provider sends a webhook event to git-eca
+
+2. **Initial Context Gathering**:
+ - git-eca fetches complete details about the contribution context
+ - For PRs: gets PR metadata
+ - For pushes: gets repository context
+ - Retrieves all commits involved in the change
+
+3. **Per-Commit Processing**:
+ - For each commit in the contribution:
+ * Checks cached results to avoid duplicate processing
+ * Validates against Eclipse Foundation systems in parallel:
+ - Projects API: Verifies project status and repository ownership
+ - Accounts API: Validates contributor agreements (ECA)
+ - Bots API: Verifies automated contribution accounts
+
+4. **Result Aggregation**:
+ - Combines validation results from all commits
+ - Updates status in the Git provider
+ - Adds explanatory comments if any validation fails
+
+5. **Response**:
+ - Returns final validation status to Git provider
+ - Contribution is either approved or blocked based on combined validation results
+
+The service ensures all contributions comply with Eclipse Foundation policies while maintaining a smooth developer experience through clear feedback and efficient validation processing.
\ No newline at end of file
--
GitLab
From 87409e142d5dd18466b9d66cb3bf79b05e6e15ad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jordi=20G=C3=B3mez?= <jordi.gomez@eclipse-foundation.org>
Date: Wed, 30 Apr 2025 10:14:17 +0200
Subject: [PATCH 2/2] docs: applying Martin's comments to be more accurate with
the flow
---
README.md | 119 +++++++++++++++++++++++-------------------------------
1 file changed, 51 insertions(+), 68 deletions(-)
diff --git a/README.md b/README.md
index 142636cc..62a4e756 100644
--- a/README.md
+++ b/README.md
@@ -155,91 +155,74 @@ The `Volatile` column denotes whether the property is subject to change once ini
## Current Picture
+### Main Flow
```mermaid
sequenceDiagram
- participant Git as Git Providers (GitHub/GitLab)
+ participant Git as Git Provider
participant ECA as Git ECA Rest API
participant Cache as Cache Layer
participant DB as Database
- participant Projects as Eclipse Projects API
- participant Users as Eclipse Accounts API
- participant Bots as Eclipse Bots API
- Git->>ECA: Send PR/Push event
- activate ECA
-
- alt GitHub PR
- ECA->>Git: Fetch PR details
- Git-->>ECA: PR data
- else GitLab Push
- ECA->>Git: Fetch repository details
- Git-->>ECA: Repository data
+ alt GitHub Webhook Event
+ Git->>ECA: Send webhook event with commits
+ activate ECA
+ ECA->>Git: Set commit status to pending
+ ECA->>Git: Fetch additional commit details
+ Git-->>ECA: Commit details
+ else GitLab Pre-receive Hook
+ Git->>ECA: Send commits for validation
+ activate ECA
end
- ECA->>Git: Fetch all commit details
- Git-->>ECA: Commits data
+ ECA->>Cache: Bulk lookup of commit validation status
+ activate Cache
+ Cache->>DB: Query for persisted validation results
+ DB-->>Cache: Return persisted data
+ Cache-->>ECA: Return validation status
+ deactivate Cache
- loop For each commit in PR/Push
- ECA->>Cache: Check cached validation
- activate Cache
- Cache->>DB: Query if not in cache
- DB-->>Cache: Return data
- Cache-->>ECA: Return validation status
- deactivate Cache
-
- par Eclipse Foundation API Checks
- ECA->>Projects: Validate project status
- Projects-->>ECA: Project validation
- and
- ECA->>Users: Check ECA status
- Users-->>ECA: User agreements
- and
- ECA->>Bots: Verify bot accounts
- Bots-->>ECA: Bot validation
- end
+ loop For each non-cached or failed commit
+ Note over ECA: See "Commit Validation Process" diagram
end
- ECA->>DB: Store validation results
-
- alt GitHub PR
- ECA->>Git: Update PR status with combined results
+ alt GitHub Webhook Event
+ ECA->>Git: Update PR status with results
ECA->>Git: Add review comments if needed
- else GitLab Push
- ECA->>Git: Update status for each commit
+ else GitLab Pre-receive Hook
+ alt Validation Failed
+ ECA-->>Git: Reject push with error details
+ else Validation Passed
+ ECA-->>Git: Allow push to proceed
+ end
end
- ECA-->>Git: Return validation result
deactivate ECA
-
```
-The git-eca service acts as a central validation gateway for Git contributions to Eclipse Foundation projects. Here's how it works:
-
-1. **Contribution Event**:
- - A developer submits a PR (GitHub) or push (GitLab)
- - The Git provider sends a webhook event to git-eca
-
-2. **Initial Context Gathering**:
- - git-eca fetches complete details about the contribution context
- - For PRs: gets PR metadata
- - For pushes: gets repository context
- - Retrieves all commits involved in the change
-
-3. **Per-Commit Processing**:
- - For each commit in the contribution:
- * Checks cached results to avoid duplicate processing
- * Validates against Eclipse Foundation systems in parallel:
- - Projects API: Verifies project status and repository ownership
- - Accounts API: Validates contributor agreements (ECA)
- - Bots API: Verifies automated contribution accounts
+### Commit Validation Process
+```mermaid
+sequenceDiagram
+ participant ECA as Git ECA Rest API
+ participant DB as Database
+ participant Projects as Eclipse Projects API
+ participant Users as Eclipse Accounts API
+ participant Bots as Eclipse Bots API
-4. **Result Aggregation**:
- - Combines validation results from all commits
- - Updates status in the Git provider
- - Adds explanatory comments if any validation fails
+ alt Not cached or needs revalidation
+ ECA->>Projects: Check if is project-managed
+ Projects-->>ECA: Project management status
-5. **Response**:
- - Returns final validation status to Git provider
- - Contribution is either approved or blocked based on combined validation results
+ par Account Validation
+ ECA->>Users: Validate commit author ECA
+ Users-->>ECA: Author agreement status
+ and
+ ECA->>Users: Validate commit committer ECA
+ Users-->>ECA: Committer agreement status
+ and
+ ECA->>Bots: Check if bot account
+ Bots-->>ECA: Bot validation status
+ end
-The service ensures all contributions comply with Eclipse Foundation policies while maintaining a smooth developer experience through clear feedback and efficient validation processing.
\ No newline at end of file
+ ECA->>DB: Store validation results
+ end
+```
\ No newline at end of file
--
GitLab