From 95e67c9502c727c41e27aa75a92010a9087ff187 Mon Sep 17 00:00:00 2001 From: Delyan Angelov Date: Fri, 27 Mar 2020 17:03:06 +0200 Subject: [PATCH] contributing.md: update git instructions --- CONTRIBUTING.md | 106 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 79 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 596b4ca89f..46b5c3d9b4 100644 --- a/CONTRIBUTING.md +++ b/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 -https://github.com/vlang/v nv`) -1. `cd nv` -1. `git remote add pullrequest git@github.com:YOUR_GITHUB_USERNAME/v.git` # -(NOTE: this is your own forked repo of: https://github.com/vlang/v - After -this, we just do normal git operations such as: `git pull` and so on.) -1. When finished with a feature/bugfix, you can: `git checkout -b fix_alabala` -1. `git push pullrequest` # (NOTE: the pullrequest remote was setup on step 3) -1. On GitHub's web interface, I go to: https://github.com/vlang/v/pulls Here -the UI shows a nice dialog with a button to make a new pull request based 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` +1. Fork https://github.com/vlang/v using GitHub's interface to your own account. +Let's say that the forked repository is at +`https://github.com/YOUR_GITHUB_USERNAME/v` . +2. Clone the main v repository https://github.com/vlang/v to a local folder on your computer, say named nv/ +(`git clone https://github.com/vlang/v nv`) +3. `cd nv` +4. `git remote add pullrequest https://github.com/YOUR_GITHUB_USERNAME/v` +NB: the remote named `pullrequest` should point to YOUR own forked repo, not the main v repository! +After this, your local cloned repository is prepared for making pullrequests, +and you can just do normal git operations such as: `git pull` `git status` and so on. -The point of doing the above steps 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; git pull --rebase origin -master` work as expected (this is actually used by `v up`) and it can always do -so cleanly. Git is very flexible, so there may be simpler/easier ways to -accomplish the same thing. +1. When finished with a feature/bugfix/change, you can: +`git checkout -b fix_alabala` +2. `git push pullrequest` # (NOTE: the `pullrequest` remote was setup on step 4) +3. On GitHub's web interface, go to: https://github.com/vlang/v/pulls + +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.