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 <[email protected]> flavor, containing: > 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 -- 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
