Skip to content

subtitulamos/subtitulamos

Repository files navigation

Contributing

Thanks for your interest in helping out! In order to be able to contribute, you will need an environment in which to develop. A detailed setup is provided below.

What can I contribute to?

You're free to contribute to any open issue that's not being tackled by anyone at the moment. However, if there's not a specific issue for the thing you want to make, make sure to open an issue or create a thread in the forums first to verify it's something that the community is interested in! Also, when contributing, please follow the contribution rules:

Contribution rules

  • Format the code using php-cs-fixer before creating a pull request. The rules are shipped with the code, on the php-cs.dist file that PHP-CS-Fixer will automatically pick up.
  • The whole codebase is in english: please use english variable names/comments/commit messages and whatnot.

Development Setup

First-time setup

  1. Clone the repo locally
  2. Copy the .env.example file on the project root to .env
    • If needed, modify its contents to the ones correct for your usecase. The defaults should work fine.
  3. Install Docker, if you don't have it (https://www.docker.com/get-started)
  4. Install NodeJS 12.x, if you don't have it (https://nodejs.org/download/release/latest-v12.x/)
    • Higher versions might work, too
  5. Run npm install from the directory src/subtitulamos
  6. Execute ./dev.sh on the repository root from a Linux shell (if you're on Windows, Git Bash should be available if you installed Git). This command will
    • build & start all the necessary Docker containers
    • start a webpack watcher that builds all the CSS/JS in the page any time it changes
  7. You're done!! You can access a subtitulamos instance at http://localhost:8080.
  8. You can log in as user root, with password root

After this first setup, any time you want to start subtitulamos, just run ./dev.sh!

Nice to have: Proper IDE completion

With the basic setup above, you will be able to run a local server of subtitulamos, including all of its dependencies.

If you would like proper code intelligence in your IDE, you will need to either run your IDE inside the Docker container (for example, VSCode's "Developing inside a Container"), or install PHP & Composer locally.

The 2nd option might be easier:

  • Install PHP
    • On Windows, an easy install can be achieved using XAMPP. However, it'll install a bunch more things you might not want (like a local MySQL server). For a plain PHP install, just head over to the PHP Windows Downloads, download a compiled version (e.g VC15 x64 Thread Safe), extract it and add it to your PATH.
  • Install Composer
  • After that, run composer install on the src/subtitulamos directory. Done!

Architecture

Software used

  • PHP 7.4
  • MariaDB 10.4
  • nginx + php7.4-fpm
  • Redis
  • MeiliSearch

Development

Altering the database model

Steps:

  1. To add new columns to a table, simply edit the model files inside [src/subtitulamos/]app/Entities, adding new private field(s) with the @ORM annotation (see the Doctrine docs for details on the annotations).
    • If what you'd like is to create a new one, you can also just create a new file in that directory, following the correct annotations (look at other files for reference)
  2. Create any necessary functions to read from/update the fields
  3. Create a databse migration for this change: docker container exec -it subs_phpsv ./vendor/bin/doctrine-migrations diff.
  4. Open the autogenerated file under app/Migrations/ and tweak it as necessary.
  5. Restart your PHP container to get the migration executed and applied to your database (e.g docker-compose down & docker-compose up), or run docker container exec -it subs_phpsv ./vendor/bin/doctrine-migrations migrate --no-interaction.

Clearing Twig cache

If you're not running on DEBUG mode, you will need to clear the Twig cache for the server to pick up changes to templates. Run docker container exec -it subs_phpsv ./app/console app:twig:clear-cache