On Fri, Nov 23, 2018 at 09:24:14PM -0600, we recorded a bogon-computron collision of the <[email protected]> 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 [email protected] http://xastir.org/mailman/listinfo/xastir
