A tool to help manage codebar.io members and events.

If you are considering making a PR, please take a look at the GitHub issues to see if there are any new feature requirements or bugs that you maybe able to help resolve.

Need help? We're on Slack!

Before you start, please check out our contributing guidelines.

We recommend native installation for local development. A full step-by-step guide is in docs/development-setup.md. The quick version is below.

1. Install prerequisites (macOS or Linux):

   • mise — manages Ruby and environment variables
   • PostgreSQL — database server
   • ImageMagick — image processing

   On macOS with Homebrew:

   brew install mise postgresql imagemagick
   brew services start postgresql

2. Clone the project:

   git clone https://github.com/codebar/planner.git
   cd planner

3. Install Ruby (managed by mise):

   mise install

4. Configure GitHub OAuth:

   • Create a GitHub OAuth app at https://github.com/settings/applications/new
   • Authorization callback URL: http://localhost:3000/auth/github
   • Copy your Client ID and Client Secret into mise.local.toml:

     cp mise.local.toml.example mise.local.toml
     # Edit mise.local.toml with your real credentials

5. Install dependencies and set up the database:

   gem install bundler
   bundle install
   bundle exec rake db:create db:prepare db:test:prepare

6. Check your environment:

   bundle exec rake setup:check

7. Start the app:

   bundle exec rails server

   Visit http://localhost:3000.

bundle exec rspec

Run tests in parallel for faster results:

bundle exec parallel_rspec spec/ -n 3

Run a single test:

bundle exec rspec spec/path/to/test_spec.rb:42

Run JavaScript-enabled feature tests with a visible browser:

PLAYWRIGHT_HEADLESS=false bundle exec rspec

After signing up locally, run:

bundle exec rails runner "Member.find_by(email: 'your-email@example.com').add_role(:admin)"

For detailed, step-by-step instructions — including troubleshooting, Linux-specific steps, and explanations of what each tool does — see docs/development-setup.md.

A Docker setup exists but is not recommended for local development. It is slower, harder to debug, and does not support running JavaScript feature tests with a visible browser.

If you prefer Docker, see the commands in bin/d*:

We use Bootstrap 5. Documentation: https://getbootstrap.com/docs/5.2/getting-started/introduction/

This project follows layered architecture principles as described in Layered Design for Ruby on Rails Applications by Vladimir Dementyev. The goal is to organise code into four layers with strict unidirectional dependencies:

Guidelines for contributors:

• Keep controllers thin — they should only handle HTTP concerns (params, session, response format)
• Put business logic in domain models, not services (services orchestrate, they don't own logic)
• Don't reference Current attributes from models — pass values explicitly
• Extract reusable queries into query objects, complex view logic into presenters
• Use form objects for multi-model forms or complex validation

AGENTS.md also references these patterns in its For planning agents section.

You can pick one of the open issues, fix a bug, improve the interface, refactor the code or improve test coverage!

If there is something else that you would like to work on, open an issue first so we can discuss it. We are always open to new ideas and ways of improving planner!

Guidelines on contributing to planner