CONTRIBUTING.md

• 1. Getting Oriented.
  • 1.1 General Design and Architecture.
  • 1.2 Users and Stakeholders.
  • 1.3 Specific Dependencies
  • 1.4 Entity Relationship Diagram (ERD).
• 2. Machine Setup.
  • 2.1. Developer Setup and Documentation.
  • 2.2.1 Developing Mailers.
  • 2.2.2 Debugger
  • 2.3. Using the devcontainer.
  • 2.4. Testing

1. Getting Oriented.

New contributors may want to review the Zinc contribution guide to ground themselves in the norms we try to follow across projects.

1.1 General Design and Architecture.

Convene is as a multi-user, multi-application web-first Operating System.

Convene's design strategy leans heavily into Outcome-Driven Innovation, Accessibility, Usability, and Data Portability. Interoperability is offered by embracing open protocols like Hypermedia as the Engine of Application State (HATEOAS). Quality and Changeability is maintained by performing Test-Oriented Development, Continuous Deployment, and Domain Driven Design.

1.2 Users and Stakeholders.

Stakeholders for Convene fall into one or more of the following categories:

• Clients, who are the legal owners of the data of their Spaces in a Neighborhood.
• [Members], have broad authority over Spaces and their [Furniture]. They are also responsible for [Visitor: Support], [Visitor: Trust & Safety], [Member: Support], and [Member: Trust & Safety].
• [Visitors], who access Spaces and their [Furniture] according to [Member] specification.
• Operators, who steward the [Neighborhood: Infrastructure], [Neighborhood: Trust & Safety], and [Client: Support] responsibilities
• [Contributors] and [Maintainers], who design and build [Furniture].

Note: Furniture has been renamed to Gizmo/Gizmos.

1.3 Specific Dependencies

1.3.a. Upstream Dependencies

Contributing to Convene benefits from fluency with the following tools:

• For Data Storage and Retrieval: PostgreSQL, Redis, and an [S3-compatible] file store.
• Servicing HTTP Requests is done with [Ruby on Rails].
• Background Jobs are performed by [Sidekiq].
• The User Interface is Server-Side Rendered [Components] implemented using [ViewComponent] styled by [Tailwind] and with interactivity provided by [Turbo] and [StimulusJS].

1.4 Entity Relationship Diagram (ERD).

We auto-generate an ERD from our Domain Model.

Generate an updated ERD via:

bin/erd

2. Machine Setup.

2.1. Developer Setup and Documentation.

To set up your development environment you'll need ruby, node and postgresql. If on Windows using WSL2, please see this document.

First, ensure your development environment has:

1. Ruby (See .ruby-version for version)
2. Node (See .nvmrc for version)
3. Yarn
4. PostgreSQL
5. Redis

(Note: If you use Docker, a docker-compose.yml file has been included with PostgreSQL and Redis for convenience.)

Then, run bin/setup to install Ruby and Node dependencies and set up the database.

Once setup completes, configure your local development environment.

1. Open .env and make any changes.

Once you have completed configuration; run bin/run. You now should be able to open http://localhost:3000 and see Convene.

Log in with space-member@example.com. You can check the email using http://localhost:1080.

Finally, with the server still running (perhaps in a different terminal), run bin/test to ensure that your development environment is configured correctly.

2.2.1 Developing Mailers.

Set SMTP_* environment variables to configure Action Mailer.

To preview mailers, visit http://localhost:3000/rails/mailers/

For more information about Rails's ActionMailers, see this guide.

2.2.2 Debugger

To run pry or byebug, run bin/connect web.

Guides: pry | byebug

2.3. Using the devcontainer.

The devcontainer workflow was disabled on 2024/05/22, see #2415 for rationale. If you want to re-enable it, let one of the maintainers know.

We have setup a developer container environment using VS Code's Dev Containers extension. Please see this document for instructions on using.

2.4. Testing

See the Testing documentation.