contribute

Welcome! You must be here to make programming accessible to everyone in the world, regardless of language or ability. We're excited to have your help!

Welcome

To start, review our welcome slides! They provide crucial context for the motivation of the project. We'll present these at the first meeting of our quarterly meetups, but if you aren't attending those, missed the first meeting, or want to see what we'll present before meeting, start here:

• Review our welcome slides

Commit to our Code of Conduct

Before getting started, there are several key principles we expect you to follow when contributing to the project:

Note

Don't skim these. They're the most important part of contributing.

Let's start with expectations. These are important, because they set norms for your behavior, communication, and conduct in this community. Read each one carefully, and pledge to yourself to do each of them.

• Communicate. The success of a software project depends greatly on individuals communicating their progress, their needs, and their knowledge, frequently and clearly. All communication related to issues should be in GitHub the corresponding GitHub issue, so any future contributor (and even yourself) can see the history of discussion and dialog. If you need to communicate about something unrelated to an issue (e.g., coordinating with collaborators), a group chat on Discord is best for more temporary collaborations, and a channel for more permanent groups. For those signed up for credit at UW, we also expect attendance to the weekly meetup.

• Be responsive. When someone reaches out to you about something, reply, at least within a few weekdays. Ghosting his highly damaging to collaboration and to the project. Set practices to regularly check your GitHub and Discord notifications so that you can reply to people trying to reach you.

• Learn. Making software requires an immense commitment to learning new things. Learning is important, takes time, and counts as progress in this community, even if it doesn't translate immediately into contributions. Find others to learn with, get feedback and help from others who know skills.

• Read carefully. There is extensive and growing documentation about every aspect of this project. Not all of it is good, and sometimes it might be wrong, but it does exist. Read it carefully first, and if it doesn't answer your question, then go to the person to is most likely to have the answer. And when you encounter an error, read the error message in detail and read documentation about the error message. Learn what it means, search for the specific error message online (without project specific details), and try to learn its possible causes. Ask for help if you can't find the answer in documentation.

• Seek help. Asking for help can be scary: its a signal that you don't know something, and we understand why you might fear being judged for not knowing something. But with software design and development, not knowing something is normal. That is the constant state of everyone. It is a kind of work that requires constant learning. So I expect you to seek help, first from documentation, then from contributors in the project. And that includes me: I know more about this project than anyone, and so if you don't come to me for help, you're not doing your job. If it's about a particular issue on GitHub, tag someone in a comment. If it's about something more general, post on the in the appropriate channel in Discord. Default to posting publicly, because it's almost certain that someone else has the same question. Only use private questions if it is a confidential topic.

• Protect each other. If you're ill, don't come to our gatherings in person. If you see bullying of any kind, stop it. If you see someone attacking another student for their identity, call them in, and hold them accountable to be kind. This has to be a place where everyone is safe, physically, and emotionally. Good work can't happen if we aren't. We want everyone who engages here to leave feeling smarter, more capable, more welcome, and more valued.

• Keep everything in GitHub (eventually). You're welcome to use other platforms and tools to do your work, but all work should be represented by a GitHub issue, and all work should eventually end up in GitHub. Create issues to represent your work, assign yourself to issues, and keep all of your work embedded in issues, using GitHub markdown. There should be no external links to content hosted elsewhere; such links break, or become inaccessible, making them useless for future contributors.

• Engage. If you're a student at UW, I expect you to be an engaged part of the community. Join the UW CREATE and DUB mailing lists, attend our seminars, and learn more about accessible computing and HCI. Maybe even fall in love with HCI, computing education, and accessibility research!

• Attend to details. Don't take shortcuts or ignore design details; work on them, or detail the work to be done for later. This is not only important in any engineering and design work, which demands attention to detail in both building and verification, but it also matters greatly for our projects goals of decolonization, justice, and equity in programming. Details of the mundane are where many are where injustice often lives, because it's easiest to ignore.

• Be consistent. This project as a large number of established architectural and interaction design patterns. Most of them were very consciously chosen to support some design goal; some may have been accidents or not well thought through. Before you begin design or engineering work, study how things have been done, and do them like that. And if you find yourself wanting to deviates from other other things work, pause talk to others, and make sure that the deviation is a good idea. Don't deviate just because it's the easier path.

• Be critical. This project only improves if you report things that aren't working. That includes things you think are design flaws, usability and accessibility problems, defects, complexities, and even this documentation. It's up to all of us to notice when something could be better. Report all issues here in GitHub.

Learning together

