[Xastir] Online Map Enhancements

[Lee Bengston]

On Fri, Nov 23, 2018, 10:54 PM Tom Russo <russo at bogodyn.org wrote:

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

The tarball contains only the 4 files that were changed, but regardless I
understand the right way to share work is via Git.

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

I'll take all the info I can get.

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

Thanks for all of the info including your follow up. I'm in no hurry, and
I'm sure you guys aren't in a hurry to deal with these changes at the
moment.

There's a remaining part of the new code I have decided to take another
look at to see if I can make it more efficient before sharing via Git. In
the meantime anyone who's interested in checking out the new capabilities
can swap the 4 source files in a local clone, rebuild, and add the new Geo
files. I would back up those 4 source files before trying that.

Lee - K5DAT


>