Skip to content

Latest commit

 

History

History
135 lines (79 loc) · 10.5 KB

CONTRIBUTING.md

File metadata and controls

135 lines (79 loc) · 10.5 KB

Contributing to Wasp

There are several main ways in which you can contribute to Wasp:

Before you begin

  • Get some experience with using Wasp, if you don't have any yet. Check out the Getting Started guide to get familiar with Wasp's fundamentals. Ideally, you'd also build an app from the Pick a Tutorial page to really get a feel for it!
  • Figure out what you'd like to help with. It can be code, documentation, tutorials, etc. Check Ways to contribute for more details.
  • Join our Discord Discord for faster communication and feedback. We'd be happy to help you find the issue you'll enjoy working on, depending on your interests and skill set! #wasp-dev channel is the perfect place to ping us with the task you want to do and how you plan to do it, which reduces duplicate or misdirected efforts.

And before you open a PR, check if it will need agreement from the maintainers:

  • Small, obvious fixes are welcome as direct PRs. Typos, broken links, docs corrections, small bugs where the fix is clear and comes with a test.

  • Everything else: talk to us before writing code. Bigger fixes or new features always need maintainer agreement in advance. Open a GitHub issue or post in the #wasp-dev channel on our Discord, and wait for a maintainer to agree on the approach. We will usually close PRs for undiscussed non-trivial changes without reviewing them. See Policies below for details, including our policy on AI-assisted contributions.

This repo

We are using a monorepo approach, where one git repo contains multiple related projects.

In our case, those are web (Wasp's web page, including docs and blog), waspc (Wasp CLI & framework), examples (example Wasp apps), etc.

While this document captures the general instructions for the whole repo, make sure to check the README of each individual project in the repo when working on it for more detailed instructions.

Dev tooling

Setup

Note

Developing on Windows? Use the Bash shell bundled with Git for Windows (often called "Git Bash"). Wasp's development scripts are Bash scripts and won't run in PowerShell or Command Prompt. If you develop inside WSL (Windows Subsystem for Linux), you are effectively on Linux, so follow the Linux instructions instead.

We use mise to manage our development tools (e.g. Haskell, Node, and code formatters). Mise is an all-in-one tool that makes it easy to set up and manage the development environment (tools, env vars, tasks) per project. Everything is declared in a single file (mise.toml), and every developer can use it to set up their environment in a consistent way. We also use it on our CI to ensure it uses the same versions of tools as well.

Note

There are no hard dependencies on mise for local development, so if you prefer to use your own tooling, you can install each program separately, and use the versions specified in mise.toml as a reference. But then, you're in charge of making sure you have the right versions of the tools installed, and keeping them up-to-date as we upgrade them.

Global Mise setup

While you can use Mise explicitly, on demand, via mise exec|run|en, normally you don't want to deal with that but just have it work automatically in the background. Mise has detailed docs on this, but here is the summarized version of how you will most likely want to set it up:

  1. Of course, install mise.
  2. Set up automatic mise activation per dir for interactive shells by adding eval "$($HOME/.local/bin/mise activate bash)" to your ~/.bashrc (If on Mac: ... zsh)" to your ~/.zshrc). With this, when in an interactive shell, mise will automatically keep the dev environment updated for that shell based on your current directory. It does so by updating its PATH and other env vars.
  3. Set up global mise shims by adding eval "$($HOME/.local/bin/mise activate bash --shims)" to your ~/.profile or possibly ~/.bash_profile (If on Mac: ... zsh --shims)" to your ~/.zprofile). This complements the activate by covering direct, non-interactive usage, which activate doesn't cover. E.g. if a process calls node directly, and not from interactive shell, it will hit a mise shim which will, based on the calling process's working directory, provide it with the correct version of node (or just pass it to system node if there is no applicable mise config).
  4. Potentially install tool-specific mise integrations/plugins, e.g. a plugin for your editor, although in most cases activation + shims will already do the job and you don't have to bother with this.

If you are wondering why both activate and shims: because they both serve different use cases and complement each other. Activate runs once per dir change / shell activation, but can't affect the non-interactive usage (e.g. your editor executing tools non-interactively). On the other hand, shims work even for non-interactive usage, but call mise on each tool call (although cheap) and also can't provide env vars for the shell (but do set them for that single tool call). Having both ensures you are well covered.

Run mise doctor to validate that everything is setup correctly.

Repo setup

Run mise install from the root of the repo to install all the required tools.

Basic commands

Formatting is defined at the repo level, and you can run it from the repo root with

pnpm run format:check

to check the formatting without any changes to the files, or

pnpm run format:write

to check and automatically fix formatting (modifies the files).

Ways to contribute

Wasp as a web framework

Wasp is a language for developing full-stack web apps. This means there are plenty of tasks related to web development itself, and most come down to improving one of the core features of Wasp (like Auth, Operations, Jobs, Rendering), or maybe improving our dev tooling config, etc.

If you have full-stack experience outside of Wasp, you should already be in a good place to start contributing in this direction.

Web dev issues for beginners can be found here.

Wasp CLI/compiler internals

The Wasp compiler is implemented in Haskell, but you will also see a lot of Javascript and other web technologies because Wasp compiles its own code into them.

While you will need to know some Haskell, you don't have to be an expert in Haskell to contribute or understand the code since we don't use complicated Haskell features often. Most of the code is relatively straightforward, and we are happy to help with the part that is not.

Check the Wasp compiler README for all the detailed instructions and guides.

Tutorials or Example apps

Another great way to help is to create an app with Wasp! We have an Examples section on our website, as well as the Tutorials page. Both of them can be improved and updated with your projects.

All that's required is to create an app. And make a tutorial or a blog post to help other people reproduce your work. Some prominent examples are: Waspello, Waspleau, and To-Do app.

Or you can re-build your existing pet project with Wasp. That would be cool!

Documentation & Blog

It may sound like the simplest one, but it's super valuable! If you've found an issue, a broken link or if something was unclear on our website - please, feel free to fix it :)

Please make sure to base your feature branches and PRs on the release branch instead of main, since that's the one that is deployed to the website.

Documentation issues for beginners can be found here.

If you'd like to write a blog post about Wasp, please contact us via Discord to discuss the topic and the details.

Happy hacking!

Policies

These are some general policies that we follow when it comes to contributions. They are not meant to be strict or exhaustive, but rather to give you a sense of what we value and expect. If you are linked here from a PR, it means that we think your contribution could be improved in some way, and following these guidelines is the best way to do it.

Discuss before you code

Anything beyond a small, obvious fix needs a maintainer's agreement on the approach before you write the code: features, refactors, API or behavior changes, and anything where you had to choose between approaches. Propose it in a GitHub issue or in the #wasp-dev channel on our Discord. An open issue is not by itself a request for PRs: check that a maintainer has confirmed the approach in the discussion first.

If a non-trivial PR arrives without that agreement, we will usually close it and ask you to start the discussion, instead of reviewing it. This is not us being unfriendly: a PR review is the wrong place to design a solution together, and we would rather spend that time helping you land something we can all agree on.

AIs and LLMs

You are free to use AI/LLM tools and agents. But the standard remains the same: you must own and stand behind every line of code and every decision in your PR, exactly as if no AI was involved. That means you've read it, run it, understood it, and you can explain and defend it under review.

Everything that lands in Wasp becomes ours to maintain, so the bar is the same regardless of how the code was written. If a PR shows clear signs that no human supervised it, we'll close it to protect our time. If you think we got that wrong, just tell us and we'll take another look.