diff --git a/README.md b/README.md index c19bcb833b..03b08b4d36 100644 --- a/README.md +++ b/README.md @@ -12,30 +12,32 @@ EvaP is the course evaluation system used internally at Hasso Plattner Institute For the documentation, please see our [wiki](https://github.com/e-valuation/EvaP/wiki). -## Installation +## Installation (for Development) The easiest setup using [Vagrant](https://www.vagrantup.com) is shown here. -0. Install [git](https://git-scm.com/downloads), [Vagrant](https://www.vagrantup.com/downloads.html), and one of [VirtualBox](https://www.virtualbox.org/wiki/Downloads) (recommended) or [Docker](https://docs.docker.com/engine/install/) (for ARM systems). - -1. Fork the EvaP repository (using the Fork-button in the upper right corner on GitHub). +1. Install [git](https://git-scm.com/downloads), [Vagrant](https://www.vagrantup.com/downloads.html), and one of [VirtualBox](https://www.virtualbox.org/wiki/Downloads) (recommended) or [Docker](https://docs.docker.com/engine/install/) (for ARM systems). 2. Run the following commands on the command line to clone the repository, create the Vagrant VM and run the Django development server. - * Windows users: We have observed [weird](https://github.com/hashicorp/vagrant/issues/9143#issuecomment-401088752) [behavior](https://github.com/git-for-windows/git/issues/3657) with ssh in Git Bash on Windows and thus recommend using PowerShell instead. In theory, you should be able to use any command line tool. + * If you are familiar with the fork-based open source workflow, create a fork and clone that (using SSH if you prefer that). + + * Windows users: We have observed [weird](https://www.github.com/git-for-windows/git/issues/4705) [behavior](https://www.github.com/git-for-windows/git/issues/4704) with ssh in Git Bash on Windows and thus recommend using PowerShell instead. * To use Docker, replace `vagrant up` with `vagrant up --provider docker && vagrant provision`. ```bash - git clone --recurse-submodules https://github.com//EvaP.git + git clone --recurse-submodules https://github.com/e-valuation/EvaP.git cd EvaP vagrant up vagrant ssh + ``` + and, after the last command opened a ssh session in the development machine: + ```bash ./manage.py run ``` 3. Open your browser at http://localhost:8000/ and login with email `evap@institution.example.com` and password `evap`. - That's it! ## Contributing @@ -51,6 +53,22 @@ or, to combine all three, simply run `./manage.py precommit`. You can also set up `pylint`, `isort`, `black` and `prettier` in your IDE to avoid doing this manually all the time. +### Creating a Pull Request (Workflow Suggestion) +0. (once) [Fork](https://github.com/e-valuation/EvaP/fork) the repository so you have a GitHub Repo that you have write-access to. + +1. (once) Set up some Authentication for GitHub that allows push access. A common option is using [SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh), the remaining instructions assume an SSH key setup. An alternative is using the [GitHub CLI tool](https://cli.github.com/). + +2. (once) Ensure your [git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) are setup to use SSH. To fetch the up-to-date state of the official repo, it's always useful to have an "upstream" remote configured: + ```bash + git remote set-url origin git@github.com:/EvaP.git + git remote add upstream git@github.com:e-valuation/EvaP.git + ``` + +3. Create a branch (`git branch -c `), commit your changes (`git add` and `git commit`), and push them (`git push`). "Push" will ask you to specify an upstream branch (`git push -u origin `). + +4. GitHub should now ask you whether you want to open a Pull Request when reloading the page. If the PR solves an issue, use one of GitHub's [magic keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) (like "fixes") to create a link between your PR and the issue. + + ## License MIT, see [LICENSE.md](LICENSE.md).