-
Notifications
You must be signed in to change notification settings - Fork 44
develop
Note
Read this page carefully and return to it regularly to ensure you're following our guidelines.
Hello developer! If you're reading this, it's because you want to help fix bugs, build new features, and make Wordplay the best Wordplay it can be. We're excited to collaborate with you!
Before starting, make sure you've read the contributor in full, and completed every step.
Then, run the local development setup documentation to configure your environment.
There are many things you need to know before you can contribute to the platform:
Use the learn links above to make sure you know the key ideas behind each of those languages and technologies.
Additionally, you'll need to learn how Wordplay is architected. To do that, read ARCHITECTURE.md, which overviews all of the major components in the Wordplay implementation. and key dependencies. If you're working in a specific part of Wordplay's implementation, it's okay to just read the subsections that are relevant.
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:
-
npm run dev. This launches Vite, a tool for running Wordplay locally, and having changes you make to code reflected immediately in your browser. -
npm run check. This shows you any TypeScript or Svelte errors you've introduced in code globally (not just in the editor in VS Code). Never commit code with any errors. -
npm run test. This runs vitest, running all of our unit tests on our code. This ensures you know when you've broken something that our tests cover. (You can still break things our tests don't cover, so don't rely on these to fully verify your code!) -
npm run locales. This checks code against our localization rules. You will see warnings about unwritten strings in other locales; that just means the localization team has some work to do. You want to look for other errors. - If you're modifying the localization types by adding or changing strings, run
npm run schemas.
Review available issues, searching for the ones you want to work on. There are some issue labels you can filter on to find possible issues:
-
buildable: This label indicates that someone has done design work that has been approved, and so it is ready to develop. There may be some issues that are unintentionally missing this tag; if you spot one, tag Amy in a comment to see if it is buildable. -
starter: This label indicates that we believe the issue should be easy, at least relative to other issues.
You might also want to look for issues that have no assignee. If you find an issue you're excited about that does have assignees, find them in Discord and ask if you can collaborate with them.
Important
If an issue is labeled needs design, it's not ready to build, so if you want to work on it, you should find a designer to collaborate with, or act as its designer
Once you've found an issue, comment on the issue, tagging a maintainer to request being assigned, and so everyone knows that you're the point of contact for it. In your comment, include your plans, so people know that you've chosen it.
Review the current behavior and the text of the issue. Does it need elaboration, minimal reproduction steps, design work? Make sure everything aligns with the issue templates, adding any information necessary in the main description of the issue. (Only use comments for discussion about the issue, treating the description as the latest summary of the conversation.)
Learn what code is relevant to the issue. Tagging Amy in a comment is the best way to learn this, at least until there are more contributors that know the code base. She can give you a list of the relevant files and explain how they work.
Note
It's important to fully understand how everything is build before you start writing code. This is the only way to ensure that what you build is consistent with the existing architecture.
To prepare to work on the issue, follow the pull request instructions.
If there is no automated test that verifies the defect is repaired, or there is a new feature you're adding, attempt to write at least one test, to help you track whether your code is working. Ff it's a new feature, you may need to write multiple to express all of the feature's requirements. 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 Amy, other contributors, and make sure the design and implementation decisions you're making are aligned with the project's existing patterns. If there was a designer who worked on it that is still in the community, find them and collaborate with them to ensure your implementation meets their specifications.
As you work, if you feel you've made progress, make a commit 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.
Regularly switch back to the main branch and run git pull to get recent changes to main. Switch back to your branch and run git rebase main to replay your commits over any changes to main that have happened since you branched from it. You may see merge conflicts; these are cases where you changed something that was also changed in main, so you'll have to communicate with whoever made the changes to ensure you're reconciling the conflicts correctly.
Some issues involve adding or modifying localization strings. If that applies to your issue, make sure to read the localize guide, so that you properly mark strings in other locales out of date or unwritten.
Ensure your final commit has Fixed #[issue number] in it, so GitHub will automatically close the issue when it is merged into main.
When you believe your work is done, submit a 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 come back with feedback for you to address before your work is merged to main. This includes automated feedback, such as tests that have failed. Expect to iterate several times before its approved.
Once your work is done, we'll schedule it for the next weekly release to production.
Once your pull request is accepted, delete your branch if it wasn't deleted already, so we have a tidy set of branches. (Your commits are saved, its just the branch that's gone).
Once you're done, pick another issue to work on!
Do you find something confusing on this page? Submit a maintenance issue, so we can improve it.