Skip to content

Docs: add a short “Quick Local Setup + Common Gotchas” section for new contributors #11855

@Prajwal-Dhande

Description

@Prajwal-Dhande

While setting up plots2 locally (non-Gitpod) as a first-time contributor,
I noticed that the README is very comprehensive but can feel overwhelming
for newcomers who just want to get the app running quickly.

The information needed to start is present, but it is spread across many
sections (Ruby versioning, database setup, Redis, webpacker, Passenger, etc.),
which makes it hard for new contributors to identify a clear entry point.

I propose adding a short section near the top of the README that includes:

  1. A concise “Quick Local Setup (TL;DR)” with the minimum steps to get the app running
  2. A “Common Gotchas for First-Time Contributors” subsection covering:
    • Ruby / Node version mismatches
    • Database configuration confusion (sqlite vs mysql)
    • Missing dependencies (Redis, webpacker)
    • Common errors encountered during initial setup and their fixes

This would not replace the existing detailed documentation, but instead
act as a guided entry point with links to the relevant sections below.

I believe this would significantly lower the barrier for first-time contributors
and reduce setup-related friction.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions