Skip to content

Latest commit

 

History

History
130 lines (77 loc) · 6.66 KB

CONTRIBUTING.MD

File metadata and controls

130 lines (77 loc) · 6.66 KB

Contributing

First of all, thank you for considering fixing or improving Avo. This is a community project, and all your contributions are most welcomed.

If you came across a bug or want to suggest a feature, feel free to say something!

If you'd like to contribute code, the steps below will help you get up and running.

Elements naming

Resource or @resource is an instantiated Avo::Resource object.

resource_name: Pluralized, machine name, snake-cased version of a resource. Ex: resource_name for /avo/resources/team_memberships path is going to be TeamMemberships.

Model or @model: Active Record Model object.

Since v 1.20 (Jan 2022), we started to change the model name with record where it fits. So the model should be the class (ex: User, Comment, etc.), and record will be the instantiated model class with data (ex: user is a record when doing user = User.find(1)).

Forking & branches

Please fork Avo and create a descriptive branch for your feature or fix. We usually use the feature/, chore/, or fix/ branch prefixes. This way, the PR gets automatically labeled.

Contributing with Pull Requests

Thank you for considering to contribute to Avo. These are our recommendations to improve readability and interoperability when contributing with a PR:

  • the title should have the type (feature, chore, fix, refactor) followed by the sentence case of what it does (ex: feature: scoped search for has many associations or fix: broken sidebar on desktop).
  • the PR should be marked by the appropiate tag (feature, chore, fix, refactor)
  • if there's an issue open that could be fixed by this PR you can mark it by writing Fixes ISSUE_URL in the description so GitHub automates some actions (ex: Fixes https://github.com/avo-hq/avo/issues/1008). If there are more issues that could be fixed, add more lines.
  • please follow the steps on the Checklist and mark them as done with an x inside the brackets [x]
  • if there's something that we can test, please send us the instructions to do that in that PR description.
  • ask for help navigating the codebase. We love it when you do!
  • enjoy the process and the thing you are making, fixing, or improving.

Thank you!

Getting your local environment set up

NOTE: We're using docker-compose to run Postgres. While we find this incredibly helpful, it's not a requirement, but you'll have to BYOD (Bring Your Own Database).

Once you pull the code down to your machine, modify spec/dummy/config/database.yml as appropriate to your environment (no changes needed if you're using Docker). Do not commit these changes. From here, running bin/init will get you up-and-running.

Local development

Running the dummy app

You can run bin/dev from the root directory, which will start an overmind (similar to foreman) process for the rails server, jsbundling and cssbundling. Then, navigate to localhost:3030 and enjoy the app.

Seeding the database for local development

Run AVO_ADMIN_PASSWORD=secret bin/rails db:seed to seed the database with dummy data and create a user for yourself with the email [email protected] and password secret.

Using your fork from another project

You may want to evaluate your changes in the context of an actual project. Follow these instructions to do so without publishing your own version of the gem.

In the other project, change the Gemfile entry for avo to point to your local clone of this repo. For example:

gem 'avo', path: '../avo'

Avo's assets will not show up by default, resulting in 404 errors on /avo-assets/avo.base.js and /avo-assets/avo.base.css. To avoid this, you need to compile the asset bundles, and symlink them into public/avo-assets.

Create symlinks for compiled assets into the public directory. You'll only need to do this once.

# `cd` into the root directory of this project.
ln -sf $(pwd)/app/assets/builds/avo.base.js public/avo-assets/avo.base.js
ln -sf $(pwd)/app/assets/builds/avo.base.css public/avo-assets/avo.base.css

After that, you'll need to compile the asset bundles any time you make changes to the JS or CSS code:

yarn build

Running tests

When running tests, you have two options.

  1. running them on your local database
  2. to use a database in a docker environment.

Run the migration script bin/rails db:migrate. Now you'll be able to run the test scripts below:

Running tests with local database

Copy the .env.test.sample (cp spec/dummy/.env.test.sample spec/dummy/.env.test) and update it with the proper credentials for your local database. Run the migration script bin/rails db:migrate. Now you'll be able to run the test scripts below:

We've set up a few helpers to get you going:

  • Run all tests (slow): bin/test
  • Run unit tests (fast): bin/test unit
  • Run system tests (slow): bin/test system
  • Run a particular spec file/test (fast): bin/test ./spec/features/hq_spec.rb

Running tests using the docker container

You may want to run the tests on your docker container. To do that, update your .env.test file with valid credentials for the docker setup like below. We do provide a docker-compose.yml file for the testing DB, so you can do docker compose up, but that's not our preferred method, and you might need to do some tweaks. You'll then be able to run the migration script and the testing commands.

POSTGRES_HOST=localhost
POSTGRES_PORT=5433
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=

Release details

Update appraisal gemfiles

We use appraisal to run tests against multiple versions of Rails. When the gemfile gets updated, you must also run bundle exec appraisal install to update the versioned ones and commit them to the repo.

Please read the RELEASE.MD for release schedules.

Custom JS

To test the custom Stimulus integration, we need to have some JS content injected into the dummy app. We also need not to have that content present in every Avo installation. That's why we ejected the _head.html.erb partial that loads the avo_custom.js file from the engine's build directory. The build directory is not committed to git, so we're all good on that. To have that file built and watched, we use a cjs (short for custom-js) process in the Procfile.dev (used only in development).

Misc

Annotate models

To keep track of the schema structure for the models, run annotate --models --exclude fixtures in the dummy app.

Using VSCode?

We compiled an extension pack with a few extensions that should help you with Ruby development. We use them with Avo.