|
1 | | -# versioning |
2 | 1 |
|
3 | | -* how do we mange the varaints of the tasks |
| 2 | +## Task Variant Tracking |
| 3 | + |
| 4 | +TaskBeacon supports **task variant tracking** to promote transparency, reproducibility, and collaboration across the research community. Task variant tracking allows the community to build on shared paradigms while keeping modifications clear and organized. It encourages open science and makes experimental replication easier — without losing flexibility. |
| 5 | + |
| 6 | +**Why it matters**: There are countless modifications of popular cognitive tasks in circulation — different stimuli, reward types, modalities, or participant populations. |
| 7 | +Without proper tracking: |
| 8 | +- It becomes hard to understand what version was actually used. |
| 9 | +- Reproducibility is compromised. |
| 10 | +- Collaborative improvements or comparisons are inefficient. |
| 11 | + |
| 12 | +By explicitly documenting task variants, TaskBeacon ensures that users can trace the origin of a task, understand what changed, and reuse versions that best match their research needs. |
| 13 | + |
| 14 | +**How It Works**: Each task in TaskBeacon is hosted in its own GitHub repository. **Variants of a task are stored as Git branches**, with each variant accompanied by a `README.md` file at the root of that branch. |
| 15 | + |
| 16 | +An Example Structure looks like this: |
| 17 | +``` |
| 18 | +sst/ |
| 19 | +├── main/ |
| 20 | +│ └── README.md ← base version |
| 21 | +├── audio_sst/ |
| 22 | +│ └── README.md ← describes the audio-based SST |
| 23 | + |
| 24 | +(not accepted as variant) |
| 25 | +├── fast_response_version/ |
| 26 | +│ └── README.md ← minor timing changes |
| 27 | +``` |
| 28 | + |
| 29 | +### What Counts as a Variant? |
| 30 | + |
| 31 | +Not all changes are meaningful enough to count as a separate variant. Here’s a general guideline: |
| 32 | + |
| 33 | +✅ Counted as a variant: |
| 34 | +- Changing the type of feedback or stimuli (e.g., replacing visual stop signals with audio in SST;Switching from monetary to social rewards in MID) |
| 35 | +- Adding or modifying experimental conditions in a non-trivial way |
| 36 | + |
| 37 | +❌ Not counted as a variant: |
| 38 | +- Minor adjustments to trial timing |
| 39 | +- Changing font sizes or button positions |
| 40 | +- Cosmetic or layout-only changes |
| 41 | + |
| 42 | +Variant contributions are reviewed and approved by TaskBeacon's administrative team to ensure they meet the standard for meaningful differentiation. |
| 43 | + |
| 44 | + |
| 45 | + |
| 46 | +### Contribute a Variant |
| 47 | + |
| 48 | +To contribute a new task variant: |
| 49 | + |
| 50 | +1. **Fork** the GitHub repository of the base task. |
| 51 | +2. **Create a new branch** for your variant (e.g., `social_reward_MID`). |
| 52 | +3. **Modify the task code** as needed. |
| 53 | +4. **Add a `README.md`** to the root of your branch. This file should: |
| 54 | + - Describe the purpose of the variant. |
| 55 | + - Explain how it differs from the `main` branch or original task. |
| 56 | + - Include your name and affiliation (optional but encouraged). |
| 57 | +5. **Submit a pull request or contact the admin team** to get your branch reviewed and published on TaskBeacon. |
| 58 | + |
| 59 | + |
| 60 | +### Contribute a New Task |
| 61 | + |
| 62 | +If you want to contribute an entirely **new task** that doesn’t exist in TaskBeacon yet: |
| 63 | + |
| 64 | +1. **Create a new public GitHub repository** under your own GitHub account or organization. |
| 65 | +2. Structure the task according to the [TAPS format](https://taskbeacon.github.io/taps/). |
| 66 | +3. Include a `README.md` with: |
| 67 | + - A brief overview of the task |
| 68 | + - Instructions for running it |
| 69 | + - Required dependencies or setup instructions |
| 70 | +4. When ready, **submit the task** to TaskBeacon by opening an issue or contacting the admin team. |
| 71 | +5. The TaskBeacon team will **review and fork** your repository under the official TaskBeacon GitHub organization for indexing. |
| 72 | + |
| 73 | +This workflow ensures that tasks are standardized, documented, and easily discoverable through the TaskBeacon platform. |
| 74 | + |
| 75 | + |
| 76 | +### Behind the Scenes: How Variants Get Indexed |
| 77 | + |
| 78 | +TaskBeacon uses a script (`fetch_all_task_variants.py`) to automatically scan task repositories, detect branches, and build a browsable index for the website. |
| 79 | + |
| 80 | +**Here's how it works**: |
| 81 | + |
| 82 | +1. The script queries GitHub’s API to retrieve all public repositories under the TaskBeacon organization. |
| 83 | +2. For each repository (excluding core tools like `psyflow` or documentation repos), it: |
| 84 | + - Lists all branches |
| 85 | + - Tries to download the `README.md` file from each branch |
| 86 | + - If found, saves it locally and registers the branch as a valid variant |
| 87 | +3. For each task with one or more variants: |
| 88 | + - A task-specific index file is created listing all branches |
| 89 | + - This gets compiled into the global `Task Library` page on the TaskBeacon site |
| 90 | + |
| 91 | +### Key Logic (Simplified) |
| 92 | + |
| 93 | +```python |
| 94 | +# For each repo |
| 95 | +branches = fetch_branches(repo) |
| 96 | +for branch in branches: |
| 97 | + readme_url = f"https://raw.githubusercontent.com/TaskBeacon/{repo}/{branch}/README.md" |
| 98 | + if download(readme_url): |
| 99 | + # Register the branch as a variant |
| 100 | + add_to_index(branch) |
| 101 | +``` |
| 102 | + |
| 103 | +This automated process ensures the Task Library always stays up to date with newly submitted variants. |
| 104 | + |
| 105 | + |
| 106 | +### Browse Tasks and their Variants |
| 107 | + |
| 108 | +You can explore all registered task variants in the [Task Library](https://taskbeacon.github.io/task_index/). Each entry includes a short description and links to the associated branch on GitHub. |
| 109 | + |
| 110 | + |
| 111 | + |
4 | 112 |
|
5 | | -* how to upload your tasks |
|
0 commit comments