setup

This page is for anyone taking a develop, verify, or localize roles, as these roles require interacting with the Wordplay repository and running Wordplay locally to test. This requires installing a bunch of stuff, including a code editor, the Wordplay repository, and the many dependencies that Wordplay has. Here is the current list of required installs:

Install things

Note

Do each of these steps carefully, reading every prompt and error message. Do not rush. Developer tools tend to be poorly designed, and assume a lot of prior knowledge, so it's important to understand each step and decision in these setups.

• Install Node. If you don't have node installed, install it. And if you don't know if you do, you probably don't. It won't hurt to install it again. This allows you to install all of the packages that Wordplay depends on to run. Ensure you give Node proper permissions to update and delete packages as necessary; read each prompt carefully.
• Install VS Code. If you don't have VS Code installed, install it. It's a popular code editor, and the one we most recommend for contributing. It also has the best support for TypeScript and Svelte of any editor.
• Install VS Code Extensions. At a minimum, you'll want "Prettier" (which ensures consistent code formatting) and "Svelte for VS Code" (which adds Svelte language features to VS Code).

Learn about Pull Requests

Wordplay uses collaboration model called Fork and Pull, which involves you following three main steps:

• Fork the Wordplay repository
• Make changes in your fork (while keeping in sync with the Wordplay repository)
• Submit a pull request to proposing to merge your changes into the main Wordplay repository, and iterate with feedback until it's approved and merged.

Before you do any of this, it's helpful to understand this model at a high level. Read the following before proceeding if you don't know this collaboration model yet:

• Learn about Fork and Pull
• Learn about Best Practices for Pull Requests.
• Learn about How to Fork a Repository.
• Learn about Creating Pull Requests.

Git and GitHub are all bit overcomplicated, but once you go through a few examples, you'll get it. Just go slowly and ask questions.

Fork Wordplay and install its dependencies

• Fork the Wordplay repository. The easiest way to do this is to go to the GitHub website, make sure you're logged in, visit the Wordplay repository in a browser, and then find the "Fork" drop down button. In the drop down, you'll see a command called + Create a new fork.... You'll see a dialog asking what you want to name your fork; all of the defaults are fine, unless you're picky about what it's called. Press the Create a fork button to create the fork in your own personal account.
• Clone your fork to your computer. Open VS Code, and then find the toolbar icon called "Source Control". Click it, make sure you're logged in to GitHub, and then you'll a panel with a few buttons appears, one labeled "Clone Repository". Click it and choose "Clone from GitHub" and then find the name of the fork you created. Choose a place on your computer where you want to store it. Remember that this is just a local copy of the repository; any changes you make are local until you push them to the cloud, and all changes are specific to your fork until you create a pull request that's successfully merged into the Wordplay repository.
• Open a terminal. Now that you have a copy of your fork on your computer, and it's open in VS Code, we want to do some commands in the terminal. Find the menu item Terminal > New Terminal to open up a command line so we can do some work with some commands. Keep this open; you'll be using it later. You may have many open at once.
• Install dependencies. Wordplay requires a few other libraries to run locally. Type npm ci. This will install all of the code that Wordplay needs to run. If you run into problems, it's likely an issue with how Node was installed, and quite often permissions issues. There are so many things that can go wrong here, so web search on the error you're seeing, or write in #contributors for help.
• Add a link to the upstream repository. To tell git that your local clone of your fork should point to the original Wordplay repository, type git remote add upstream https://github.com/wordplaydev/wordplay.git.

Once everything above is installed, try this command in a terminal to run Wordplay locally on your computer:

npm run dev

That should start a local Vite web server and give you a URL like https://localhost:5173 for you to visit in your browser. You should now see the Wordplay website running on your device. If you don't, there's either a problem with your setup above or Wordplay. Don't worry, it's not your fault. Read any error messages you see, and ask if you need help.

Stay in Sync

Wordplay's code and dependencies are always changing, so it's important to run these two commands every once in a while, to make sure you're in sync with the main branch:

git fetch upstream
npm ci

The first command pulls new Wordplay code from GitHub and ensures your fork has its updates. (Think of this like a software update). The second command installs any new library updates that Wordplay depends on locally on your machine. Do this regularly (e.g., every time you do some work), so you don't fall so far behind that you have a big pile of conflicts between your code and the main repository.

If you made a branch in your fork for the issue you're working on, then you'll likely also want to rebase your branch on main:

git rebase main

This will replay commits since the last time you fetched from main. If you changed something that someone else changed, you might have some conflicts. Talk to the person you had a conflict with to figure out how to resolve the conflicts. (Don't just revert all the changes their made; you might break something).

Finally, don't do a npm update: that will change the versions of installed dependencies, and we want to do that intentionally. ci will preserve dependencies.

Follow your role's guidelines to work on your issue.