Bookkeeper Portal — 🟥 Edition

dev branch: , deployed app: Heroku

main branch: , deployed app: Heroku

A web application for keeping track of items and loaning them out, written in Ruby on Rails. Created in the Scalable Software Engineering course at the HPI in Potsdam.

Development Guide

Commit Guideline

We use the Conventional Commits Specification v1.0.0 for writing commit messages. Please refer to the website for specific instructions.

Since we don't have many different modules / services, we do not specify a commit scope (write fix: ... instead of fix(module): ...).

We use the recommended commit types from the specification, namely:

• feat: A code change that introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning)
• fix: A code change that patches a bug in your codebase (this correlates with PATCH in Semantic Versioning)
• refactor: A code change that neither fixes a bug nor adds a feature
• build: Changes that affect the build system or external dependencies (example scopes: pip, npm)
• ci: Changes to CI configuration files and scripts (examples: GitHub Actions)
• docs: Documentation only changes
• perf: A code change that improves performance
• test: Adding missing tests or correcting existing tests

Git Workflow

We practice Scaled Trunk-Based Development with a dev branch as trunk. Hence our feature branches are short-lived and merged back into dev as soon as possible. After consultation with POs, dev can be merged into main at any time to create a production release.

Our branches are named {team-initals}/{feature-name}, eg. gdm/print-qrcode. This allows folder grouping by team and easy identification of the feature being worked on.

Each PR requires at least one approved review before it can be merged into dev. Each PR branch must be rebased on dev before merging (or have dev merged into the PR branch before).

Also please do not squash your commits.

Code & Style Guide

We follow the Ruby Style Guide, which is enforced by RuboCop. Please use an editor extension to ensure that Rubocop offenses are highlighted directly.

Rubocop also allows to automatically fix offenses:

bundle exec rubocop --auto-correct

Employed Frameworks

• Stimulus JS as the default JavaScript framework, augmenting HTML
• Bootstrap for layout, styling and icons
• Devise library for authentication
• FactoryBot to generate test data
• Capybara for feature testing
• shoulda for additional RSpec matchers

Cheat Sheets

• FactoryBot
• Testing using Capybara

Setup

• bundle exec rails db:migrate RAILS_ENV=development && bundle exec rails db:migrate RAILS_ENV=test Migrate both test and development databases
• rails assets:clobber && rails assets:precompile Redo asset compilation

Testing

• bundle exec rspec Run the full test suite
  • --format doc More detailed test output
  • -e 'search keyword in test name' Specify what tests to run dynamically
  • --exclude-pattern "spec/features/**/*.rb" Exclude feature tests (which are typically fairly slow)
• bundle exec rspec spec/<rest_of_file_path>.rb Specify a folder or test file to run
• bundle exec rspec --profile Examine run time of tests
• Code coverage reports are written to coverage/index.html after test runs (by simplecov)

Debugging

• debug anywhere in the code to access an interactive console
• save_and_open_page within a feature test to inspect the state of a webpage in a browser
• rails c --sandbox Test out some code in the Rails console without changing any data
• rails dbconsole Starts the CLI of the database you're using
• bundle exec rails routes Show all the routes (and their names) of the application
• bundle exec rails about Show stats on current Rails installation, including version numbers

Generating

• rails g migration DoSomething Create migration db/migrate/*_DoSomething.rb
• rails generate takes a --pretend / -p option that shows what will be generated without changing anything

Local Development Setup

Ensure you have access to a Unix-like environment through:

• Your local Linux / MacOS installation
• Using the Windows Subsystem for Linux (WSL)
• Using a VM, e.g. Virtualbox and Vagrant
• Using a docker container

Application Setup

• ruby --version Ensure Ruby v2.7.4 using rbenv or RVM
• sqlite3 --version Ensure SQLite3 database installation
• bundle --version Ensure Bundler installation (gem install bundler)
• bundle config set without 'production' && bundle install Install gem dependencies from Gemfile
• rails db:migrate Setup the database, run migrations
• rails assets:precompile && rails s Compile assets & start dev server (default port 3000)
• bundle exec rspec --format documentation Run the tests (using RSpec framework)

OIDC Setup

Note: This is only required in a production environment. There are hard-coded OIDC client credentials in this project which are configured to work in a local environment.

• register a new application with the redirect URI http://{BASE_URL}/users/auth/openid_connect/callback (adapt the base URL accordingly).
• set the following variables in your rails environment:
  • OPENID_CONNECT_CLIENT_ID
  • OPENID_CONNECT_CLIENT_SECRET

Creating Debug Users

To create a new user for debug purposes, open the rails console with rails console then enter

user = User.create(
    email: "mail@example.com", 
    full_name: "Max Mustermann", 
    description: "A nice student!", 
    password: "ThisIs_My!Super#Secure/Pw")

Any errors during creation are logged to user.errors (password length, special characters).