Repository navigation
develop
Note
Please read this page carefully and return to it regularly to ensure you're following our guidelines.
Hello developer! We're excited to evolve Wordplay with you.
Before starting, please read the contributor and complete every step.
Then, complete the local development setup documentation to configure your environment.
There are many things you need to know before you can contribute to the platform:
You'll also need to learn how Wordplay is architected. To do that, read ARCHITECTURE.md, which overviews all the significant components in the Wordplay implementation—and critical dependencies. If you're working on a specific part of Wordplay's implementation, just reading the relevant subsections is okay.
Finally, you'll want to learn the GitHub Flow branching strategy since that is how we organize our work. The gist is that we organize our work around issues. We create a branch for the issue we're working on, and when the branch is ready for production, you'll submit a pull request to merge the branch into our main branch for release. (We'll cover this in more detail below.)
Learning all of the above takes time, and that's okay! You've got a whole community of contributors who are here to help. Consider everyone a resource, and use Discord to ask questions to accelerate your learning.
Once you feel like you've learned the basics — you don't have to have mastered everything — you'll want to set up your VS Code work environment.
When developing, you should have at least four terminals open, each running a specific command. Each of these keeps running and re-checks your work every time you save a file, so you find out about a mistake seconds after you make it rather than hours later.
-
npm run dev. This launches Vite, a tool for running Wordplay locally. It prints a URL likehttp://localhost:5173to open in your browser, and changes you make to code appear there immediately. -
npm run check. This shows you any TypeScript or Svelte errors you've introduced anywhere in the project, not just in the file you have open in VS Code. It also treats accessibility warnings as errors, so it will stop you from shipping an inaccessible interface. Never commit code with any errors. (If you just want to check once and stop, rather than watch, usenpm run check:now.) -
npm test. This runs all of our unit tests, so you know when you've broken something the tests cover. (You can still break things our tests don't cover, so don't rely on these to thoroughly verify your code!) -
npm run locales. This checks the project against our localization rules. You will see warnings about unwritten strings in other locales; that just means the localization team has work to do, and it isn't your fault. Errors, though, you need to fix. If you change anything about localization types or strings, runnpm run create-schemasto update the schemas to reflect the changes.
Wordplay has a number of conventions that aren't obvious from reading the code, and breaking one is the most common reason a pull request needs another round of review. Four documents in the repository capture them. You don't need to memorize them, but you should know they exist and skim the parts relevant to what you're changing:
- CLAUDE.md is the project's conventions document: how immutability works, how localized text must be rendered, how screen reader announcements are made, how accessibility is enforced, and which parts of the codebase are generated rather than written by hand. Read the section that covers whatever you're touching. (It's written to instruct AI coding assistants, but everything in it applies to people too.)
- ARCHITECTURE.md explains how Wordplay is put together, component by component.
- LANGUAGE.md is the specification of the Wordplay programming language itself. If you change anything about how the language parses or evaluates, this has to change with it.
- CONTRIBUTING.md covers code formatting, which is automated — you shouldn't have to think about it, but our automated checks will reject a pull request that isn't formatted.
One convention deserves calling out here, because it's easy to violate by accident: several parts of the project are generated by a script, not written by hand, including the fonts, the logo and icons, the instrument recordings, the emoji data, and the VS Code theme. Editing one of those files directly will look like it works and then fail our tests, because a test compares the committed file against what the generator produces. Each has a command that regenerates it (npm run fonts-fix, npm run logo-fix, npm run instruments-build, npm run emoji-update, npm run vscode-theme), and CLAUDE.md explains when to run them.
Review available issues. Look for issues with these labels:
-
buildable: This label indicates that someone has done approved design work and is ready to develop. Some issues may unintentionally lack this tag; if you spot one, tag Amy in a comment to see if it is buildable. -
starter: This label indicates that the issue should be manageable relative to other topics. Problems for issues without assignees. If you find an issue cited that does have assignees, you can find them in Discord and ask if you can collaborate with them.
Important
If an issue is labeled needs design, it is not ready to build. Find a designer, or act as the designer, and get design approval before implementing anything.
Once you've found an issue, comment on it, tagging maintainer, requesting to be assigned. In your comment, include your plans so people know that you've chosen it. If the maintainer approves, they will assign you and you can start working.
Examine the issue text. Does the issue need elaboration, minimal reproduction steps, or design work? What do you need to learn about Wordplay's implementation to work on this? Tag a maintainer for guidance on where to look in the implementation rather than trying to understand everything yourself. They can give you a list of the relevant files and explain how they work.
Note
It's important to fully understand how everything is built before you start writing code. This is the only way to ensure your design is consistent with the existing architecture.
Follow the pull request instructions to prepare to work on the issue.
If there is no automated test that verifies the defect is repaired, or you're adding a new feature, attempt to write at least one unit or end to end test to help you track whether your code is working. You may need to write multiple to express its requirements if it's a new feature. See verification for guidance on writing tests.
Fix the defect or build the feature. Talk to everyone who might have a stake in the decision, including maintainers and other contributors, and make sure the design and implementation decisions you're making align with the project's existing patterns. If there is a designer who has worked on it and is still in the community, find them and collaborate with them to ensure your implementation meets their specifications.
If you feel you've made progress as you work, make a commitment that describes your progress. It's okay to have multiple commits as long as the last one explicitly references the issue you worked on so that GitHub automatically closes the issue when your fix is merged. The main branch is likely to change as you work.
Ensure you regularly pull updates into your fork, following the synchronization guidelines.
Some issues involve adding or modifying localization strings. If that applies to your issue, localize guide so that you properly mark strings in other locales as outdated or unwritten.
If your change is something a creator would notice — a new feature, a changed interface, a fixed bug they'd have run into — add a line describing it to CHANGELOG.md, written plainly enough that a middle schooler would understand it. Follow the style of the entries already there. Changes nobody would notice, like refactoring or new tests, don't need one.
Ensure your final commit has Fixed #[issue number], so GitHub will automatically close the issue when it is merged into main.
When you believe your work is done, submit your pull request, requesting your fork's branch be merged into the Wordplay main branch. Write a detailed explanation of the issue, the work you did, and any issues or decisions you had to make that the reviewer might need to consider. The reviewer may return feedback for you to address before your work is merged to main. This includes automated feedback, such as tests that have failed. You should expect to iterate several times before it's approved.
Once your work is done, we'll schedule it for the next weekly release to production.
Once you're done, pick another issue to work on!
Do you find something confusing on this page? Submit a workflow issue, so we can improve it! Every contribution counts.