Skip to content

Latest commit

 

History

History
86 lines (60 loc) · 5.93 KB

CONTRIBUTING.md

File metadata and controls

86 lines (60 loc) · 5.93 KB
Raw

Contributing guidelines

Thanks for taking the time to contribute 😁

We would like the Astuto community to be a welcoming environment for both seasoned programmers and absolute beginners. The following guidelines should help you get started regardless of your skill level.

How to contribute

There are many ways to contribute to Astuto, not just coding. In this section we list the most common ones:

  • Getting involved in the community: we love to hear opinions about our product. Dropping a comment on an open issue or pull request or joining the discussion on the Discord server is an easy yet impactful way to contribute.
  • Reporting bugs or proposing features: open a new issue on GitHub. Before posting, check if a similar issue has already been reported. Try to be concise but also unambiguous.
  • Translating Astuto into a new language: we want Astuto to speak all languages and we need contributors to achieve this goal! If you're interested, join our Crowdin project, the platform we use to manage translations.
  • Coding: open a pull request with your bug fix or feature implementation. Before diving into coding, you may find the coding and testing section useful.

If you still have any doubt, feel free to join our Discord and drop a message! And remember: there are no stupid questions 😉

Translations

If you're interested in translating, we suggest to visit and register to our Crowdin project, the place where we manage translations. If the language you want to contribute is not present in Crowdin, just open an issue on GitHub and let us know!

Translations structure

Locales are stored in YAML files under config/locales. Translations are splitted in 3 files:

  • [lang].yml: contains frontend translations
  • backend/backend.[lang].yml: contains backend translations, e.g. mailers, error messages, entity names
  • devise/devise.[lang].yml: contains translations for the authentication system (which is based on Devise gem). Usually, this file is not manually translated, because ready-made translations are already available at this page.

Coding and testing

Installation instructions for contributors

In order to contribute to Astuto, you need to run Astuto on your computer in development mode. In order to do so, please follow these instructions:

  1. Ensure you have Docker and Docker Compose installed
  2. Clone this repository
  3. Edit docker-compose.yml if you want to change the value of some environment variables. Note that this docker-compose.yml is already configured to run Astuto in development mode (target: dev).
  4. Run docker compose build
  5. Run docker compose up
  6. You should now have a running instance of Astuto at localhost:3000. A default user account has been created with credentials email: admin@example.com, password: password.

Technologies

Depending on the task you're working on, you need to know one or more of these technologies:

Project structure

The project is broadly structured as follows:

  • app
    • models: Rails ActiveRecord models. These models are mapped by ActiveRecord to database tables.
    • controllers: Rails controllers. Web requests will be handled here. Here you can query the database, return HTML/JSON, etc. We try to keep controllers as small as possible.
    • views: Rails views. Some of these views render HTML directly, whereas others render React components. Ideally, we'd like to move the entire frontend to React.
    • javascript
      • actions: Redux actions
      • components: React components
      • containers: React components that connect to Redux state. See this article to learn more.
      • reducers: Redux reducers
      • stylesheets: all CSS files are stored here
    • mailers: mail templates that are sent to notify users
    • workflows: classes that contains some complex logic. Usually that logic was originally in a controller, but has been refactored and delegated to a workflow. In fact, workflows are usually called inside controllers.
    • policies: policies used by Pundit for resource authorization
  • config
    • locales: locales files for internationalization. See this section for additional information.
    • routes.rb: backend routes, i.e. mapping requests to controller actions
  • db
    • migrate: contains migration files
    • schema.rb: database schema
  • spec: RSpec tests

Rails console

If you need to work with the Rails console, just attach a shell to the web container. From there, type rails c to run the console. You may notice that every query you run (e.g. Post.all) fails with error Current::MissingCurrentTenant (Current tenant is not set): that's because Astuto implements multi tenancy at the database level. In order to fix this error, supposing you're in single tenant mode, just run Current.tenant = Tenant.first as the first command inside the Rails console. After that, everything should work as expected.

Specs (tests)

Tests are done using RSpec, a testing framework for Ruby on Rails:

  • To execute all specs, run rspec command inside the web container. System specs relies on Google Chrome to run, so you may need to rebuild Astuto image uncommenting lines 9-11 in Dockerfile.
  • If you want to run all specs except for system specs, you can run the script script/rspec-no-system-specs.sh.