diff --git a/_BEGINNER_GUIDE.md b/_BEGINNER_GUIDE.md new file mode 100644 index 000000000..c4f506d3c --- /dev/null +++ b/_BEGINNER_GUIDE.md @@ -0,0 +1,21 @@ +## Beginner guide +Note: update the laravel docs references to the currently used version (see "laravel/framework" in `composer.json`) + +The basic things you will need as a beginner: +- Controllers: `app/Http/Controllers` - the main functionalities of the backend +- Database: + - [Migrations](https://laravel.com/docs/8.x/migrations): `database/migrations` - the database structure can be modified with migrations + - [Seeders](https://laravel.com/docs/8.x/seeding): `database/seeders`, `database/factories` - the database can be seeded with dummy data which are set in factories + - Read the [documentation of queries](https://laravel.com/docs/8.x/queries) to understand how to insert/update/delete data in the database. Laravel also has [particular functions for inserting and updating models](https://laravel.com/docs/8.x/eloquent#inserting-and-updating-models). The queries will mostly return [Collections](https://laravel.com/docs/8.x/collections), which are similar to arrays but with custom functions. +- [Models](https://laravel.com/docs/8.x/eloquent): `app/Models` - the database is mapped to php classes using Models (ORM - Object Relational Mapping). Models are the main way to interact with the database. To create Models, use `php artisan make:model ModelName -a` to generate the model and a corresponding controller, factory, etc. Also take a look at [Relationships](https://laravel.com/docs/8.x/eloquent-relationships) to define relations between Models. +- Routes: `routes/web` - to map the requests from the browser to controller functions +- Frontend: `resources/views` - the webpage is generated from these blade files. To return a webpage, use `return view('path.to.view', ['additional_data' => $data, ...]);`. Blade files are html codes with [additional php functionalities](https://laravel.com/docs/8.x/blade#blade-directives): loops, variables, etc. Writing `{{ something }}` is equivalent to php's print: `echo something;`. When writing forms, add `@csrf` to the form for security reasons (without it, the request will not work). Blade files can also be nested, included, etc (eg. `@include('path.to.file'))`). Our front-end framework is [Materialize](https://materializecss.github.io/materialize/). +- Language files: `resources/lang` - to translate the webpage. Use `__('filename.key')` in the backend and `@lang('filename.key')` in blades. To add variables: `__('filename.key', ['variable' => 'value'])`, prefix the variable name with `:` in the language files. +- Validation: It is recommended to validate every user input: for example, in the controller: `$request->validate(['title' => 'required|string|max:255']);`. [Available validation rules](https://laravel.com/docs/8.x/validation#available-validation-rules). +- Debugging: log files: `storage/logs/laravel.log` - use `Log::info('something happened', ['additional_data' => $data])` to log (also: error, warning, etc.). Alternatively, in the controllers, you can type `return response()->json(...);` to print something in the browser. In blades, type `{{ var_dump($data) }}` to display some data. It is worth to take a look at the [query debugging options](https://laravel.com/docs/8.x/queries#debugging) also. + +You can use `php artisan db` command to enter into the database directly or `php artisan tinker` to get a runtime laravel evaluation tool. + +## Official documentations +- [Laravel](https://laravel.com/) +- [Materialize](https://materializecss.com/) diff --git a/CODE_OF_CONDUCT.md b/_CODE_OF_CONDUCT.md similarity index 100% rename from CODE_OF_CONDUCT.md rename to _CODE_OF_CONDUCT.md diff --git a/_CONTRIBUTING.md b/_CONTRIBUTING.md new file mode 100644 index 000000000..1084acf0d --- /dev/null +++ b/_CONTRIBUTING.md @@ -0,0 +1,28 @@ +# Contributing guidelines + +## Official documentations +- [Laravel](https://laravel.com/) +- [Materialize](https://materializecss.com/) + +## Simple git usage + +```bash +# when you start working +git checkout master +git pull +git checkout -b your_feature_branch + +# add your changes + +# when you are done +git add --all # or only your changes +git commit # an editor comes up, the first line should look like: Issue #x: changed this and that +# add more information if needed +git fetch origin +git rebase origin/master # resolve conflicts if something comes up +git push origin your_feature_branch + +# open repo in your browser and you should see a Create PR option. +``` + +## More guidelines will come here... diff --git a/CONTRIBUTING.md b/_SETUP_DEV_ENVIRONMENT.md similarity index 78% rename from CONTRIBUTING.md rename to _SETUP_DEV_ENVIRONMENT.md index cd9a1d119..ad85420c1 100644 --- a/CONTRIBUTING.md +++ b/_SETUP_DEV_ENVIRONMENT.md @@ -1,12 +1,7 @@ -# Contributing guideline -## The basics +## Development environment -We use the [Laravel framework](https://laravel.com/), to learn more about it, read the basics section of its documentation. -It's also good to check out the previous commits, to see how to implement that part or that. Might seem a lot first, but it's really easy, -thanks to Laravel. - -## Development +There are several ways to set up your development server and environment. Basically, you only need a running php server that uses the /public folder and an sql database connected to it. There are some tips how to achieve that (and even more) below. ### Developing on the cloud with gitpod (for starters or for slow machines) @@ -102,40 +97,3 @@ docker exec -it mars-mysql-1 mysql --password -e "SET GLOBAL log_bin_trust_funct 9. Now you can test the site at `http://localhost:8080`. 10. Instead of SSH, you can use `docker exec -it mars-laravel.test-1 bash`. 11. And to access MySQL, run `docker exec -it mars-mysql-1 mysql --user=mars --password mars` (change the container name, the username and the database name if needed; the latter two are in .env) and log in with the password (also found in .env). - -## Keep it minimal - -The main problem with Urán 1.1 was its _reinventing the wheel_ strategy. Laravel provides everything we need. Use it. -The other problem was the unnecessary features came before the most important ones. Therefore the now defined issues are minimal, only -contain the necessary parts of the system. After these are done, we can change the world. But first, build it. - -## Commiting - -When you would like to make some change, assign an issue to yourself, only after that start working on it. -If there's no issue, create one, but remember the paragraph above. Keep it minimal. If something's not clear, ask your questions under the issue. -Feel free to create your own branch (if you are a contributor), or fork the repo. -When you are done with your changes, the commit message should be the Issue's title and it should be sent through a -Pull Request. Also, feel free to review already sent in changes. E.g. - -```bash -# when you start working -git checkout masteryour_feature_branch -git pull -git checkout -b your_feature_branch - -# add your changes - -# when you are done -git add --all # or only your changes -git commit # an editor comes up, the first line should look like: Issue #x: changed this and that -# add more information if needed -git fetch origin -git rebase origin/master # resolve conflicts if something comes up -git push origin your_feature_branch - -# open repo in your browser and you should see a Create PR option. -``` - -## Got any questions? - -Find me, or write a mail to root at eotvos dot elte dot uh. (Last two letteres reversed.)