Using GitHub

[Dirk Hohndel]

> On Jan 4, 2017, at 11:46 PM, Paul-Erik Törrönen <poltsi at poltsi.fi> wrote:
> 
> On 2017-01-05 08:29, Willem Ferguson wrote:
>> How does one submit a patch? Does one have to do the edits online
>> within GitHub inside a browser or can one upload files with changes?
>> The tutorial is not clear.
> 
> IIRC Dirk did mention that he would accept pull-requests?
> 
> If so then that would mean that your repo must be public, and I guess the easiest way is to just fork Dirk's github project (let's call this master) to your own github account (let's call this your branch) and issue a pull from there?
> 
> You then in turn, clone from your github account your branch to your workstation (let's call this local copy) and do the edits there.
> 
> So the flow model of your changes would be:
> 
> local copy => your branch => master
> 
> You also need to get the updates to your local copy from master, which means that you need to add master as a remote so you can fetch/merge all the other changes which you then push to your github branch.
> 
> So the flow model of others changes would be:
> 
> master => local copy => your branch

There is one challenge here and I've already seen this in a couple of the 
pull requests... don't do merges in the branch that you create the pull 
requests from. One way to do things is this:

First let's change the terminology that Paul used, 'master' is the name 
of an important branch, not a great name to refer to a repo. So let's call 
these three repos "upstream" (Subsurface-divelog/subsurface), 
"your fork" (yourgithubaccount/subsurface), and "local copy"

In your local copy you should always have a clean master branch 
that exactly tracks Subsurface-divelog/subsurface master - no 
additional commits, same SHAs - many of you don't do this and I 
can tell from the patches and it's even more obvious with pull requests.

So in your local copy do

git checkout master
git pull 

this gets you the latest in master - if this asks you to do a merge 
commit, you didn't have an exact copy; stop here, figure out what's 
different between your local branch and upstream master

git checkout -b my-feature-branch

this creates an exact copy of master in "my-feature-branch" 
(please give it a good name... user-manual-updates-for-4.6 is a
great name)

git rev-parse HEAD

remember this SHA as your starting point

work in this branch until you are happy.
DO NOT MERGE UPSTREAM INTO THIS BRANCH

(if you really, absolutely have to update, try 

git pull --rebase upstream master

and carefully deal with any problems - but unless you know what 
you're doing, I'd rather you didn't)

once you are happy with your work, run gitk or git log and look at the 
history. Feel free to clean up. "git rebase -i <SHA of your starting point>" 
is a great way to do that. Careful if you didn't listen and did merges - this 
is where things go off the cliff if you don't know what you are doing. 
Really, please, don't merge.

now you can push that branch to your fork

git push your-fork my-feature-branch

Now, on the github site, you can create a pull request for that branch

> Or you can continue in the old way, sending patches by email from your local copy.

Yes, absolutely. Those who are comfortable sending patches, please 
continue doing so. The idea with switching to pull requests was that they 
would make it easier for me not to miss patches. And that for many open 
source developers they have become the default thing that they do. But 
if you have figured out how to send patches and this pull request thing is 
scary (or you just hate it for other reasons), feel free to send me patches 
(and remind me if I don't apply them).

Makes sense?

/D