[Scummvm-devel] How to use your personal github fork

Mon May 30 14:27:52 CEST 2011

I think that it would be best if we add the text as-is in the wiki, and then
people can amend it themselves.

Regards
Filippos

On Mon, May 30, 2011 at 3:21 PM, Max Horn <max at quendi.de> wrote:

> Just as a reminder: The following is still not in the Wiki. If anybody
> feels like something like it should be in there, please add it. People can
> then edit it to adjust it based on the various suggestions people had later
> on.
>
> Or else, we'll just let it die. Fine by me, too, I don't need it, after all
> :).
>
> Bye,
> Max
>
> Am 27.04.2011 um 17:39 schrieb Max Horn:
>
> > Hi there,
> >
> > for various reasons I thought it'd be a good idea to explain how to make
> good use of the github fork feature, and to describe a basic workflow
> involving your personal fork of the scummvm repository. I guess a version of
> this should be put onto a Wiki page. There are several people on this list
> who know a lot more about git than I do, and maybe they can help improve
> this guide, and correct its flaws.
> >
> > Cheers,
> > Max
> >
> >
> >
> > Preliminaries
> > =============
> > I assume that you are familiar with the basics of git, have a github
> account, and have adjusted your local git config to contain info about your
> github user account, as per <http://help.github.com/git-email-settings/>.
> >
> > In addition, if you are on a unixy system, I recommend taking a look at
> the "hub" tool <http://github.com/defunkt/hub> which makes it easier to
> fork repositories, clone other people's repositories etc. But I will not
> assume that you are using it.
> >
> >
> > What is a github fork and why use it?
> > =====================================
> > A github fork is a clone of another github hosted repository (say,
> scummvm/scummvm) which is located under your github user account (say
> fingolfin/scummvm). It allows you to publish changes you make to ScummVM
> (preferably in a topic branch), but which you do not want to / cannot push
> to the regular scummvm repository yet.
> > It's a good place to stage bigger changes. It's also very easy to ask the
> ScummVM team to review your changes made in a public github fork, and to
> optionally merge them into scummvm/scummv, via a so-called "pull request" <
> http://help.github.com/pull-requests/>.
> >
> > How to create a github fork?
> > =============?==============
> > See here <http://help.github.com/fork-a-repo/>. Essentially, you use the
> "fork" button on <https://github.com/scummvm/scummvm>. Then, clone your
> new fork. You can now work in this clone as in a clone of scummvm/scummvm,
> but pulls and pushes now go to / come from your fork.
> >
> > How to use your github fork?
> > ============================
> > In the following, I will try to describe a workflow that is hopefully
> effective, safe, and relatively easy to use. Other workflows are possible,
> and you are welcome to use them; the one here tries to minimize the risk of
> messing up the scummvm/scummvm repository, and to avoid situations in which
> you need to do complicated stuff you correct mistakes you made.
> >
> > Over time, your fork will start to *deviate* from scummvm/scummvm. In
> particular, it will not automatically receive updates made to
> scummvm/scummvm. So, you will want to regularly sync your fork and its
> master branch against the master branch of scummvm/scummvm. This is easiest
> if your fork's master branch never receives any custom commits; always keep
> it identical to (a possibly old version of) the scummvm/scummvm master
> branch. All your own work should go to branches, ideally one branch for
> every topic you are working on (so-called topic branches).
> >
> > Initial Setup
> > -------------
> > This is how I did the initial setup for it for my personal fork:
> >
> > 1) Clone the fingolfin/scummvm repository
> >   git clone git at github.com:fingolfin/scummvm.git scummvm-fingolfin
> >   cd scummvm-fingolfin
> >
> > 2) add a "remote" for the official scummvm/scummvm repository (I will use
> "upstream" as remote name, to match the github docs; personally, I prefer
> using the remote "username", so in this case I would have used "scummvm"
> instead of "upstream". Pick whatever you like)
> >
> > A read-only remote can be added like this:
> >   git remote add upstream git://github.com/scummvm/scummvm.git
> > If you have write access, you may want to instead add a read+write
> remote, e.g. using the SSH protocol:
> >   git remote add upstream git at github.com:scummvm/scummvm.git
> >
> > 3) Retrieve the latest data from scummvm/scummvm
> >   git fetch upstream
> >
> > Sync master branches
> > --------------------
> > To sync my master branch with the upstream master branch, I can now do
> this, assuming that "master" is the currently active branch (if not, use
> "git co master" to switch to it):
> >    git pull upstream master
> >    git push
> >
> > Working with code
> > -----------------
> > Usually, any code I make goes first into a branch:
> >
> >  git co -b new-cool-feature
> >
> > Let's edit a file (e.g. modify base/main.cpp to print "hello, world").
> Commit this as usual; note that the commit will land on the new-cool-feature
> branch, not master.
> >
> >  ... edit base/main.cpp ...
> >  git add base/main.cpp
> >  git ci -m "BASE: Add new cool feature"
> >
> > You can check the difference between the two branches:
> >
> >  git diff master..new-cool-feature
> >
> > Now we want the rest of the world to be able to see our marvelous new
> code, so let's push it to a new branch on our github fork, with identical
> name:
> >
> >  git push origin new-cool-feature
> >
> > With this we have established a connection between our local
> "new-cool-feature" branch, and the "new-cool-feature" branch on github. From
> now on we can just do "git push". So let's edit base/main.cpp again, this
> time maybe by printing a "goodbye, world" at the end. Then, let's commit and
> push the changes:
> >
> >  ... edit base/main.cpp ...
> >  git add base/main.cpp
> >  git ci -m "BASE: Even better new feature"
> >  git push
> >
> > You can look at the result here: <
> https://github.com/fingolfin/scummvm/tree/new-cool-feature>
> >
> > At some point, you may want your work to be integrated into the official
> ScummVM tree. As mentioned above, the easiest way (if you are not a
> committer) probably is to submit a pull request <
> http://help.github.com/pull-requests/>. Even people who do have write
> access often use this, in order to receive feedback on their code.
> >
> > If you have write access and just want to integrate your changes, do the
> following (I'll assume you do a merge here, but you can of course also do a
> rebase):
> >   git co master
> >   git pull upstream   # ensure we are in sync with upstream
> >   git merge new-cool-feature
> >   git push upstream   # push to upstream
> >   git push            # push to your fork
> >
> > [question to the experts: maybe we want to suggest use of --no-ff for the
> merge ?]
> >
> >
> > Note: In reality, I sometimes make an exception and skip the creation of
> a (topic) branch. E.g. if I only want to commit a quick fix to some code. In
> that case, I might commit the fix into my local master branch, then push the
> result to both my fork and scummvm
> >  git co master
> >  git pull
> >  ... edit files, add and commit them ...
> >  git push upstream
> >  git push
> >
> >
> > Cleaning up your existing clones / checkouts
> > --------------------------------------------
> > Maybe you were already using a fork, but were following a different model
> (or no model at all ;) and would like to adapt to this. E.g. maybe you made
> commits directly to your master branch, then merged changes from
> scummvm/scummvm's master branch into that, and now have a messy history
> which intermingles your own work with upstream work.
> >
> > Cleaning this up is usually quite simple. Let's assume the most simple
> case, namely that you made no branches at all and did all your work on
> master. (If you did use branches, you need to adapt this. Feel free to ask
> here or on our IRC channel if you need help.)
> > So, let's assume you are in your local clone of your fork, with master as
> sole active branch. Make sure that the upstream remote has been added, as
> described above, so
> >   git remote add upstream git://github.com/scummvm/scummvm.git
> > or
> >   git remote add upstream git at github.com:scummvm/scummvm.git
> >
> > Now, we fetch the upstream changes, and *rebase* our master branch on
> that:
> >   git fetch upstream
> >   git rebase upstream/master
> >
> > If all went fine, then this just completely. If you are in bad luck, this
> will cause an error, and you will have to resolve conflicts. It prints
> instructions for how to do that. Feel free to ask here or on IRC for
> assistance with resolving the issues. In the worst case, you can just use
> >   git rebase --abort
> > to give up.
> >
> > But let's assume the rebase worked fine, or that you managed to make it
> work by resolving any conflicts. Now it's time to move any work you have
> done on master to a branch, so that we don't need to worry about this again
> in the future. Also, we will reset your local master branch to match the
> upstream master branch
> >
> >  git br BRANCH_NAME
> >  git reset --hard upstream/master
> >
> > Finally, we can push your work back to your fork:
> >
> >  git co master
> >  git push origin master
> >  git co BRANCH_NAME
> >  git push origin BRANCH_NAME
> >
> >
> >
> ------------------------------------------------------------------------------
> > WhatsUp Gold - Download Free Network Management Software
> > The most intuitive, comprehensive, and cost-effective network
> > management toolset available today.  Delivers lowest initial
> > acquisition cost and overall TCO of any competing solution.
> > http://p.sf.net/sfu/whatsupgold-sd
> > _______________________________________________
> > Scummvm-devel mailing list
> > Scummvm-devel at lists.sourceforge.net
> > https://lists.sourceforge.net/lists/listinfo/scummvm-devel
> >
>
>
>
> ------------------------------------------------------------------------------
> vRanger cuts backup time in half-while increasing security.
> With the market-leading solution for virtual backup and recovery,
> you get blazing-fast, flexible, and affordable data protection.
> Download your free trial now.
> http://p.sf.net/sfu/quest-d2dcopy1
> _______________________________________________
> Scummvm-devel mailing list
> Scummvm-devel at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/scummvm-devel
>

-- 
"Experience is the name every one gives to their mistakes" - Oscar Wilde
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.scummvm.org/pipermail/scummvm-devel/attachments/20110530/b16b292f/attachment.html>