RedwoodJS

v0.19.0

# Contributing

Love Redwood and want to get involved? You’re in the right place and in good company! As of this writing, there are over 100 individuals who have helped make Redwood awesome by contributing code and documentation. This doesn't include all those who participate in the vibrant, helpful, and encouraging Forums and Discord, which are both great places to get started if you have any questions.

There are several ways you can contribute to Redwood:

Before interacting with the Redwood community, please read and understand our Code of Conduct.

# Contributing Code

Redwood's composed of many packages that are designed to work together. Some of these packages are designed to be used outside Redwood too!

Before you start contributing, you'll want to set up your local development environment. The Redwood repo's top-level contributing guide walks you through this. Make sure to give it an initial read.

For details on contributing to a specific package, see the package's README (links provided in the table below). Each README has a section named Roadmap. If you want to get involved but don't quite know how, the Roadmap's a good place to start. See anything that interests you? Go for it! And be sure to let us know—you don't have to have a finished product before opening an issue or pull request. In fact, we're big fans of Readme Driven Development.

What you want to do not on the roadmap? Well, still go for it! We love spikes and proof-of-concepts. And if you have a question, just ask!

Package Description
@redwoodjs/api Exposes functions to build the GraphQL API and provides services with context
@redwoodjs/auth A lightweight wrapper around popular SPA authentication libraries
@redwoodjs/cli All the commands for Redwood's built-in CLI
@redwoodjs/core Defines babel plugins and config files
@redwoodjs/create-redwood-app Enables yarn create redwood-app—downloads the latest release of Redwood and extracts it into the supplied directory
@redwoodjs/dev-server Configuration for the local development server
@redwoodjs/eslint-config Defines Redwood's eslint config
@redwoodjs/eslint-plugin-redwood Defines eslint plugins; currently just prohibits the use of non-existent pages in Routes.js
@redwoodjs/forms Provides Form helpers
@redwoodjs/internal Provides tooling to parse Redwood configs and get a project's paths
@redwoodjs/router The built-in router for Redwood
@redwoodjs/structure Provides a way to build, validate and inspect an object graph that represents a complete Redwood project
@redwoodjs/testing Provides helpful defaults when testing a Redwood project's web side
@redwoodjs/web Configures a Redwood's app web side: wraps the Apollo Client in RedwoodProvider; defines the Cell HOC

# Contributing Docs

First off, thank you for your interest in contributing docs! Redwood prides itself on good developer experience, and that includes good documentation.

Before you get started, there's an implicit doc-distinction that we should make explicit: all the docs on redwoodjs.com are for helping people develop apps using Redwood, while all the docs on the Redwood repo are for helping people contribute to Redwood.

The exceptions to this split are the packages that are designed to be used outside Redwood, which, right now, are @redwoodjs/auth and @redwoodjs/router.

Although Developing and Contributing docs are in different places, they most definitely should be linked and referenced as needed. For example, it's appropriate to have a "Contributing" doc on redwoodjs.com that's context-appropriate, but it should link to the Framework's CONTRIBUTING.md (the way this doc does).

# How Redwood Thinks about Docs

Before we get into the how-to, a little explanation. When thinking about docs, we find divio's documentation system really useful. It's not necessary that a doc always have all four of the dimensions listed, but if you find yourself stuck, you can ask yourself questions like "Should I be explaining? Am I explaining too much? Too little?" to reorient yourself while writing.

# Docs for Developing Redwood Apps

redwoodjs.com has three kinds of Developing docs: Docs, Cookbook Recipes, and The Tutorial. You can find Docs and Cookbook Recipes within their respective directories on the redwood/redwoodjs.com repo: docs/ and cookbook/. The Tutorial is actually all in one file.

The Tutorial is a standalone document that serves a specific purpose as an introduction to Redwood, an aspirational roadmap, and an example of developer experience. As such, it's distinct from the categories mentioned, although it's most similar to Cookbook Recipes.

# Docs

Docs are explanation-driven how-to content. They're more direct and to-the-point than The Tutorial and Cookbook Recipes. The idea is much more about finding something or getting something done than any kind of learning journey.

Before you take on a doc, you should read Form and Redwood Router; they have the kind of content you should be striving for. They're comprehensive yet conversational.

In general, don't be afraid to go into too much detail. We'd rather you err on the side of too much than too little. One tip for finding good content is searching the forum and repo for "prior art"—what are people talking about where this comes up?

# Cookbook Recipes

Cookbook Recipes are tutorial-style content focused on a specific problem-solution. They usually have a beginner in mind (if not, they should indicate that they don't—put 'Advanced' or 'Deep-Dive', etc., in the title or introduction). Cookbook Recipes may include some explanatory text as asides, but they shouldn't be the majority of the content.

# Making a Doc Findable

If you write it, will they read it? We think they will—if they can find it.

After you've finished writing, step back for a moment and consider the word(s) or phrase(s) people will use to find what you just wrote. For example, let's say you were writing a doc about configuring a Redwood app. If you didn't know much about configuring a Redwood app, a heading (in the nav bar to the left) like "redwood.toml" wouldn't make much sense, even though it is the main configuration file. You'd probably look for "Redwood Config" or "Settings", or type "how to change Redwood App settings" in the "Search the docs" bar up top, or in Google.

That is to say, the most useful headings aren't always the most literal ones. Indexing is more than just underlining the "important" words in a text—it's identifying and locating the concepts and topics that are the most relevant to our readers, the users of our documentation.

So, after you've finished writing, reread what you wrote with the intention of making a list of two to three keywords or phrases. Then, try to use each of those in three places, in this order of priority:

  • the left-nav menu title
  • the page title or the first right-nav ("On this page") section title
  • the introductory paragraph

# Docs for Contributing to the Redwood Repo

These docs are in the Framework repo, redwoodjs/redwood, and explain how to contribute to Redwood packages. They're the docs linked to in the table above.

In general, they should consist of more straightforward explanations, are allowed to be technically heavy, and should be written for a more experienced audience. But as a best practice for collaborative projects, they should still provide a Vision + Roadmap and identify the project-point person(s) (or lead(s)).