[Xastir] Online Map Enhancements

[Tom Russo]

On Fri, Nov 23, 2018 at 09:24:14PM -0600, we recorded a bogon-computron collision of the <lee.bengston at gmail.com> flavor, containing:
> >
> > I looked at the Wiki article on how developers should use Git, but I guess
> > my brain is to tired for that to fully soak in, so for now I'm sharing the
> > modified source files via a web link.
> >
> 
> By the way I didn't mean to imply above that I now consider myself to be a
> developer :-)

At the moment, only Curt and I have permission to write to the main Xastir
repo, and both of us are swamped (as you might have noticed from our relative
silence these days).  So downloading a new tarball of source code and picking
out the changes is pretty much not something either of us will do.  The only
real process we have these days is pull requests, so if you wanna share your
work and get it into Xastir, you pretty much have to go that route.

I just reviewed the "Notes:Git" file, and it isn't really that helpful for
suggesting how a member of the community should share their code via Git.
I'll try to summarize.  I am not good at summarizing, so this is long.

The best way to do it is to create a "fork" of Xastir on GitHub.  There's
a ton of information on Github about that here:
   https://help.github.com/articles/working-with-forks/
Note that some of this documentation assumes that your fork is the one
you cloned (so it is called "origin") and the main repo from which you
forked has been defined as an alternate remote ("upstream") but my thumbnail
sketch is the other way around, because you already have Xastir's repo
cloned and set as the "origin" remote.

A thumbnail sketch is:
  - Make sure your clone is up to date:
    git fetch origin
    git merge master

  - Create a github account if you don't already have one.  

  - Back inside your existing git clone, 
    Make sure to configure git so your commits have your name and email
    address associated with them:

       git config --global user.name "Lee Bengston"
       git config --global user.email <your email address>

    Make sure you use the same email address that you used
    to set up your Github account.

  - Now create a fork on github through github's web interface
    using the "fork" button at the top right corner of the Xastir project page 
    at https://github.com/Xastir/Xastir 

    A "fork" is nothing more than a git clone that lives on Github instead
    of your machine, but is owned by you and you can do anything you want
    to it, including pushing changes from your local git repo on your
    own machine.


  - Associate your fork with a "remote" in your git clone directory:
        git remote add <remote name> <remote URL>
    "remote name" is something you'll use to refer to this alternate
    Github fork.  "remote url" is the URL to your Github fork.  So, for example
        git remote add myfork https://github.com/<your github user name>/Xastir.git

    If you do "git remote -v" you should now see four lines, two saying there's
    the default "origin" remote, and two with your new one called "myfork".

    You can now pull code from "origin" to keep current with Xastir's
    development as usual.  But having the other remote defined means
    you can also mess around with your fork without having two
    different directories to work in.

  - Now check the current status of your clone directory:
        git status
    It should show that you've got a few code changes, and you should make sure
    that only the changes you *want* are there.  It will probably also
    show that you're on the "master" branch.

    Use 
       git diff
    and look over the differences, and make sure that everything that is 
    different between your working directory and the repo's previous
    state are changes you really wanted to share.

  - Create a new branch to hold the changes you want to share, and switch
    to it.
      git checkout -b myspecialnewhack
    The "checkout" command switches which branch you're on, and the 
    "-b" flag means "create the branch before switching."

  - Once again, check your status:
      git status
    It should show that you're on the "myspecialnewhack" branch, and that
    all the changes you made are still "Changes not staged for commit".

  - Stage your changes for commit
      git add .
    This is slightly dangerous, as it stages *ALL* changes present in your 
    directory for commit.  This is why I said "make sure that only the changes
    you *want* are there."  You can be more precise if you want, and 
    individually stage each file that you actually want to commit, if there
    are some differences you DON'T want to share.
      git add <file1> <file2> ... <etc.>

  - Now actually commit the things you staged:
      git commit
    This should fire up an editor and let you type in a commit message.  
    Write an informative one.  Use the following format:
      First line should be written in the imperative, and about 50 characters
      Leave a blank line.
      Explain what your commit does.  Wrap your lines around 72 chars.
      Do not rely on your editor to wrap lines for you.

    Example:
    =======
    Add new online map options

    This commit modifies the online map URL generating code to support
    tile servers that reverse the X and Y of tile locations, and also
    adds several .geo files for interesting tile servers.
    =======

    Save the commit message using your editor's file save command, and 
    exit the editor.  Your commit will now be saved in your local git
    repo.

  - Check that it's good:
      git log
    should show that you added a new commit.
      git log -p
    should show that you added a commit, and what changes that commit made.
      git log --all --decorate --oneline --graph
    should show you a graphical representation of the git history, with
    labeled branches and only the first line of the commit message for each
    commit in the history (this is why you leave the blank line, and why
    you should stick to 50 chars).

    In that graph display, you should see that your new commit should show 
    a decoration that has "HEAD->myspecialnewhack" in it, indicating that 
    your change happened on your branch and not on master.  

    You should also see that "master" and "origin/master" are decorating
    a commit *prior* to your change.

  IF ANYTHING DOESN'T LOOK RIGHT HERE, DON'T GO TO THE NEXT STEP!  There
  *ARE* ways to fix things using "commit --amend" , "reset" and so forth, but
  not after you've pushed code.

  - Now that you're sure that your new branch is the way you want the world
    to see it, push your new branch up to YOUR remote:
     git push myfork myspecialnewhack
   where "myfork" is what you used when you did the "git remote add"
   command.  You will be prompted for your github user ID and password here.

   This will push the contents of "myspecialnewhack" branch up to your
   fork, where anyone who wants to can either download that branch, or
   fork your fork and hack on it further.

  - Once you've pushed, try redoing this command:
      git log --all --decorate --oneline --graph
    You should see now that not only is your new commit on the 
    "myspecialnewhack" branch, but also on "myfork/myspecialnewhack".

Now your fork differs from the main Xastir repo, because it has a new branch
with your fancy new changes.  Now go to Github and open a pull request
Here's the real documentation, which you should actually read:  
    https://help.github.com/articles/creating-a-pull-request-from-a-fork/

and here's a possibly inadequate thumbnail sketch of the process.
   - Go log in to github.com, and navigate to your Xastir fork.
   - Click the "New pull request" button next to the "Branch" pull-down.
   - Fill in the form, selecting what branch of your repo you're suggesting
     we pull from, and which branch to pull it into (in this case, master).
   - ?
   - Profit.

Sometime before the heat death of the universe, maybe we'll get to look over
the changes and merge them into Xastir if they're safe.  

If ever you want to return to the unmodified code from the main repo, just
switch back to the master branch:
   git checkout master
This is safe, because your new changes have been carefully saved on the 
"myspecialnewhack" branch, and you can return to them any time with:
   git checkout myspecialnewhack

Pile of cake, n'est pas?

-- 
Tom Russo    KM5VY
Tijeras, NM  

 echo "prpv_a'rfg_cnf_har_cvcr" | sed -e 's/_/ /g' | tr [a-m][n-z] [n-z][a-m]