Are you interested in giving a hand? We can't be more excited about it. Thanks in advance!
Notes:
Here are some guidelines that could help you to get started quickly.
The best way to contribute to Monica is to use Homestead as a development environment, which is an official, pre-packaged Vagrant box that provides you a wonderful development environment without requiring you to install PHP, a web server, and any other server software on your local machine. The big advantage is that it runs on any Windows, Mac, or Linux system.
This is what is used to develop Monica and what will provide a common base for everyone who wants to contribute to the project. Once Homestead is installed, you can pull the repository and start setting up Monica.
Note: the official Monica installation uses mySQL as the database system. While Laravel technically supports PostgreSQL and SQLite, we can't guarantee that it will work fine with Monica as we've never tested it. Feel free to read Laravel's documentation on that topic if you feel adventurous.
We've installed the development version with Valet, which is a Laravel development environment for Mac minimalists. It works really well and is extremely fast, much faster than Homestead.
Prerequisites:
Steps to install Monica
Once the above softwares are installed (or if you've finished the installation of Homestead/Valet):
monica
in your mySQL instance.
sudo scripts/create-mysql.sh monica
or mysql -e "CREATE DATABASE 'monica'";
inside mySQL.vagrant ssh
will let you login as root inside your VM.make install
in the folder the repository has been cloned. This will run :
cp .env.example .env
to create your own version of all the environment variables needed for the project to work.composer install --no-interaction --no-suggest
to install all packages.yarn install
to install all the front-end dependencies and tools needed to compile assets.yarn run dev
to compile js and css assets.php artisan key:generate
to generate an application key. This will set APP_KEY
with the right value automatically.php artisan setup:test
to setup the database.
--skipSeed
option to skip the process of adding fake data in your dev environment.php artisan passport:install
to create the access tokens required for the API (Optional)..env
to your specific needs.If you haven't skipped the seeding of fake data, two accounts are created by default:
admin@admin.com
with the password admin
. This account contains a lot of fake data that will let you play with the product.blank@blank.com
with the password blank
. This account does not contain any data and shall be used to check all the blank states.To update a current installation with the latest dependencies, just run make update
to run
composer install --no-interaction --no-suggest
yarn upgrade
yarn run dev
php artisan migrate
We try to cover most features and new methods with unit and functional tests. Any pull request submitted on GitHub will have to go through Travis and pass before being merged. Moreover, we strongly encourage adding unit tests for every new method added to the codebase to ensure code stability, and we will probably refuse a pull request if there is no tests for it.
To setup the test environment:
monica_test
php artisan migrate --database testing
php artisan db:seed --database testing
The test suite uses Phpunit. It's mainly used to perform unit tests or quick, small functional tests.
To run the test suite:
phpunit
or ./vendor/bin/phpunit
in the root of the folder containing Monica's code from GitHub.Browsers tests simulate user interactions in a live browser.
curl -sS -o - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt -y update
sudo apt -y -f install google-chrome-stable fonts-liberation libappindicator1
php artisan dusk
You should never make real HTTP calls in your unit tests - like querying an external API that is not linked to Monica.
You can mock http calls by mocking calls made by Guzzl.
You can find an example of how mocking is done in the GetWeatherInformationTest.php
file.
You need to provide a sample response of the external call that you are mocking in the Fixtures folder.
We follow GitHub Flow to manage the development of features.
We follow the conventional commit message syntax for our commits. For instance, feat: allow provided config object to extend other configs
or feat(lang): added polish language
.
Every feature branch that is squashed onto master must follow these rules.
The benefits are:
The keywords that support (heavily inspired by config-conventional):
ci
,chore
,docs
,feat
,fix
,perf
,refactor
,revert
,style
,test
.Moreover, every commit message needs to be written in lowercase.
All the commits in a pull request are squashed when merged into master. That means only the commit message of the squashed branch needs to follow this commit message convention. That also means that you don't need to follow this convention for commits within a branch, which will usually contains a lot of commits with a wip
title.
The project follows strict object calisthenics, as much as possible and more and more over time. We will soon implement those rules in the Linters and will block a pull request for the code that does not follow those guidelines. Here are the rules (adapted for PHP):
If you add a new table, make sure there is a column called account_id
in this new table. That way, we will make sure that the script responsible for resetting or deleting a user account will go take this new table into consideration while running.
Sometimes you need to manipulate and move data around when you decide to change the database structure. In that case, as much as possible, do not use Eloquent to change the data. Use either raw SQL queries or the Query builder to do it. This is due to the fact that objects might change overtime or even be deleted, which would break the migrations entirely.
Emails are an important part of Monica. Emails are still the most significant mean of communication and people like receiving them when they are relevant. That being said, you will need to test emails to make sure they contain what they should contain.
For development purposes, you have two choices to test emails:
brew install mailhog
). Then, run mailhog
and point the browser to http://127.0.0.1:8025
(more complete instructions).sudo service mailhog restart
) inside your Vagrant. Then, head up to http://localhost:8025 in your local browser to load Mailhog's UI.Note: if you want to use mailhog, you need the following settings in your .env
file:
MAIL_DRIVER=smtp
MAIL_HOST=0.0.0.0
MAIL_PORT=1025
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=
Monica sends two types of emails: reminders, and notifications. Notifications are sent 7 and 30 days before an event happens, while reminders are sent the day the event happens.
Reminders are generated and sent using an Artisan command send:reminders
. Notifications are sent using send:notifications
. Those commands are scheduled to be triggered every hour in app/console/Kernel.php
.
Monica calculates every night (ie once per day) a set of metrics to help you understand how the instance is being used by users. That will also allow to measure growth over time.
Statistics are generated by the Artisan command monica:calculatestatistics
every night at midnight and this cron is defined in app/console/Kernel.php
.
As said above, Monica uses mySQL by default. While Laravel supports multiple DBMS, we can't assure you it will work with any other DBMS than mySQL.
If you want to connect directly to Monica's MySQL instance read Connecting to MySQL inside of a Docker container.
The above comments can seem harsh and we apologize in advance. However you have to understand that we deeply care about providing the best user experience to our users. Features that are purely backend do not have the same impact as the ones that the user interacts with. Features that modify the front end will have a tremendous impact on how users perceive the software. Therefore we want to make sure that anything that touches the frontend is perfect and aligned with our vision.
We use mix to manage the front-end and its dependencies, and also to compile and/watch the assets. Please note that we should do our best to prevent introducing new dependencies if we can prevent it.
Mix should be available in your development environment if you have installed Monica locally and ran yarn install
in the first place.
If you need to add a new dependency, update package.json
to add it and make sure you commit package-lock.json
once package.json
is updated.
CSS is written in SASS and therefore needs to be compiled before being used by the application. To compile those front-end assets, use yarn run dev
.
To monitor changes and compile assets on the fly, use yarn run watch
.
At the current time, we are using a mix of Bootstrap 4 and Tachyons. We aim to use Atomic CSS instead of having bloated, super hard to maintain CSS files. We'll get rid of Bootstrap entirely over time.
This means that we should add new CSS classes only if it's absolutely necessary.
We are using Vue.js in some parts of the application, and we'll use it more and more over time. Vue is very simple to learn and use, and with Vue Components, we can easily create isolated, reusable components in the app. If you want to add a new feature, you don't need to use Vue.js - you can use plain HTML views served by the backend. But with Vue.js, it'll be a nicer experience.
Localization of the application is handled by the default i18n helper provided by Laravel. When adding or modifying strings, you only have to handle the en
language, which is stored in resources/lang/en/
. The other locales are going to be handled by Crowdin, our translation platform.
We also have a dedicated page for our translators, just in case you need it.
We use the default Laravel helper: trans('app.save')
.
For everything that is in VueJS though, things are a bit different. We have to use a special library to allow translated strings to be available in the javascript views. The helper in Vue is slightly different.
You can use these replacements instead of the regular (php) definition:
trans('file.string')
is writen $t('file.string')
.trans('file.string', ['param' => $value])
is writen $t('file.string', {param: value})
.trans_choice('file.string', $count)
is writen $tc('file.string', count)
.Important note: every time a string changes in a translation file, you need to regenerate all the strings so they can be made available in JS. To do this,
php artisan lang:generate
yarn run prod
, and commit the whole.此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。