VERIFICATION.md
6,261 bytes
| 1 | # VERIFICATION.md — profileShare |
|---|---|
| 2 | |
| 3 | This document describes what "done" looks like for **profileShare** and how a coding agent should verify it. It is based only on the specification interview. Where the developer explicitly left a decision open, this is noted rather than assumed. |
| 4 | |
| 5 | ## Purpose |
| 6 | |
| 7 | profileShare lets a developer share a read-only overview of selected GitHub projects (including private ones) via a link, without making repositories public or adding viewers as collaborators. Viewers are primarily potential hiring managers. The link works for a limited time period, then expires. |
| 8 | |
| 9 | The core goal, restated by the developer: **"an overview of my code."** Nothing more complex. |
| 10 | |
| 11 | --- |
| 12 | |
| 13 | ## Definition of Done |
| 14 | |
| 15 | The project is done when all of the following behaviors hold. |
| 16 | |
| 17 | ### 1. Connecting to GitHub and selecting repositories |
| 18 | - The owner can authenticate with their GitHub account and grant access. |
| 19 | - Access is granted **only to the repositories the owner points to**, not to all repositories. [S19] |
| 20 | - The owner sees their repositories and can click to select which ones to share. [S9] |
| 21 | |
| 22 | ### 2. Creating a share link |
| 23 | - The owner selects specific repositories and generates a **simple URL** to share. [S9] |
| 24 | - The owner can set a **time period** for how long the link is valid (e.g. 7 days), and this period is customizable. [S9] |
| 25 | - The shared content is a **snapshot** taken at the moment the link is created — it does not update as the source repositories change. [S15] |
| 26 | |
| 27 | ### 3. Viewing a shared link (no account required) |
| 28 | - A viewer can open the link **without needing a GitHub account**. [S5] |
| 29 | - **Anyone with the link** can open it while it is valid; there is no per-person restriction, and forwarding the link is acceptable. [S23] |
| 30 | - The landing page is the owner's **profile page**. [S39] |
| 31 | |
| 32 | ### 4. Profile page contents |
| 33 | The profile page shows GitHub-style basic profile information and the list of selected projects. Supported items mentioned: name, photo, short bio, and the list of projects; profile activity is also desirable. [S12][S3] |
| 34 | - From the profile page, the viewer clicks a repository to open it. [S39] |
| 35 | |
| 36 | ### 5. Inside a project |
| 37 | - The viewer can browse the project's **files**, opening a file by name to read the code on screen. [S44] |
| 38 | - Folders (including nested folders) can be opened to find files. [S44][S45] |
| 39 | - The viewer can see the project's **commit history**: a list of what changed and when. [S42] |
| 40 | - If feasible, a commit should be **clickable to show which lines changed**. [S43] |
| 41 | |
| 42 | ### 6. Navigation |
| 43 | - A **button at the top** returns the viewer to the profile page. [S47] |
| 44 | - The viewer can step back up through nested folders and back out of a project. [S48][S38] |
| 45 | |
| 46 | ### 7. Expiration |
| 47 | - When a link is opened after its time period has ended, the viewer sees a simple message that **the URL is expired**. [S21] |
| 48 | |
| 49 | --- |
| 50 | |
| 51 | ## Explicitly Out of Scope |
| 52 | |
| 53 | Do **not** implement these: |
| 54 | - Comments. [S31] |
| 55 | - Downloading code. [S31] |
| 56 | - Editing by the viewer. [S32] |
| 57 | - A full clone of all GitHub functionality — only an overview. [S32][S33] |
| 58 | - Per-recipient access control / preventing link forwarding. [S23] |
| 59 | - Live/continuously-updating content (snapshot only). [S15] |
| 60 | |
| 61 | --- |
| 62 | |
| 63 | ## Open / Undecided Items (do not treat as requirements) |
| 64 | |
| 65 | - Whether the tool supports **only the owner** or **multiple sign-up users**. [S7] |
| 66 | - Whether stored snapshots are **deleted on expiry** or retained. [S26][S27] |
| 67 | - Size, link-count, or performance limits — developer only said it should "work normally." [S25] |
| 68 | - **Mobile support** was not requested; viewing is oriented to a computer. [S28][S29] |
| 69 | |
| 70 | --- |
| 71 | |
| 72 | ## How to Verify |
| 73 | |
| 74 | Since automated commands are not specified in the interview, verification is primarily behavioral. A coding agent should provide runnable build/start commands and then confirm the behaviors below. |
| 75 | |
| 76 | ### Build / run |
| 77 | - Provide and run the project's standard install and start commands (e.g. install dependencies, start the server). |
| 78 | - Confirm the app launches without errors and the owner can reach the GitHub authentication flow. |
| 79 | |
| 80 | ### Manual acceptance walkthrough (owner's own check) [S34][S35][S36][S37] |
| 81 | The developer's own acceptance test is to **open the generated link himself** and confirm: |
| 82 | 1. **All the projects he selected appear** — no more, no less. [S37] |
| 83 | 2. **All commits appear** for those projects. [S37] |
| 84 | |
| 85 | Extend this into the full check: |
| 86 | |
| 87 | 1. **Repo selection & access scope** |
| 88 | - Authenticate with GitHub. |
| 89 | - Confirm only the pointed-to repositories are accessed, not all repos. [S19] |
| 90 | - Select specific repositories and generate a link. |
| 91 | |
| 92 | 2. **Link generation** |
| 93 | - Confirm a simple shareable URL is produced. |
| 94 | - Confirm a customizable expiration period can be set. [S9] |
| 95 | |
| 96 | 3. **Snapshot behavior** |
| 97 | - After creating a link, change the source repository. |
| 98 | - Reopen the link and confirm the page still shows the original snapshot, not the change. [S15] |
| 99 | |
| 100 | 4. **Viewer experience (no login)** |
| 101 | - Open the link in a context without a GitHub session/account and confirm it loads. [S5] |
| 102 | - Confirm the profile page shows at least name, photo, bio, and the selected project list. [S12] |
| 103 | |
| 104 | 5. **Navigation into projects** |
| 105 | - From the profile, click a repository and confirm you enter it. [S39] |
| 106 | - Open files (including files inside nested folders) and read code on screen. [S44][S45] |
| 107 | - View the commit list (what changed and when). [S42] |
| 108 | - If implemented, click a commit to view changed lines. [S43] |
| 109 | - Use the top button to return to the profile. [S47] |
| 110 | - Step back up through nested folders / out of a project. [S48] |
| 111 | |
| 112 | 6. **Expiration** |
| 113 | - Open (or simulate opening) a link after its period ends. |
| 114 | - Confirm a simple "URL is expired" message is shown and content is not served. [S21] |
| 115 | |
| 116 | 7. **Out-of-scope confirmation** |
| 117 | - Confirm there is no comment feature, no download option, and no way for the viewer to edit content. [S31][S32] |
| 118 | |
| 119 | ### Pass criteria |
| 120 | The build succeeds and starts; the owner can connect GitHub, select specific repos, generate a time-limited link showing a snapshot; a viewer without an account can browse the profile, projects, files (including nested folders), and commits, and navigate back to the profile; and an expired link shows the expired message. Comments, downloads, and editing are absent. |