Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Step 1: Create a free GitHub account if you don't already have one. Be sure to set up your account with a SSH key pair and your email address(es) so Git can identify which commits are yours.
Step 2: Go to the Fedora repository on GitHub and click on the "Fork" button
Step 3: Clone your fork, using the private URLthe Fedora repository. At a command line, go to a directory where you want the new local repository, and issue the following:

Code Block
$ git clone git@githubhttps://github.com:<you>/fcrepo4/fcrepo4.git

When this finishes you will have a local clone of your forkthe Fedora code base, complete with a remote named 'origin' that points back to your fork on GitHub (not the original)to the main Fedora Github repository.

Step 4: Tell your local clone about your fork of the official upstream repository on GitHub:

Code Block
$ cd fcrepo4
$ git remote add upstream<you> githttps://github.com/fcrepo4<you>/fcrepo4.git
$ git fetch upstream

This uses the public URL for the upstream repository, which is read-only. This helps ensure that your changes only go into your fork repository.
Now we've set up a local Git repository, we can talk about the steps you'll do much more often.

...

Now, we need to pull any changes made to the official upstream main repository due to new features or bug fixes. You can pull them into your fork two ways:

Code Block
$ git pull upstream master

or

Code Block
$ git fetch upstream
$ git merge upstream/master

...

pull

...

code
$ git branch -a

If you do not see a branch in 'remotes/upstream' that you know is in the official repository, run the "git fetch upstream" and "git merge upstream/<missingBranch>" form.
Any local changes you have will be merged, and any local commits already in the upstream will be handled as a fast-forward merge (leaving your branch at the same commit as the "upstream/master").

Now that your local Git repository has the latest, go ahead and push all the new commits to your fork:

Code Block
$ git push origin<you> master

This is an optional step. The "master" branch on your fork is not really used at all, but you can keep it up-to-date with the upstream repository if you want.

...

NOTE: Pull-requests that use the 'master' branch will not be accepted, even in your fork repository. There are too many things that can go wrong. Firstly, doing so will make it difficult to work on more than one (independent) set of changes at a time; working on 'master' will make your second set of changes dependent upon the first set of changes. Secondly, GitHub pull-requests are tied to branches, so GitHub will want to include all your commits into the same pull-request. Thirdly (and perhaps most importantly), if your commits are not approved, your 'master' branch history will have commits that don't actually appear in the official 'master' branch, and this could be problematic in the future. The 'master' branch in your fork should really be just the local branch that represents the official repository's 'master' branch - use it to pull changes from upstream origin and merge/rebase onto your topic branches.

...

If you have been working on this branch for a while, other changes may have been merged (from other pull-requests) into the upstream origin repository. Often times this is okay. However, sometimes your local change will be affected by recent merges. It is best to make sure that you update your local clone before you create your pull-request.

...

Code Block
$ git checkout master          # switches to the 'master' branch
$ git pull upstreamorigin master       # fetches all 'upstreamorigin' changes and merges
                               # 'upstreamorigin/master' onto your 'master' branch
$ git checkout fcrepo-1234     # switches to your topic branch
$ git rebase master            # reapplies your changes on top of the latest
                               # in master (i.e., the latest from master will
                               # be the new base for your changes)

...

After you have committed changes locally (and pulled from upstream), you can commit your changes to your fork repository and generate a pull-request. Pushing the changes is easy:

Code Block
$ git push origin<you> fcrepo-1234

This will push the commits on 'fcrepo-1234' up to the 'origin' repository (which is your fork on GitHub).

Create Pull-Request

After pushing your changes into your GitHub fork, you have published your changes but have not really told the Fedora community about them. To do this, generate a pull-request on GitHub. If your commits are on a branch other than 'master', be sure to update the commit range (changing 'master' to the correct branch name). Then record this on the JIRA ticket, and use the URL to the pull-request and include a good comment that describes your changes.  Finish the JIRA ticket;  the ticket will then be ready to deliver, and the integration managers will be alerted that you have a pull request outstanding.

...

This command deletes the remote branch in your fork repository on GitHub:

Code Block
$ git push origin<you> :fcrepo-1234

At first blush, the syntax of this second command is a little strange. It is actually a form of the "git push <remote> <localBranch>:<remoteBranch>" command. If you do not specify the local branch, this basically means push nothing onto the remote branch, and Git removes the remote branch.

...