...
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 ModeShape Fedora repository on GitHub and click on the "Fork" button
Step 3: Clone your fork, using the private URL. At a command line, go to a directory where you want the new local repository, and issue the following:
| Code Block |
|---|
$ git clone git@github.com:<you>/ |
...
fcrepo4.git |
This can take as long as a minute or two. But when it does finish you'll When this finishes you will have a local clone of your fork, complete with a remote named 'origin' that points back to your fork on GitHub (not the original).
Step 4: Tell your local clone about the official upstream repository on GitHub:
| Code Block |
|---|
$ cd |
...
fcrepo4 $ git remote add upstream git://github.com/ |
...
futures/ |
...
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.
Pulling Upstream Changes
Start by ensuring that you 're are on the 'master' branch and that you 've got have no local changes:
| Code Block |
|---|
$ git checkout master |
...
$ git status |
The last command should report something like:
| Code Block |
|---|
# On branch master |
...
nothing to commit (working directory clean) |
Now, we need to pull any changes made to the official upstream 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 |
...
The first is more direct, but it only gets the changes for one branch ("master" in this case) and because the merge is not explicit it can be confusing for new Git users that the 'pull' actually results in a merge conflict (e.g., if the files you 've have changed locally were also modified in the upstream). The latter uses an explicit merge and also fetches all branches (including any new branches that were created since you cloned your repository and/or added 'upstream' as a remote). You can list all branches with:
| Code Block |
|---|
$ git branch -a |
...
If you don't 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 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.
Make Changes
All changes should be made on topic branches, typically named according to the JIRA PivotalTracker issue. (We recommend Recommended naming them convention "modefcrepo-xxxx".) There 's is nothing special about a "topic" branch -- it 's is just a normal Git branch that you create and use for a specific topic (i.e., JIRA Pivotal issue).
NOTE: We will not accept pullPull-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 and merge/rebase onto your topic branches.
To create a topic branch, start on a branch you want to base from (which is often 'master'). The following command creates a new branch named "modefcrepo-1234" (based off of 'master') and then checks out that branch:
| Code Block |
|---|
$ git checkout -b |
...
fcrepo-1234 master |
Your working directly reflects Work directly in the new "modefcrepo-1234" branch, and this . This is where you make your changes and run your new/modified unit tests. When you 're are happy, stage your changes with:
| Code Block |
|---|
$ git add . |
and do Do a complete integration build to make sure your new tests pass and that your changes didn't did not cause a regression:
| Code Block |
|---|
$ mvn clean install |
----------------------------------
or, if you want to build the kits and run the integration tests, add the "integration" profile:
...
# 'upstream/master' onto your 'master' branch
$ git checkout modefcrepo-1234 # switches to your topic branch
...
# be the new base for your changes)
At this point, your "modefcrepo-1234" branch has been updated (rebased), and you can proceed.
...
After you've 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:
$ git push origin modefcrepo-1234
This will push the commits on 'modefcrepo-1234' up to the 'origin' repository (which is your fork on GitHub).
...
The aforementioned process adds your new commits to the pull-request. But sometimes, the integration managers will request just a few smaller changes, and making a separate commit for those small changes is less desirable. Instead, in this case we suggest that you make the changes and then amend your previous commit. This helps keep related changes in fewer commits, and makes it easier to apply the changes to other branches. Yes, amended commits actually do change history, so be sure to do this only with commits that appear only on a topic branch. We think it is perfectly acceptable (and sometimes preferable) to amend/change the commits on a pull request before it is merged onto an official branch (before this, a PR is really "proposed code"). The procedure is pretty straightforward. On your local branch (e.g., "modefcrepo-1234") that you used to push to your fork (e.g., "origin") and create the PR, make any additional changes to the code and then:
...
$ git commit --amend .
$ git push -f origin modefcrepo-1234
GitHub will automatically update the pull-request, where it can be reviewed once again.
...
This command will delete a local topic branch:
$ git branch -D modefcrepo-1234
while this command deletes the remote branch in your fork repository on GitHub:
$ git push origin :modefcrepo-1234
At first blush, the syntax of this second command is a little strange. It's actually a form of the "git push <remote> <localBranch>:<remoteBranch>" command. If you don't specify the local branch, this basically means push nothing onto the remote branch, and Git removes the remote branch.
...