Contributing

This document is meant to be a complete set of instructions on how to contribute to Repeater World, including everything you need to know to get it up and running on your own computer. If the instructions here don't work, please update this document or report an issue to https://github.com/flexpointtech/repeater_world/issues. If you have any questions you can ask on https://github.com/flexpointtech/repeater_world/discussions.

If you are not sure what you can help with, check out these issues: https://github.com/flexpointtech/repeater_world/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22

Repeater World is a Ruby on Rails application, developed as a monolith, with HTML served from the server following the Hotwire pattern. To develop you need to run:

• A PostgreSQL database.
• The Rails Server.
• The Tailwind CSS compiler.

Services

The PostgreSQL database, and all other services, will be run from a docker-compose file that's distributed with the code. Install docker by whatever mechanism you prefer, possibly going to https://www.docker.com/get-started and then run:

docker-compose up

to have all the dependency services up and running.

Port 5000 is reserved for the Rails server, and all services will be run in non-standard ports starting at 5001 to avoid any conflicts with software you may already have on your machine.

Ruby

You need Ruby, 3.1.2 or so. On Windows it's recommended that you use WSL and then pretend it's just a Linux. You should probably use a Ruby version manager like RVM or rbenv (and there are others).

Non-ruby dependencies

Even though we use a dockerized database, pg gem depends on libraries which come with Postgres installed on the host machine.

On Windows use WSL and then follow the Linux instructions.

On MacOS with Homebrew:

brew install postgresql

On Ubuntu Linux, It's likely something like:

sudo apt-get install libpq-dev

TODO: add other distros.

Getting things ready

You first need to install dependencies:

bundle install

Create the databases:

rake db:create

Run the migrations:

rake db:migrate

Generate sample data:

rake generate_sample_data

Configure the local environment by copying .env.local.example to .env.local and changing any values that need changing. For example, for Google Maps to work, you'll need to obtain a Google Maps API key (it's free) and set GOOGLE_MAPS_API_KEY to it. You can find other environment variables in Environment Variables.

Running

That will create enough data for you to start playing, including repeaters, users, admins, etc. Take a look at the output of the command for the usernames and passwords of these users.

Run the tests (or specs if you want to be fancy):

rake spec

If all of that worked you are in good shape.

Now run the server in development mode:

rails server

Because we use Tailwind CSS, you also need to run the TailwindCSS compiler:

rails tailwindcss:watch

If you want, you can run:

.bin/dev

which runs both, the Rails server and the TailwindCSS compiler in one go.

As of now, you can go to http://localhost:5000 and use the application locally.

Testing

If you contribute any code, please write tests to it. Check the coverage and make sure it's high. We try to keep it above 90% but more important than the number is to cover everything that makes sense and make sure that everything is tested. Once your PR is merged to main it'll get automatically deployed to https://repeater.world without any further QA or checking.