From d8d782154f168b7efd85ceb6331d5c004b0c3ba6 Mon Sep 17 00:00:00 2001
From: Manfred Brandl <manfred@brandl.net>
Date: Mon, 20 Aug 2018 10:41:47 +0000
Subject: [PATCH] Add Using GitHub and Git

---
 CONTRIBUTING.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d43a07547..64ea71ba9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -366,3 +366,47 @@ The `iD.js` and `iD.min.js` files in this project are autogenerated - don't edit
 2. Run lint and tests with `npm test`
 3. Commit your changes with an informative commit message
 4. [Submit a pull request](https://help.github.com/articles/using-pull-requests) to the `openstreetmap/iD` project.
+
+## Using GitHub and git
+
+If you are new to GitHub or git you can read the [GitHub Guides](https://guides.github.com)
+"Understanding the GitHub Flow", "Git Handbook" and "Forking Projects" could be especially intresting to you.
+
+## Step by Step
+
+Addtionaly here is a step-by-step workflow example for beginners:
+
+1. [Login](https://github.com/login) to your GitHub account or [create](https://services.github.com/on-demand/intro-to-github/create-github-account) a GitHub account, if you do not already have one.
+
+2. Go to the [iD main repository](https://github.com/openstreetmap/iD) and fork iD into your GitHub account (Fork is top right).
+
+3. Set up [Git](https://help.github.com/articles/set-up-git/) and prepare for Authenticating with GitHub from Git.
+
+4. Clone or download your local copy of iD from your GitHub account using https `git clone https://github.com:<yourgithubaccount>/iD.git` or using ssh `git clone git@github.com:<yourgithubaccount>/iD.git`. In your local copy you'll have a "remote" called origin.
+
+5. Switch to the iD directory, create a working branch (choose a descriptive name) and switch to it : `cd iD ; git checkout -b <working-branch-name>`. Never do anything in master branch.
+
+6. Edit file(s) and try your change locally (See above).
+
+7. Add Files and commit them `git add <files> ; git commit -m "Description of what you did"` .. repeat repeat as needed..
+
+8. Push Changes to your GitHub account `git push --set-upstream origin master`
+
+9.  Go to GitHub for your fork of iD at https://github.com/<yourgithubaccount/iD. GitHub will already know about your recently pushed branch, and ask if you want to create a Pull Request for it.
+
+10. Your Pull Request will be seen by the maintainers of iD. They can merge it or ask for changes. You can update your Pull Request with Steps 7 and 8, Step 9 is only required once once per Pull Request.
+
+## Clean Up
+
+After your Pull Request gets merged into the main repository
+you can clean up by deleting the branch from your Github-iD-Clone and your local directory
+
+`git push --delete origin <branch_name> ; git branch -d <branch_name>`
+
+## Restart with another PR after some while
+
+If you did not use your copy of iD for some while, other Pull Request gets merged and you dont have the latest version of iD. You can replace your master with whatever is in our master. If you have not done so yet: Add the main repo as an "upstream" remote:
+`git remote add upstream git@github.com:openstreetmap/iD.git`
+Then change to the master branch and get everything from upstream (the main repository)
+`git checkout master ; git fetch --all && git reset --hard upstream/master`
+