develop

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 and setup documentation first, in full.

Next, 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. Ask Amy questions if something is vague; your questions are a helpful guide on what we need to elaborate on.

After you've learned the architecture, here is how you'll work:

First, when working, always have at least four terminals open, one with npm run dev (for interactive testing while you build), one with npm run check (to show any TypeScript errors), one with npm run test to (ensure you know when any tests fail), and one with npm run locales (to know when you've violated any localization rules). These are all important to run, so that you find issues before you commit or push anything.

We use the GitHub Flow branching strategy on this project. Here's what it looks like in practice:

1. Review available issues, searching for the ones you want to work on. If you're just starting, filter by the starter label to find issues that might be easier for someone learning the implementation. Filter by issues with no assignee. Issues eligible for development are ones with the defect label or buildable label, indicating that it's a feature that is ready to build. (If it 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).
2. Assign yourself to and comment on the issue, so everyone knows that you're the point of contact for it.
3. 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.)
4. When you're ready to work on the issue, create a branch from main in which to do your work with the format [issue #]-[descriptive name, so we know what the branch concerns. For example, if you were working on hypothetical issue number 27, and it concerned fancy colors, you might call your branch 27-fancy-colors. If you're a contributor on the repository, you can create the branch in our repository. If you're not, you can create a fork and make a branch in your fork for later merging through a pull request. Publish it, so that others can work on it with you.
5. If there is no automated test that verifies the defect is repaired, attempt to write at least one (there probably isn't one, which is why there's a defect!). If 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.
6. 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.
7. Commit to your branch. 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 pull from main, then git rebase main in your feature branch, replaying your commits over any changes to main that have happened since you branched from it. Ensure your final commit has Fixed #[issue number] in it, so GitHub will automatically close the issue when it is merged into main.
8. When you believe your work is done, submit a pull request, requesting your branch be merged into main. 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.
9. 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.
10. Once your pull request is accepted, delete your branch, 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!