Skip to content

develop

Amy J. Ko edited this page Sep 24, 2024 · 22 revisions

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.

Onboard

Before starting, please read the contributor and complete every step.

Then, complete the local development setup documentation to configure your environment.

Learn

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.

IDE configuration

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. Changes you make to code are 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 test, running all 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 thoroughly verify your code!)
  • npm run locales. This checks the 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. If you change anything about localization types or strings, run npm run schemas to update the schemas to reflect the changes.

Choose an issue

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.

Understand the issue

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.

Set up a draft pull request for the issue

Follow the [pull request](pull requests) instructions to prepare to work on the issue.

Test

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.

Code

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.

Ensure your final commit has Fixed #[issue number], so GitHub will automatically close the issue when it is merged into main.

Submit a pull request (PR)

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.

Next steps

Once you're done, pick another issue to work on!

Clone this wiki locally