astuto/CONTRIBUTING.md

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: the main locale file. Contains translation strings for the frontend, backend, mailers, etc.
• activerecord/activerecord.[lang].yml: contains Rails ActiveRecord translations, i.e. translations for model names, properties and validation error messages.
• devise/devise.[lang].yml: contains translations for the authentication system (which is based on Devise gem). It is likely that you'll find ready-made translations for your language at this page, so this step usually consist in a simple copy-paste!

Coding and testing

First of all, you need to follow the installation instructions to have a working local instance of Astuto.

Technologies

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

• Ruby on Rails: Ruby framework for the backend
• React: UI library used for most of the frontend views
• Redux: state management library for React
• TypeScript

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

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.