High-level overview:

The debian packaging works by keeping several branches in parallel.  First there is the g.c/master
branch: this has no debian packaging in it at all, it is basically just the upstream GraftNetwork
branch with all graft-community changes added in, and this is meant to be built from anyone who
wants to compile the community version from source.

Then there are branches for each supported debian/ubuntu version (current 5: debian, debian-stretch,
ubuntu-xenial, ubuntu-bionic, and ubuntu-cosmic).  These branches follow the g.c/master branch, but
add the debian packaging files and are use the build the debs.


Updating Instructions:

1. (Only need to do this part once)
   a) Clone the graft-community/GraftNetwork repository to your own github account on github,
      then clone your fork locally using `git clone ...` specifying your own github checkout URL.
   b) cd into your cloned GraftNetwork and add the g.c and upstream remotes:
      git remote add g.c https://github.com/graft-community/GraftNetwork.git
      git remote add upstream https://github.com/graft-project/GraftNetwork.git
   c) apt install git-buildpackage

2. Update from the three remote repositories:

   git fetch --all

3. Start a new branch from the g.c/master branch (the "update174" name here doesn't really matter):
   git checkout -b update174 g.c/master

4. Merge changes from upstream master branch into your branch using:
   git merge upstream/master

   a) If there are conflicts (because upstream and g.c each changed the same code) the git merge will
   instead give an error message and tell you to resolve conflicts.  `git status` will show the
   current status including files where there are conflicts.  You need to edit this files and look
   for any conflict markers which will look like this:

   <<<<<<< HEAD
   Hello world
   =======
   Goodbye
   >>>>>>> upstream/master

   This is saying that the code "Hello world" is the code in g.c, but that upstream/master (the
   graft-project repository) put the code "Goodbye" there instead.  Sometimes resolving these
   conflicts is obvious, sometimes it takes more work to figure out the solution.

   Once they are resolved in a file, you `git add filename` that file.  Once *all* the conflicts
   are resolved you use `git commit` and continue:

   b) If there were no conflicts, or if you resolved all the conflicts, this will drop you into an
   editor with a default commit message about the merge; you can just save and exit.

5. (Optional) You can try to build the project normally at this point.  If something fails, you'll
   need to fix it.  The bigger the change, or the larger the number of conflicts, the more important
   it is to do this step.

6. Start a new branch based on one of the debian/ubuntu branches.  For this you will want to create
   a local branch based on the g.c/DISTRO branch, where DISTRO is one of:

    - debian (debian "sid")
    - debian-stretch (debian 9)
    - ubuntu-xenial
    - ubuntu-bionic
    - ubuntu-cosmic

   I recommend starting on whichever one you are currently using (for example ubuntu-cosmic if on
   a ubuntu 18.10 system):

   git checkout -b bionic174 g.c/ubuntu-bionic

7. Merge your local changes destined for the `g.c/master` branch using:

   git merge update174

   If conflicts occur, see the note above about resolving them, though conflicts are much rarer
   here.

8. Decide on the release version for the deb.  I try to follow this format:

   1.7.4+gc1-1              (for the `debian` branch)
   1.7.4+gc1-1~deb9         (for the `debian-stretch` branch)
   1.7.4+gc1-1~ubuntu18.04  (for the `ubuntu-cosmic` branch; change 18.04 to 18.10 or whatever for other ubuntu versions)

   where:
   - '1.7.4' is the upstream graft number
   - '+gc1' indicates that this is the first graft.community build of 1.7.4
   - '-1' indicates that this is the first release of the .deb
   - '~whatever' is there to disambiguate the packages for the different distributions (so that the
     package version on ubuntu 18.04 is slightly different than the package version on ubuntu 18.10).

   So when a new release comes out, the 2nd and third reset to `+gc1-1`.
   If there isn't a new release, but there is some new graft-community addition or fix, you would change `+gc1-whatever` to `+gc2-1`.
   If this is a change only to the .deb packaging but not to the graft-community master code, then you would change `-1` to `-2`.

9. Increment the debian package version using:

   gbp dch --ignore-branch -RN 1.7.4+gc1-1~ubuntu18.04 --distribution bionic

   but of course change this version as appropriate for each build/branch as per step 8.  The
   distribution at the end should be one of:

   Debian: sid stretch (future: buster)
   Ubuntu: xenial bionic cosmic (future: disco)

   This command will read the git history and drop you into an editor pre-filled with the commit
   messages.

10. Build the package using this (note that you need to be in the top-level GraftNetwork directory):

    dpkg-buildpackage -uc -us -b -j4

    Change -j4 to whatever parallel compilation your system supports.

11. Assuming the package built successfully, you will find the *.deb in .. (i.e. in the parent
    directory of GraftNetwork).  You can install them using `dpkg -i filename.deb filename2.deb ...`
    and at least test that some basic functionality works (at a minimum try `--help` on a couple of
    the binaries and maybe start graftnoded for a few seconds to make sure it starts).

12. If all looks good, go back to the GraftNetwork directory and do `git add debian/changelog` then
    commit this with `git commit`.  Give it some useful commit message like "upgraded ubuntu 18.04 deb
    to 1.7.4".

13. Repeat steps 6-9 and 12 for the other debian/ubuntu branches.  You may run into some minor issues
    trying to build on the wrong system, so don't bother with steps 10 and 11.

14. Now you are essentially done, you just need to push these 6 branches to your github repository
    by checkout (for example: `git checkout update174` or `git checkout bionic174`) out each one and
    running:

    git checkout update174
    git push -u origin update174

    git checkout bionic174
    git push -u origin bionic174

    ...

15. Submit pull requests: go to your github, go to Pull Requests, click the green "New pull request"
    button, then choose base repository of graft-community/GraftNetwork (this should be the default),
    and choose the appropriate branch (`master`, `ubuntu-bionic`, etc.), choose your updated branch
    (`update174`, `bionic174`, etc.) then hit `Create pull request`.

    Repeat this for each branch.

16. Relax.