[Xastir] Online Map Enhancements

[Tom Russo]

I was sure I'd written all this up before, and I had.

It can be found (possibly in a more coherent form) in the CONTRIBUTING.md
file of an Xastir clone, or at 
https://github.com/Xastir/Xastir/blob/master/CONTRIBUTING.md


On Fri, Nov 23, 2018 at 09:54:04PM -0700, we recorded a bogon-computron collision of the <russo at bogodyn.org> flavor, containing:
> 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]
> 
> _______________________________________________
> Xastir mailing list
> Xastir at lists.xastir.org
> http://xastir.org/mailman/listinfo/xastir

-- 
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]