SPEC.md
4,635 bytes
| 1 | # SPEC.md — profileShare |
|---|---|
| 2 | |
| 3 | ## Goal |
| 4 | |
| 5 | profileShare is a tool for privately sharing selected GitHub repositories and profile information via a shareable link, without adding viewers as collaborators [S1]. The primary aim is to give people an overview of the developer's work without making the underlying GitHub repositories fully public to the whole world [S13][S23][S31][S33]. Access via the link is time-limited [S1][S9]. |
| 6 | |
| 7 | ## Users |
| 8 | |
| 9 | - **Link creators:** Initially the developer sharing their own work; possibly extendable to other people who want to share their own profiles (undecided) [S6][S7]. |
| 10 | - **Viewers:** Mainly people who might hire the developer; they do not need a GitHub account of their own to view the work [S4][S5]. |
| 11 | |
| 12 | ## User stories |
| 13 | |
| 14 | - As a creator, I want to select specific repositories from my account and generate a simple shareable URL, so I can send it to people without making everything public [S8][S9]. |
| 15 | - As a creator, I want the link to expire after a customizable time period (e.g. seven days), so people cannot view it indefinitely [S1][S9]. |
| 16 | - As a viewer, I want to open the link and see the creator's profile and selected projects, including code and commit history, so I can get an overview of their work [S3][S11]. |
| 17 | - As a creator, I want to verify a link myself before sharing it with a hiring person, so I can confirm the right projects and commits appear [S34][S35][S37]. |
| 18 | |
| 19 | ## Functional requirements |
| 20 | |
| 21 | - FR-001: The system shall allow a creator to view their GitHub repositories and select which ones to share [S9][S17]. |
| 22 | - FR-002: The system shall generate a shareable profile page and a simple URL for the selected repositories and profile information [S9]. |
| 23 | - FR-003: The shared link shall have a time period after which it expires, with a customizable duration (e.g. seven days) [S1][S9]. |
| 24 | - FR-004: The shared page shall present a snapshot of the code and profile taken at the moment the link is created, rather than always reflecting the latest changes [S14][S15]. |
| 25 | - FR-005: The system shall pull the creator's projects and code from their GitHub account [S16][S17]. |
| 26 | - FR-006: The system shall request access only to the repositories the creator chooses to share, not all repositories [S18][S19]. |
| 27 | - FR-007: When a link is opened after it has expired, the viewer shall be shown a message that the URL is expired [S20][S21]. |
| 28 | - FR-008: The shared page shall display the basic profile and repository information found on GitHub/GitLab, including projects, code, and commit history [S11][S12][S13]. |
| 29 | - FR-009: The main page shall show the creator's profile, from which the viewer can click into the shared repositories [S38][S39]. |
| 30 | - FR-010: The viewer shall be able to open a project and browse its files, including navigating into nested folders, and click a file to read its code on screen [S44][S45]. |
| 31 | - FR-011: The viewer shall be able to see the commit history within a project as a list of changes and dates [S37][S42]. |
| 32 | - FR-012: Commits should be clickable to show which lines of code changed, if feasible [S43]. |
| 33 | - FR-013: A button at the top of the page shall let the viewer return to the main profile page [S47]. |
| 34 | - FR-014: Anyone who has the link shall be able to open it while it is valid; no restriction on forwarding is required [S22][S23]. |
| 35 | |
| 36 | ## Edge cases |
| 37 | |
| 38 | - A viewer opening the link after expiry sees a simple "the URL that you have opened is expired" message [S20][S21]. |
| 39 | - A link forwarded to an unintended person will still open while valid; this is acceptable because the code contains no secrets and limited exposure is fine [S22][S23]. |
| 40 | |
| 41 | ## Out of scope |
| 42 | |
| 43 | - Making repositories fully public to the whole world [S13][S31]. |
| 44 | - Comments from viewers [S30][S31][S32]. |
| 45 | - Downloading the code [S30][S31]. |
| 46 | - Viewers editing anything [S32]. |
| 47 | - Being a full copy of everything GitHub does [S32][S33]. |
| 48 | - Team-oriented use rather than a single person's overview [S32][S33]. |
| 49 | - Mobile/phone optimization; intended for viewing on a computer [S28][S29]. |
| 50 | |
| 51 | ## Assumptions |
| 52 | |
| 53 | - Creators authenticate with and grant access to their GitHub account to import selected projects [S16][S18]. |
| 54 | - The tool need only "work normally"; no specific limits were defined for project size, number of concurrent links, or page load speed [S24][S25]. |
| 55 | - The retention behavior of the stored snapshot after expiry is left to the implementer to choose the best solution [S26][S27]. |
| 56 | - Detailed in-project navigation layout (e.g. file list vs. commit list arrangement, stepping up folder levels) is left to the implementer [S40][S41][S48]. |
| 57 | - Whether the tool supports only the developer or multiple sign-up users is undecided [S6][S7]. |