Skip to content

Latest commit

 

History

History
113 lines (84 loc) · 4.17 KB

CONTRIBUTING.md

File metadata and controls

113 lines (84 loc) · 4.17 KB

Contributing to Graph-Python-scripts

Thank you for your interest in contributing! This repository uses a community review system to validate graph analysis results.

Submitting Reviews

Reviews help ensure the accuracy and reliability of graph analysis results. There are two ways to submit reviews:

Method 1: In-Dashboard Review Form (Recommended for Quick Reviews)

  1. Visit the Dashboard

  2. Navigate to an Analysis

    • Click on any analysis tab (e.g., "Co-attendance Degree", "Field Degree")
    • Review the results displayed

  3. Submit a Review

    • Scroll to the bottom of the analysis tab to find the review form
    • Fill out the form:
      • Rating: Select "Correct", "Needs Review", or "Incorrect"
      • Comments: Provide your feedback, observations, or concerns (required)
      • Your Name (optional): Your name or identifier
      • Suggestions (optional): Include specific improvements, patches, or corrections
    • Click "Submit Review"
    • Optionally download the review as JSON using the "Download Review as JSON" button

  4. Reviews are stored locally in your browser and will appear in the Audit tab immediately.

Method 2: JSON File Submission (For Programmatic Submissions)

You can also submit reviews by committing JSON files to the repository:

  1. Create a Review JSON File

    • Download a review from the dashboard (uses the correct format)
    • Or create a JSON file with the following structure:
    {
  "id": "unique-review-id",
  "method": "coattendance",
  "rating": "correct",
  "comment": "Your review comment here",
  "reviewer": "Your Name",
  "suggestions": "Optional suggestions",
  "file": "docs/index.html",
  "timestamp": "2025-01-15T10:00:00.000Z"
}

  2. Submit the JSON File

    • Commit the JSON file to the /reviews/ directory in the repository
    • Push to the main branch

  3. Automatic Processing

    • A GitHub Action will automatically:
      • Validate the JSON structure
      • Create a GitHub Issue from your review
      • Move the processed file to /reviews/processed/

JSON File Requirements:

  • File must be valid JSON with .json extension
  • Must include required fields: method, rating, comment, timestamp
  • method must be one of: coattendance, field-degree, path-structure, centrality, clustering, components
  • rating must be one of: correct, needs-review, incorrect
  • comment cannot be empty

Note: Invalid JSON files will be skipped with error messages logged. Only successfully processed files are moved to /reviews/processed/.

What to Review

Focus on:

  • Accuracy: Do the results match your understanding of the data?
  • Completeness: Are important patterns or relationships captured?
  • Clarity: Are the visualizations and tables clear and interpretable?
  • Methodology: Are the analysis methods appropriate for the questions being answered?

Review Labels

When you submit a review, you should select one rating label:

  • correct - The analysis results appear accurate
  • needs-review - The analysis may have issues that require investigation
  • incorrect - The analysis results appear incorrect or misleading

Review Best Practices

  • Be Specific: Include details about what you observed or what concerns you
  • Be Constructive: If reporting issues, suggest how they might be addressed
  • Reference Data: If possible, cite specific examples from the data
  • Be Respectful: Maintain a respectful and collaborative tone

Viewing Review Statistics

Check the "Audit" tab in the dashboard to see:

  • Trust scores aggregated across all reviews
  • Distribution of ratings
  • All review comments from the community

Code Contributions

If you want to contribute code improvements:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request with a clear description

Questions?

  • Check REVIEWING.md for details about how the audit system works
  • Open an issue for questions or discussions