README.md: Separate quick-setup and push-ready forked setup

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/<your_github_username>/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 `[email protected]` 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 [email protected]:<your-username>/EvaP.git
+   git remote add upstream [email protected]:e-valuation/EvaP.git
+   ```
+
+3. Create a branch (`git branch -c <your-branch-name>`), 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 <your-branch-name>`).
+
+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).