From b952e653009a910004296260ce0d5c0919ea0d6c Mon Sep 17 00:00:00 2001
From: Geoff McLane <ubuntu@geoffair.info>
Date: Fri, 27 Apr 2018 15:33:17 +0200
Subject: [PATCH] Is #718 #726 - Some updates of CONTRIBUTING.md

---
 README/CONTRIBUTING.md | 35 +++++++++++++++++++++++++----------
 1 file changed, 25 insertions(+), 10 deletions(-)

diff --git a/README/CONTRIBUTING.md b/README/CONTRIBUTING.md
index 0055127..5f78848 100644
--- a/README/CONTRIBUTING.md
+++ b/README/CONTRIBUTING.md
@@ -39,17 +39,21 @@ Concerning the “Tidy Code Style,” checkout [CODESTYLE.md](CODESTYLE.md), but
 
 ### Using Git appropriately
 
- 1. Fork the repository to your GitHub account.
- 2. Optionally create a **topical branch**, a branch whose name is succinct but explains what you're doing, such as "feature/add-new-lines".
- 3. Make your changes, committing at logical breaks.
- 4. Push your work to your personal account.
- 5. [Create a pull request](https://help.github.com/articles/using-pull-requests).
- 6. Watch for comments or acceptance.
+ 1. Fork tidy to your own github account. Use top right `Fork` icon.
+ 2. Optional: Generate a SSH Key, and add it to your `https://github.com/<name>` settings, SSH and GPG keys
+ 3. Clone your own fork - `$ git clone git@github.com:<name>/tidy-html5.git tidy-fork` Or using `https`.
+ 4. Create a branch - `$ cd tidy-fork; $ git checkout -b <branch-name>`
+ 5. Edit, and commit your changes to this `branch` of your fork.
+ 6. Test your changes, and if appropriate run [regression](https://github.com/htacg/tidy-html5-tests/blob/next/README/RUNTESTS.md) tests.
+ 7. Publish the branch - `$ git push -u origin <branch-name.` - to your remote fork.
+ 8. Create a [Pull Request](https://help.github.com/articles/about-pull-requests/), a **PR**, here.
+ 9. Watch for comments, acceptance.
 
-Please note - if you want to change multiple things that don't depend on each
-other, it is better to use `branches`, and make sure you check the master branch back out before making more changes - that way we can take in each change seperately, otherwise Github has a tendancy to combine your requests into one.
+Item 2., SSH Key, is optional, and only required if you want to use `clone git@github.com...`. And if you generate the ssh without a `passphrase`, things like `git push` can be done without a password. Just convenience. Alternatively you can use the `HTTPS` protocol...
 
-If you are a continuing contributor then you will need to `rebase` your fork, to htacg `next`, **before** doing any more work, and likewise branches, otherwise we may not be able to cleanly merge your PR. This is a simple process:
+Concerning 5., editing and committing your changes, **generally** it is better to `commit` changes often, adding an appropriate commit message to each. This also aids in the PR review. But the situation varies. Like adding say an option, which can mean several files have to be edited, where it is likely appropriate to combine a considerable number of edits into one commit. There can be no hard and fast rules on this.
+
+Please note, if you want to change **multiple** things that don't depend on each other, use **different** `branches`, and make sure you check the `next` branch back out, before making more changes in a **new** branch. That way we can take in each change separately, otherwise Github will combine all your branch commits into one PR. And see below on keeping your `next` fully in sync with here - this is **important**.
 
 ```
 $ git remote add upstream git@github.com:htacg/tidy-html5.git # once only
@@ -62,7 +66,18 @@ $ git stash pop # if required, and fix conflicts
 $ git push      # update the fork next
 ```
 
-This can be repeated for other branches, too.
+This has to be repeated for other branches, too. `$ git checkout <your-branch>`, `$ git rebase next`, fix conflict, if any, and `$ git push`, for each branch. It is not fun to keep multiple `branches` fully up-to-date with an active `upstream`...
+
+Of course, the **regression** tests, 6., are really only if you have made `code` changes, but it is a good habit to get into. As can be seen the `tests` are in a **separate** repo, so you must also clone that. This is best done in the same `root` folder where where you cloned `tidy-html5`.
+
+```
+$ git clone git@github.com:htacg/tidy-html5-tests.git
+$ cd tidy-html5-tests/tools-sh
+$ ./testall.sh ../../tidy-html5/build/cmake/tidy
+$ diff -u ../cases/testbase-expects ../cases/testbase-results
+```
+
+If the `testall.sh` shows a different exit value, or there are differences between the `expects` and `results` these **must** be studied, checked very carefully. There may be cases where the **new** `results` are correct, in which case a simultaneous PR for the tests must be created to match your source PR.
 
 ### Help Tidy Get Better