Skip to content

Design PR workflow with contributor friction for data changes #23

Closed

Description

@neuromechanist

Summary

Design and implement a PR workflow for dataset changes that distinguishes between metadata-only changes (easy) and data changes (requires contributor status).

Background

Currently, users can clone a dataset and potentially push data changes without going through proper contributor verification. We need to:

  1. Make metadata PRs easy for anyone
  2. Create friction for data changes that requires contributor status first

Current Workflow

Need to explore and document:

  • How users currently submit changes
  • What DataLad/git-annex operations are involved
  • How data vs metadata is distinguished
  • Where staging → final S3 copy occurs

Proposed Workflow

For Metadata-Only Changes

  1. User forks or creates branch
  2. Makes changes to JSON/TSV files (stored in git proper)
  3. Opens PR
  4. Review and merge (straightforward)

For Data Changes

  1. User must first request contributor access (nemar dataset request-access <id>)
  2. Wait for approval (automatic for public datasets, manual for private)
  3. Once approved, can create branch and push data changes
  4. Data goes to staging S3 during PR
  5. On merge, staging → final S3 copy (via GitHub Actions)

Key Technical Considerations

Detection Logic

Metadata files: *.json, *.tsv, *.txt, README*, CHANGES*, LICENSE*
Data files: *.edf, *.bdf, *.set, *.fdt, *.vhdr, *.vmrk, *.eeg, (and largerthan threshold)

git-annex largefiles config

git annex config --set annex.largefiles 'include=*.edf or include=*.bdf or largerthan=100kb'

Validated Workflow Reference

See .context/validated_workflows.md for tested patterns:

  • Git-annex staging → final (use git annex copy --from --to)
  • GitHub Actions S3 copy on PR merge
  • Branch protection with enforce_admins=true

Implementation Tasks

  1. Document current workflow in detail
  2. Design change detection (metadata vs data)
  3. Implement pre-push hook or CLI check
  4. Add contributor verification step
  5. Update upload workflow to check contributor status
  6. Add helpful error messages guiding users

UX Goals

  • Clear error messages explaining why data changes require contributor status
  • Easy path for metadata contributors (no extra friction)
  • Transparent process for becoming a contributor
  • Prevent accidental large data uploads without proper access

Related

Activity

  1. added
    P2Normal priority - standard features and improvements
    featureNew feature or enhancement
    cliCLI related
    backendBackend/API related
    on Jun 18, 2026
  2. neuromechanist commented on Sep 3, 2026

    @neuromechanist
    ContributorAuthor

    Closing as decided. ADR 0001 (dataset changes go through pull requests) settled the governance model: review is gated on publish state rather than uniform contributor friction. The supporting pieces exist on dev: the collaborator request and approve flow in backend/src/routes/datasets/collaborators.ts, the single-source annex policy module (ADR 0031), and the staged-S3 then copy-on-merge PR workflow documented in .context/validated_workflows.md.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Normal priority - standard features and improvementsbackendBackend/API relatedcliCLI relatedfeatureNew feature or enhancement

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions