contributing.md: update git instructions

CONTRIBUTING.md

@@ -58,31 +58,83 @@ maps), `time/`, `os/`, etc. Their documentation is pretty clear.
 username will be referred to later as 'YOUR_GITHUB_USERNAME'. Change it
 accordingly in the steps below.)
 
-1. Clone https://github.com/vlang/v in a folder, say nv (`git clone
+1. Fork https://github.com/vlang/v using GitHub's interface to your own account.
-https://github.com/vlang/v nv`)
+Let's say that the forked repository is at
-1. `cd nv`
+`https://github.com/YOUR_GITHUB_USERNAME/v` .
-1. `git remote add pullrequest git@github.com:YOUR_GITHUB_USERNAME/v.git`  #
+2. Clone the main v repository https://github.com/vlang/v to a local folder on your computer, say named nv/ 
-(NOTE: this is your own forked repo of: https://github.com/vlang/v - After
+(`git clone https://github.com/vlang/v nv`)
-this, we just do normal git operations such as: `git pull` and so on.)
+3. `cd nv`
-1. When finished with a feature/bugfix, you can: `git checkout -b fix_alabala`
+4. `git remote add pullrequest https://github.com/YOUR_GITHUB_USERNAME/v`  
-1. `git push pullrequest`  # (NOTE: the pullrequest remote was setup on step 3)
+NB: the remote named `pullrequest` should point to YOUR own forked repo, not the main v repository!
-1. On GitHub's web interface, I go to: https://github.com/vlang/v/pulls  Here
+After this, your local cloned repository is prepared for making pullrequests, 
-the UI shows a nice dialog with a button to make a new pull request based on
+and you can just do normal git operations such as: `git pull` `git status` and so on.
-the new pushed branch. (Example dialogue:
-https://url4e.com/gyazo/images/364edc04.png)
-1. After making your pullrequest (aka, PR), you can continue to work on the
-branch... just do step #5 when you have more commits.
-1. If there are merge conflicts, or a branch lags too much behind V's master,
-you can do the following:
-   1. `git checkout master`
-   1. `git pull`
-   1. `git checkout fix_alabala`
-   1. `git rebase master`  # solve conflicts and do git rebase --continue
-   1. `git push pullrequest -f`
 
-The point of doing the above steps to never directly push to the main V
+1. When finished with a feature/bugfix/change, you can: 
-repository, only to your own fork. Since your local master branch tracks the
+`git checkout -b fix_alabala`
-main V repository's master, then `git checkout master; git pull --rebase origin
+2. `git push pullrequest`  # (NOTE: the `pullrequest` remote was setup on step 4)
-master` work as expected (this is actually used by `v up`) and it can always do
+3. On GitHub's web interface, go to: https://github.com/vlang/v/pulls  
-so cleanly. Git is very flexible, so there may be simpler/easier ways to
+
-accomplish the same thing.
+Here the UI shows a dialog with a button to make a new pull request based on
+the new pushed branch. 
+(Example dialog: https://url4e.com/gyazo/images/364edc04.png)
+4. After making your pullrequest (aka, PR), you can continue to work on the
+branch `fix_alabala` ... just do again `git push pullrequest` when you have more commits.
+5. If there are merge conflicts, or a branch lags too much behind V's master,
+you can do the following:
+   1. `git pull --rebase origin master` # solve conflicts and do `git rebase --continue`
+   2. `git push pullrequest -f` # this will overwrite your current remote branch with the updated version of your changes.
+
+The point of doing the above steps, is to never directly push to the main V
+repository, *only to your own fork*. Since your local `master` branch tracks the
+main V repository's master, then `git checkout master`, as well as
+`git pull --rebase origin master` will continue to work as expected
+(these are actually used by `v up`) and git can always do it cleanly.
+
+Git is very flexible, so there are other ways to accomplish the same thing.
+
+## Using Github's hub CLI tool
+
+You can download the `hub` tool from https://hub.github.com/ . Using
+`hub`, you will not need to go through the (sometimes) slow website 
+to make PRs. Most remote operations can be done through the `hub` CLI
+command.
+
+NB: You still need to have a GitHub account.
+
+### Preparation:
+(steps 1..3 need to be done just *once*):
+
+1. `hub clone vlang/v my_v`
+2. `cd my_v`
+3. `hub fork --remote-name pullrequest`
+
+4. `git checkout -b my_cool_feature` # Step 4 is better done *once per each new feature/bugfix* that you make.
+
+### Improve V by making commits:
+
+5. `git commit -am "math: add a new function copysign"`
+
+### Testing your commits locally:
+You can test locally whether your changes have not broken something by 
+running: `v test-compiler`
+
+### Publishing your commits to GitHub:
+
+6. `git push pullrequest`
+
+### Making a PR with `hub`:
+(so that your changes can be merged to the main V repository)
+
+7. `hub pull-request`
+
+Optionally, you can track the status of your PR CI tests with:
+
+8. `hub ci-status --verbose`
+
+### Fixing failing tests:
+If everything is OK, after 5-10 minutes, the CI tests should pass for
+all platforms. If not, visit the URLs for the failing CI jobs, see
+which tests have failed and then fix them by making more changes. Just use 
+`git push pullrequest` to publish your changes. The CI tests will
+run with your updated code. Use `hub ci-status --verbose` to monitor
+their status.