Contributing to this project will require lots of learning. Don't be surprised if you need to pause, spend some time learning a particular aspect of a tool, programming language, or framework. We view that learning as a normal part of contributing, and hope you will too! There's no shame in taking responsibility for some work, and learning as part of it.

Here are some of the things you might need to learn:

• Git and GitHub functionality
• VS Code functionality
• Details of JavaScript, HTML, and CSS syntax and semantics
• TypeScript, and the more general concept of static typing
• Svelte and SvelteKit concepts and tools
• Firebase concepts and functionality (authentication and Firestore in particular)

Obviously, if you know some of these will already, you'll be able to contribute more, but all contributions are valuable, however small and slow. We're just glad you're here.

In fact, it is entirely appropriate if most of your time is spent learning. Engage the community in this learning, learn together, and teach each other; self-organize study groups, share resources, and ask questions on Discord, and contribute answers if you have them. That requires some vulnerability, but the more vulnerable and supportive we are with each other, the faster we will all learn.

If you are participating in the Wordplaypen meetups in Seattle, self-organize group tutorials. Amy and other contributors can explain concepts and give demos in groups, helping to accelerate learning. We also encourage you to organize your own group tutorials.

Join GitHub

GitHub is where we talk about issues. All new issues, design proposals, and discussion about specific issues should go there, so there's a record of decisions for everyone to review, enabling newcomers to have all the context necessary to contribute to the issue.

It's also where we manage the project. See our project's Kanban board to check what issues are in our backlog, being actively worked on, or finished.

• If you don't have a GitHub account, create one, and make note of your username.

Important

GitHub be responsive to GitHub comments, especially if someone tags you. It's crucial that you respond to requests within at least a few days, so that others aren't blocked, waiting for information from you. Do not ghost.

Join Discord

Discord is where we help each other and coordinate our work. Post in relevant channels with questions, resources, and event information.

You're also welcome to create dedicated channels for issues (named [issue]-description, in the "issues" category), to coordinate and collaborate, as long as you ensure that key insights and decisions are captured on GitHub. Archive the channel once the issue is closed.

• Join the Wordplay Discord and make sure you're on the #contributors channel.
• In Discord, update your server nickname in "Edit Server Profile" to "Your Name (github-username)" (e.g., Amy's is "Amy J. Ko (amyjko) so people can find you on each platform.

Important

Don't use other platforms (e.g., some other Discord server, Slack, Teams, group chats, etc.) to communicate. Discord is where our community is, and if you talk elsewhere, it fragments the community. If you have ideas for how to make the Discord better support your work, suggest ideas in #suggestions.

Learn Wordplay basics

Before you can contribute, there are several things you need to install and configure in order to run Wordplay on your device:

• Complete the Wordplay tutorial to learn the programming language and the interface. This is an essential step for any contribution, so you know what you're enhancing, fixing, localizing, etc.
• Create an account, explore examples in the galleries, and make a few Wordplay programs. Get used to what's possible to create with it.

It's okay if you don't feel like you've mastered the language after the tutorial. The important part is that you have a sense of the scope of content, functionality, and possibilities, so you have context for your work.

Choose a role

There are many ways to contribute to the project:

• Design
• Develop
• Verify
• Localize
• Curate
• Manage

Pick one or more of these, carefully read through the entire documents, and ask questions about the role in the appropriate channel in Discord. If it sounds like something you want to do, or learn to do, then:

• Request contributor permissions so you can contribute on GitHub. This is a manual process, so it may take a day or so for us to send an invite.
• Go to the #choose-roles channel on Discord and indicate the role(s) you've chosen
• Read the guidelines for your role(s) the corresponding documents above.

Set up your device

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).
• Clone the Wordplay repository. Open VS Code, and then find the toolbar icon called "Source Control". Click it, and you'll a panel with a few buttons appears, one labeled "Clone Repository". Click it, then copy and paste https://github.com/amyjko/wordplay into the prompt. Once you enter it, it'll ask you where you want to clone the repository; 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 a branch or submit them as a pull request to GitHub.
• Open the repository in VS Code. It'll work for a second to get the repository from the internet, then ask you if you want to open it. Say yes. It'll then ask you whether you whether you trust the authors. (Do you? I trust me, but that's me!)
• Open a terminal. In the VS Code menu, choose 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. 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.

Once everything above is installed, try this command in a terminal:

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.

Sync Regularly

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 pull
npm ci

The first command pulls new Wordplay code from GitHub and also new code that Wordplay depends on. Think of this like any other software update. Note: 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.