Skip to content
This repository has been archived by the owner on Mar 26, 2022. It is now read-only.

Latest commit

 

History

History
101 lines (73 loc) · 5.88 KB

CONTRIBUTING.md

File metadata and controls

101 lines (73 loc) · 5.88 KB

Contributing guideline

The basics

We use the Laravel framework, 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

Universal (using VS Code dev containers - recommended)

  1. You need to install Docker (and WSL2 on Windows). See requirements here.
  2. You need to install VS code
  3. You need to install the Remote Development extension pack in VS code.
  4. Clone Mars and open the project: git clone git@github.com:luksan47/mars.git.
  5. VS code will notice that the project is configured to use dev containers and will promt you if you want to use it. Click yes, and you're all done!

OS X

For OS X, Valet gives a pretty smooth experience. Easy to download, easy to configure.

Windows and Linux

For Windows and Linux the project has an example Laravel Homestead configuration which can be used for local development.

With these steps you should be able to run Mars on your machine:

  1. Clone Mars: git clone git@github.com:luksan47/mars.git.
  2. Install Vagrant and VirtualBox. (Or other virtualization platforms supported by Vagrant. Don't forget to reconfigure the provider in the steps below if you do so.)
  3. Follow the instructions in the First steps section:
    • vagrant box add laravel/homestead
    • git clone https://github.com/laravel/homestead.git from a folder where you want to set up Homestead
    • go into this new directory
    • git checkout release
    • init.bat (bash init.sh on Linux)
  4. Set up Homestead: Copy and rename Homestead.yaml.example from this repository to Homestead.yaml in the Homestead directory (overwrite if needed). Modify this file by changing folders: - map: /your/local/path/to/mars .
  5. Create ssh keys to ~/.ssh/homestead_rsa.pub and ~/.ssh/homestead_rsa. (You can use something like ssh-keygen -t rsa -b 4096 -C "your_email@example.com".)
  6. On Windows add the 192.168.10.10 mars.local host entry to C:\Windows\System32\drivers\etc\hosts.
  7. Go to your Homestead directory and Run vagrant up and vagrant ssh to set up and enter your virtual machine.
  8. In the project root (cd mars) run composer install
  9. Set up Mars: Copy and rename .env.example to .env, and change these settings: DB_DATABASE=homestead DB_USERNAME=homestead DB_PASSWORD=secret APP_URL=http://mars.local.
  10. Run the following commands:
  • Run php artisan migrate:fresh --seed.
  • Run php artisan key:generate.
  • Run npm install to install JS related dependencies.
  • Run npm run dev to create the CSS and JS files in the public directory.
  1. The project should be running at mars.local.

Optional steps

  • You can add your personal access token from GitHub to use the GitHub API (eg. bug reports are sent through this). You can generate a token here. You have to check the 'public_repo' scope.
  • If you want to test emails, change MAIL_TEST_ADMIN to your email (after seeding, you will be able to log in to the admin user with this email address) and set your email credentials (MAIL_USERNAME and MAIL_PASSWORD) - you might have to enable third party access to your email account.

For everyday use

Most of the above setup is a one-time thing to do. However, whenever you start working on based on a newer version, you will have to run the following commands:

  • npm run dev: In case of recent UI changes (ie. JS or CSS), this will generate the new assets from webpack.mix.js. For frontend developers, npm watch might be useful -- it does the same, but also updates on change.
  • php artisan migrate:fresh --seed: This will migrate everything from scratch (useful if you work on changes in parallel) and seeds the database.

You can log in to our seeded admin user with email MAIL_TEST_ADMIN (example@eotvos.elte.hu by default - you can find this in your .env file) and with password asdasdasd. See database/seeds/UsersTableSeeder.php for more predefined users.

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 minial, 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.

# 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.)