Skip to content

PR_SUBMISSION_IMPLEMENTATION.md

Latest commit

 

History

History
196 lines (159 loc) · 7.2 KB

PR_SUBMISSION_IMPLEMENTATION.md

File metadata and controls

196 lines (159 loc) · 7.2 KB
Raw

GitHub Pull Request Submission Feature - Implementation Summary

This document summarizes the implementation of the GitHub Pull Request submission feature for the Model Openness Tool.

Overview

Users can now submit their evaluated models directly to the MOT GitHub repository via an automated Pull Request workflow. The feature integrates with the existing GitHub OAuth authentication system.

Files Created

1. web/modules/mof/js/submit_pr.js

  • JavaScript file handling PR submission button clicks
  • Makes AJAX requests to the PR submission endpoint
  • Displays success/error messages to users
  • Handles loading states and user feedback

Files Modified

1. web/modules/mof/src/Services/GitHubPullRequestManager.php

Changes:

  • Complete rewrite to use authenticated user's OAuth token
  • Retrieves token from social_auth entity storage
  • Implements methods:
    • getAccessToken(): Retrieves GitHub OAuth token
    • getGitHubUsername(): Gets authenticated user's GitHub username
    • isAuthenticated(): Checks if user has valid GitHub authentication
    • request(): Makes authenticated GitHub API requests
    • ensureFork(): Creates fork if it doesn't exist
    • createBranch(): Creates a new branch in the fork
    • commitFile(): Commits YAML file to the branch
    • createPullRequest(): Creates PR from fork to upstream

2. web/modules/mof/mof.services.yml

Changes:

  • Added github_pr_manager service registration
  • Dependencies: @http_client, @entity_type.manager, @current_user, @logger.channel.mot

3. web/modules/mof/src/Controller/ModelController.php

Changes:

  • Fixed typo: RendererInterfce → RendererInterface
  • Added imports for ModelSerializerInterface, GitHubPullRequestManager, JsonResponse
  • Added properties: $modelSerializer, $githubPrManager
  • Updated create() method to inject new services
  • Fixed bugs in yaml() and json() methods (missing $response initialization)
  • Added submitPullRequest() method:
    • Checks GitHub authentication
    • Validates session data
    • Generates YAML content
    • Creates fork, branch, commits file, and creates PR
    • Returns JSON response with success/error status
  • Added generatePrBody() helper method:
    • Generates PR description with model details
    • Includes MOF classification status

4. web/modules/mof/mof.routing.yml

Changes:

  • Added mof.model.evaluate_form.submit_pr route
  • Path: /model/evaluate/submit-pr
  • Controller: ModelController::submitPullRequest
  • Access: Public (authentication checked in controller)
  • No cache option enabled

5. web/modules/mof/src/ModelViewBuilder.php

Changes:

  • Added PR submission button to evaluation results
  • For authenticated users: Shows "Submit Pull Request" button with JavaScript handler
  • For unauthenticated users: Shows "Login with GitHub to Submit PR" link
  • Button includes data attribute with PR submission URL

6. web/modules/mof/mof.libraries.yml

Changes:

  • Added JavaScript file to model-evaluation library
  • Added dependencies: core/drupal, core/drupalSettings

7. README.md

Changes:

  • Updated "Evaluating a Model" section
  • Added information about PR submission feature
  • Added new "Submitting Your Model via Pull Request" section
  • Documented both automatic and manual submission workflows
  • Explained GitHub authentication requirement

Documentation Created

1. TESTING_PR_FEATURE.md

  • Comprehensive testing guide
  • Test scenarios for different user states
  • Verification checklist
  • Common issues and solutions
  • Database verification queries
  • Log monitoring instructions

2. PR_SUBMISSION_IMPLEMENTATION.md (this file)

  • Implementation summary
  • Files created and modified
  • Architecture overview
  • Workflow description

Architecture

Authentication Flow

User → Evaluate Model → Results Page
  ↓
Not Authenticated? → Login with GitHub → Return to Evaluation
  ↓
Authenticated → Submit PR Button → AJAX Request
  ↓
Controller checks auth → Retrieves OAuth token → GitHub API calls
  ↓
Success → Display PR link | Error → Display error message

GitHub API Workflow

1. Check authentication (OAuth token from social_auth entity)
2. Get GitHub username from social_auth additional_data
3. Ensure fork exists (create if needed)
4. Create unique branch (model-{name}-{timestamp})
5. Commit YAML file to models/ directory
6. Create pull request from fork to lfai/model_openness_tool
7. Return PR URL to user

Key Features

  1. Seamless Integration: Uses existing GitHub OAuth authentication
  2. User-Friendly: Single-click PR submission for authenticated users
  3. Automatic Fork Management: Creates fork if user doesn't have one
  4. Unique Branch Names: Timestamp-based to avoid conflicts
  5. Comprehensive Error Handling: Clear error messages for all failure scenarios
  6. Security: OAuth tokens encrypted in database, used only for GitHub API
  7. Feedback: Real-time status updates via JavaScript
  8. Fallback: Manual download option still available

Security Considerations

  1. Token Storage: OAuth tokens encrypted in social_auth entity table
  2. Token Access: Only accessible to authenticated user who owns it
  3. API Scope: Requires repo scope for PR creation
  4. Rate Limiting: GitHub API rate limits apply (5000 req/hour for authenticated users)
  5. CSRF Protection: Drupal's built-in CSRF protection on routes
  6. Input Validation: Model data validated before YAML generation

Dependencies

  • Drupal Core: 10.x
  • social_auth_github: ^4.0 (already installed)
  • GuzzleHTTP: For GitHub API requests
  • Drupal Session: For storing model evaluation data

Configuration Required

  1. GitHub OAuth App: Must be configured in social_auth_github settings
  2. OAuth Scopes: Must include repo scope for PR creation
  3. Repository: Targets lfai/model_openness_tool repository

Testing Requirements

Before deploying to production:

  1. Test with unauthenticated users
  2. Test with authenticated users (first-time and existing fork)
  3. Test error scenarios (invalid token, API failures)
  4. Verify PR content and formatting
  5. Check rate limiting behavior
  6. Test on different browsers
  7. Verify mobile responsiveness

Future Enhancements

Potential improvements for future versions:

  1. PR Status Tracking: Track PR status and notify users of updates
  2. Draft PRs: Option to create draft PRs for review
  3. Batch Submissions: Submit multiple models at once
  4. PR Templates: Customizable PR body templates
  5. Conflict Resolution: Handle cases where model file already exists
  6. Retry Logic: Automatic retry for transient GitHub API failures
  7. Progress Indicator: Show detailed progress during fork/branch/commit steps

Maintenance Notes

  • Monitor GitHub API rate limits in production
  • Keep social_auth_github module updated
  • Review GitHub API changes for compatibility
  • Monitor error logs for common failure patterns
  • Consider implementing caching for fork existence checks

Support

For issues or questions:

  • Check TESTING_PR_FEATURE.md for common problems
  • Review Drupal watchdog logs: drush watchdog:show --type=mof
  • Check browser console for JavaScript errors
  • Verify GitHub OAuth configuration in Drupal admin