kapunahelewong/angular-docs.md

## angular-docs.md

      
    Raw
  

              angular-docs.md
            
          
    Make sure you've read the Angular.io CONTRIBUTING.md before starting out.
Angular.io local setup

Follow these steps when you are setting up the repo locally for the first time and would like to view your changes in the browser as you edit.

Fork angular/angular.

In terminal:

git clone the-angular-repo-you-want-to-clone (your fork that you just made).
cd angular
git checkout -b yourname-branch-topic
yarn
cd aio
yarn setup
yarn start (alternatively, you can use yarn serve-and-sync to run both these processes simultaneously)
Open a new terminal tab or window in the same directory.
yarn docs-watch in new tab.
Open a third tab or window so you can issue git commands as you work.

Note: If you already have yarn running and you switch branches, the yarn proceses might break. Just Ctrl+C in the two yarn tabs and restart them.
In Chrome:

Go to localhost:4200

Where the docs are

Guides are in: aio/content/guide
Tutorial (Tour of Heroes) is in: aio/content/tutorial
Example apps: aio/content/examples
API docs: Go to the doc in question on angular.io and look near the top in the table where the source is listed. That's the file you'll edit in the API docs.

After working, go back to the third tab/window you’d opened in terminal and add, commit, and push. Here are helpful git commands:

git add --all
git commit -m “docs: the-edits-you-are-adding” Check out the Commit messages guidelines. If you're fixing an issue, add that so it closes the issue automatically on merge. Here's an example:

docs: fix typo in template syntax

Fixes ####


Where #### is the issue number you're fixing. (You can also say Closes.)

git push (You’ll get an error the first time you try this if you don’t have a branch on GitHub that mirrors this one you’re working on. Just use the command that the error suggests.)

Then go to your fork in GitHub and submit your PR against angular/angular. Tag me if you have any questions or would like me to review your PR. Well done! :)
How to rebase

Here's my own rebasing workflow and it's worked well for me. In my own fork of angular, I keep my master (origin master) up-to-date and then rebase my feature branch from origin master rather than by pulling from upstream (though there's nothing wrong with doing it that way that I know of). So here are my steps I do locally:

On master: git pull upstream master
On master: git push origin master (now I have my fork on github even with angular/angular).
Checkout my feature branch (for example if I have a branch called docs-fix): git checkout docs-fix
On docs-fix I rebase: git rebase origin/master
Then, push up: git push (might need -f, just be sure you understand force pushing before you do it)

Note: Your upstream should be https://github.com/angular/angular.git, which you can see with a git remote --v. If it isnʻt, add it with git remote add upstream https://github.com/angular/angular.git.
How to squash

Squash when you have multiple commits but want it all in one. Here is my workflow:

On my feature branch: git rebase -i HEAD~# where # is how many commits I want to squash. So, if I have 3 commits to squash into one, it would be git rebase -i HEAD~3.
Your default editor will open with a list of your commits at the top. Pick the one at the top and fixup (f) the rest in the list.
Save and exit your editor.
To double check you've done it right, do a git log or git log --oneline to see the commit log. Your fixed up ones should be no longer in the list and the one you picked should be the only one left of your commits on the feature branch.

How to amend a commit


On my feature branch (make sure you've checked out the right branch): git commit --amend
Your default editor will open. Change your commit message. Save and close.
Back at the command line, you can run git log or git log --oneline to confirm.
Then push back up. Your PR should reflect the updated commit message. (You might need -f, just be sure you understand force pushing before you do it)

What to do if you end up with a bunch of commits that aren't yours in your PR

I think this happens sometimes when we merge (like in git pull) master into our feature branch. Since I switched to using rebase and never merge, I haven't had this problem.
Before doing this, since your branch is in an undesirable state, back up your work. Copy and paste it somewhere outside of your project so that when git does its work it doesn't overwrite your back up.

First, on master (not your messed up branch), rebase (don't merge!) Instead, rebase according to the steps below.
On master: git pull upstream master
On master: git push origin master (now you should have your fork on github even with angular/angular).
git checkout your-messed-up-branch
Now, on your messed up branch: git rebase origin/master
If you now do a git log or git log --oneline, you should see that you're only ahead of master by your commits on this branch, for example, if I had 3 commits on my feature branch, I should see now that I am three commits ahead of master.

Now you can git push. Go look at your PR to see how many commits you have now and that your work remained in your PR. This is a baffling problem, so if these instructions don't work for you on the angular repo, please tag me. Maybe together we can figure it out.