Working with Angular PatternFly & Git
Install Git locally
Review Interactive Git Tutorial
git clone copies/downloads the code in the remote ‘master’ branch of the angular-patternfly git repo., locally to your machine:
mkdir repos
cd repos
git clone [email protected]:patternfly/angular-patternfly.git
cd angular-patternfly
angular-patternfly> ls
bower.json Gruntfile.js index.js src test
This is a copy of the code in angular-patternfly#master branch. Your local branch is also called 'master'
angular-patternfly>git branch
* master
How does your local branch compare to the remote, master Angular-Patternfly repo.?
angular-patternfly>git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working tree clean
Wait, what's this origin thing? origin is referring to the remote branch which your local master branch is tracking against. origin was initially set when you did a git clone.
git remote -v
origin [email protected]:patternfly/angular-patternfly.git (fetch)
origin [email protected]:patternfly/angular-patternfly.git (push)
Basically, when git status says Your branch is up-to-date with 'origin/master' it means "Your [local] branch [master in this case] is up-to-date with [the remote branch [email protected]:patternfly/angular-patternfly.git]". In the next section, we'll create a dev branch, make some code changes, and push those changes up to your remote forked (copy of) the angular-patternfly repo.
At this point you have a local angular-patternfly repo which is tracked/backed by the remote/origin angular-patternfly repo. First, you want to make sure your local 'master' branch is up-to-date with the remote master. We do that in two steps:
-
git fetch origin-this will just get the latest metadata from origin/master, does not affect your local branch. -
git rebase origin/master-this will affect your local branch. Basically new commits you have done in this local branch will be put on top of whatever the latest is in origin/master. You may get merge conflicts if you have changed a file which had also changed in origin/master since your last rebase.
Once git status says your master branch is up to date with origin/master, create a new branch to work from:
git checkout -b myNewFeatureOrFix
Switched to a new branch 'myNewFeatureOrFix'
Let's create a new file and commit it locally:
touch mynewcode.js
This should create a new file.
git status
On branch myNewFeatureOrFix
Your branch is up-to-date with 'origin/master'.
Untracked files:
(use "git add <file>..." to include in what will be committed)
mynewcode.js
nothing added to commit but untracked files present (use "git add" to track)
We created a new file, but it is 'untracked' and Git doesn't know anything about it, yet. So let's follow the instructions and do a git add
git add mynewcode.js
angular-patternfly>git status
On branch myNewFeatureOrFix
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
new file: mynewcode.js
Now our file is added or staged to commit, let's commit the file locally:
git commit -m "fix(pfFooBar): I fixed some stuff"
[myNewFeatureOrFix bfda57dd] fix(pfFooBar): I fixed some stuff
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 mynewcode.js
Now the file is committed. Notice the commit message is formatted as fix(pfFooBar): I fixed some stuff. We use git-commit-guidelines to auto-publish changes after a PR is merged. For example, suppose angular-patternfly is a at version 4.1.3:
fix(...) would equal 4.1.4 - patch release
feat(...) would equal 4.2.3 - minor release
perf(...) would equal 5.0.0 - major release
chore(...) would equal 4.1.4 - no version bump
You should now be able to see your commit in your local git log:
angular-patternfly>git log --oneline
f46ccdb8 (HEAD -> myNewFeatureOrFix, dave/myNewFeatureOrFix) fix(pfFooBar): I fixed some stuff
0012ea6c (dave/pfTableView_sorting, pfTableView_sorting, master) fix(pfTableView): Fixed sort col when show/hiding checkbox col
...
...
The first line is your new commit, the following lines are whatever was in origin/master when you last rebased.
The way you post your code for others to review is by creating a pull request (PR).
Ok, now it gets a little complicated. So far you have a local dev branch, with one local commit, backed by remote angular-patternfly repo. We could git push your dev branch & commit to remote origin/angular-patternfly, but if we follow this process all developers would be pushing their dev branches up to remote angular-patternfly, the gold master. That might lead to a lot of orphaned dev branches in our master repo.
Instead, the preferred process is to create a remote copy of origin/angular-patternfly -your 'fork' to work with.
Fork'ing a repo. makes a remote copy of a repo., kind of your remote, online copy/sandbox of the original repo. This is different from Cloning a repo., which also creates a copy, but that copy is downloaded to your local machine, whereas Forking a repo., creates a remote/online copy in GitHub.
Goto https://github.com/patternfly/angular-patternfly and click on the Fork button:
On the next screen choose your github username/profile to create the fork under. Once the fork is done, you should see your forked repo. It's title will be <your-github-username>/angular-patternfly....forked from patternfly/angular-patternfly.
Now that you have created a fork, you must let your local branch know about it, so it can push and fetch from it. First, take a look at your local remote branches:
git remote -v
origin [email protected]:patternfly/angular-patternfly.git (fetch)
origin [email protected]:patternfly/angular-patternfly.git (push)
To add my new fork:
git remote add dave [email protected]:dtaylor113/angular-patternfly.git git remote -v dave [email protected]:dtaylor113/angular-patternfly.git (fetch) dave [email protected]:dtaylor113/angular-patternfly.git (push) origin [email protected]:patternfly/angular-patternfly.git (fetch) origin [email protected]:patternfly/angular-patternfly.git (push)
Now you will be able to push your local changes up to your fork, then create a Pull Request (PR) between your fork and origin/angular-patternfly master. This way the only time origin/angular-patternfly repo. is changed is after a PR is merged; after all the code has been reviewed and TravisCI tests have been passed.
Let's push your dev branch, which has your code change in a commit, up to dave's fork:
git push -f dave
The -f means force -meaning overwrite or create the branch myNewFeatureOrFix on dave.
So, to summarize the process/flow:
-
git checkout master- switch to your local master -
git fetch origin- get latest metadata from origin -
git rebase origin/master- update your local master to origin/master -
git checkout -b myChanges- create dev branch - Make initial changes
-
git add & commit- make sure your commit msg adheres to git-commit-guidelines - Assuming some time has passed as you worked, repeat steps 2 & 3 before pushing your changes to your fork.
git push -f <remote-fork-name>- Open a Pull Request - see next section
At this point you have your dev branch on your fork. To open a pull request you can go to your fork:
Or you can always goto https://github.com/patternfly/angular-patternfly/pulls, click on the big green "New Pull Request" button, then make sure you click on the "compare across forks" link. You shouldn't have to change the first two 'base' dropdowns but change the last two 'head' dropdowns to be your fork and dev branch. Click on the big green "Create Pull Request" button:
- Be sure to assign Reviewers
- There is a PR template, please update the Description, add a 'fixes' label. Ex: 'fixes #322' to indicate what Issue this PR addresses (after merge the PR will automatically close the associated Issue).
- Check off items in the checklist which apply. For example, if you have attached screenshots or updated unit tests. For visual changes be sure to add Chris and/or Coleen.
- When done, click on the green "Create pull request" button. This will create the PR and the Reviewers will be notified.
Unless you are a flawless coder like myself :-) , reviewers are bound to comment and request changes for your PR. Make and commit additional changes locally. You can push -f <fork-name> to get these new commits up to your fork -the PR will automatically detect changes in the fork.
Once the PR has been reviewed and approved by at least two reviewers, you should squash all PR commits into a single commit with appropriate commit msg (fix, feat, chore, etc..). To squash commits, execute locally:
git rebase --interactive <SHA>, or...
git rebase -i HEAD~2 -to list last two commits
For more details, please checkout this nice writeup on git rebase -i
At this point a repo. maintainer may merge the PR. Once the PR is merged checkout: https://github.com/patternfly/angular-patternfly/releases and after a few minutes you should see a version bump (assuming you did anything but a chore(...) commit.
If you have been assigned as a Reviewer on a PR, you can add comments under the "Conversation" tab, or click on the "Files changed" tab and add comments to individual lines or Approve or Request Changes for the entire PR:
Ideally, in addition to reviewing the code, devs should download and run the PR's code, and test changes in angular-patternfly's ngDocs.
To run/review a developers code for a PR they created you’ll need to first add their forked a-pf repo. as a remote for your local angular-patternfly repo. If I wanted to run Nicole's PR code, I would:
git remote add nicole [email protected]:nicolethoen/angular-patternfly.git (one time step)
git fetch nicole
git checkout nicole/<pr-branch>
This puts you in a 'detached HEAD' state, meaning you are on a temporary branch. If the PR has changed dependencies be sure to npm install & bower install. To run and see the code changes in action, execute grunt build and grunt serve. This will bring up the angular-patternfly ngDocs with these PR changes.
If you want to make the branch more permanent, execute:
git checkout -b <new-branch-name>
Then if the PR's code changes, you can simply execute the following to get the latest PR code changes:
git fetch nicole
git rebase nicole/<pr-branch>
