AWS Builder Center
OSS Quest: Turning a First Open-Source Contribution Into a Guided Journey

OSS Quest: Turning a First Open-Source Contribution Into a Guided Journey

OSS Quest is a gamified learning platform that guides beginners through their first open-source contribution. Across six interactive villages, learners understand Git and GitHub, practise the contribution workflow in a safe terminal, and use GitHub repository data with the Strands Agents SDK to discover a suitable real-world issue.

Make you Visible to AI
My first open-source contribution did not feel like a coding problem. It felt like a map with no signs.
I did not know where to begin, which repository was safe for a beginner, what "fork" and "clone" meant in practice, how to ask a maintainer for help, or whether an issue was actually suitable for someone at my level. Most guides explained the commands, but the intimidating part was the journey around those commands.
That is why I built OSS Quest: a gamified open-source contribution learning platform for people making their first contribution.
Instead of dropping a beginner into a huge codebase, OSS Quest turns the process into a world of six villages. Each village represents a stage of the contribution journey. NPCs explain the ideas in plain language, the player practices the workflow in a safe terminal, and the final chapters connect that learning to a real GitHub repository and issue.
A fantasy-style world map with six named learning areas, chapter markers, movement controls, and a quest progress panel.

The Problem I Wanted to Solve
Open source often assumes that a newcomer already understands the culture around the code.
A beginner has to learn several things at once:
  • what Git and GitHub are
  • how forks, clones, branches, commits, and pull requests fit together
  • how to read an unfamiliar repository
  • how to communicate with maintainers
  • how to identify a realistic first issue
  • how to recover when a command fails
Documentation is useful, but it can still leave a first-time contributor afraid of making a public mistake. OSS Quest creates a lower-pressure path. It teaches one concept at a time, gives the learner a reason to use it, and only then hands them off to a real project.
This is not meant to be a conventional game with open-ended entertainment as the main goal. The RPG layer is an interface for structured learning. Progress through the world mirrors progress toward a real contribution.
How the Journey Works
The overworld contains six connected learning areas:
  1. The Forge introduces Git and GitHub.
  1. The Old Copyworks explains forks and clones.
  1. The Reading Grove teaches learners how to explore an unfamiliar codebase.
  1. The Speaking Well covers issues, questions, and communication with maintainers.
  1. The Proving Grounds searches for a suitable real repository and beginner issue.
  1. The Gate of Merging walks through the contribution workflow, including cloning, branching, committing, pushing, and preparing a pull request.
The player moves with WASD or the arrow keys and enters a village near its marker. Inside, dialogue and small quests replace a wall of documentation with a sequence of actions.
The Proving Grounds village with an NPC dialogue asking the learner to scan a real repository.

The goal is not to hide real tools behind fantasy language. It is to give the learner enough context and confidence to use those tools correctly.
From a Real GitHub Issue to a Beginner Match
The matching flow starts with the learner's language and skill level. The local Express backend queries the GitHub REST API for recently updated open issues carrying the "good first issue" label. It then reads repository signals such as the presence of README and contributing files, recent activity, and issue metadata.
The project uses the Strands Agents SDK to ask an agent to assess three dimensions:
  • language fit
  • beginner friendliness
  • maintainer responsiveness
The result is shown as a match card, followed by a direct route to the repository and a guided contribution workflow.
A repository match card for ONEARMY/community-platform with language fit, beginner friendliness, and responsiveness bars, plus a visible note that agent scoring failed and default estimates are shown.

That screenshot also captures an important limitation honestly. The GitHub repository data was retrieved, but the Strands scoring call failed during this run. The app handled the failure by showing safe default estimates and labeling them clearly. I do not treat those displayed percentages as agent-generated results.
The fallback keeps the learning flow usable, but it is not the final behavior I want. My next step is to improve error reporting, validate the model response before parsing it, and make the difference between retrieved repository facts and generated assessment even clearer.
A Safe Place to Practise the Workflow
After a match, OSS Quest opens a simulated terminal lesson. It breaks the contribution flow into five steps so a learner can practise without worrying about damaging a project:
  1. clone the fork
  1. enter the repository
  1. create a branch
  1. commit the change
  1. push the branch to GitHub
The simulated terminal is intentionally guided. It does not pretend to replace a real shell or a maintainer's review. Its job is to build a mental model before the learner works in a real repository.
Architecture and AWS Connection
I built the frontend without a game engine. It uses vanilla JavaScript, HTML5 Canvas, and CSS. A custom renderer manages the overworld, village scenes, characters, NPCs, collisions, dialogue, quest state, and sprite animation.
The working demo uses a local Node.js and Express backend. That backend:
  • calls the read-only GitHub REST API
  • retrieves repository and issue metadata
  • invokes the Strands Agents SDK for issue assessment
  • returns the repository details and score response to the frontend
  • stores local progress state for the demo
The repository also contains an AWS serverless path rather than claiming that the recorded demo is already running in production on AWS. It includes:
  • an AWS SAM template
  • a Node.js AWS Lambda handler
  • an API event definition for the serverless endpoint
  • DynamoDB client code for progress storage
  • environment-based handling for the GitHub token
The demo itself runs locally. The AWS files are the deployment path I started for moving the matching and progress services from the local prototype to a managed serverless backend. I chose this shape because Lambda fits short matching and progress requests, API Gateway can expose those operations to the browser, and DynamoDB fits the small per-user progress record.
Strands Agents SDK is the agent layer in the working local backend. It receives issue data and a learner profile, requests structured JSON scores, and passes them back to the interface. When that agent call fails, the current code falls back to labeled estimates instead of blocking the full lesson.
What Fought Back
Building the visual world was harder than placing static images on a page.
The character and ambient assets had inconsistent dimensions and backgrounds. I built an AssetLoader and Canvas rendering path that could process them at runtime, calculate animation frame widths, and keep movement readable across the overworld and village scenes. Cats, campfires, characters, and NPCs all needed slightly different handling.
The second challenge was joining two very different systems: a responsive Canvas learning experience and live external repository data. The world has to remain understandable while a network request is running, an issue is being selected, and an agent response is being parsed.
The third challenge was graceful failure. A live agent or API can fail at exactly the moment a learner expects an answer. In the final recorded run, repository discovery returned a real project, while the agent scoring step fell back. That exposed an area that still needs work, but it also proved why visible status and fallback behavior matter.
What I Learned
The biggest lesson was that onboarding is not only about explaining commands. It is about reducing uncertainty.
A newcomer needs to know:
  • what to do next
  • why that step exists
  • what a safe result looks like
  • how the step connects to a real contribution
I also learned that gamification works best when every visual element carries part of the learning structure. The map is a syllabus. Villages are modules. NPC dialogue supplies context. The terminal turns explanation into rehearsal. The repository match is the bridge from the protected learning space to real open source.
What Comes Next
The next version of OSS Quest will focus on reliability and the real-world handoff:
  • make agent failures easier to diagnose and retry
  • deploy and test the serverless AWS path
  • replace remaining local progress storage with the DynamoDB-backed flow
  • show the exact matched issue and repository evidence more clearly
  • add stronger validation around generated score JSON
  • improve accessibility and keyboard guidance
  • expand the multilingual learning content
The long-term goal is simple: a learner should finish OSS Quest with more than a completed chapter. They should understand the workflow, have a real issue in front of them, and feel ready to make their first contribution.
Explore the public repository:  https://github.com/Tushar6809/Oss-quest 
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article