Contributing to the Angular docs

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.

1. Fork angular/angular.

In terminal:

1. git clone the-angular-repo-you-want-to-clone (your fork that you just made).
2. cd angular
3. git checkout -b yourname-branch-topic
4. yarn
5. cd aio
6. yarn setup
7. yarn start (alternatively, you can use yarn serve-and-sync to run both these processes simultaneously)
8. Open a new terminal tab or window in the same directory.
9. yarn docs-watch in new tab.
10. 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:

1. 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:

1. git add --all
2. 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.)

1. 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:

1. On master: git pull upstream master
2. On master: git push origin master (now I have my fork on github even with angular/angular).
3. Checkout my feature branch (for example if I have a branch called docs-fix): git checkout docs-fix
4. On docs-fix I rebase: git rebase origin/master
5. 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:

1. 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.
2. 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.
3. 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

1. On my feature branch (make sure you've checked out the right branch): git commit --amend
2. Your default editor will open. Change your commit message. Save and close.
3. Back at the command line, you can run git log or git log --oneline to confirm.
4. 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.

1. First, on master (not your messed up branch), rebase (don't merge!) Instead, rebase according to the steps below.
2. On master: git pull upstream master
3. On master: git push origin master (now you should have your fork on github even with angular/angular).
4. git checkout your-messed-up-branch
5. Now, on your messed up branch: git rebase origin/master
6. 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.

Hi! Please note that in the In terminal: section bullet points 2 and 3 should switch places. Thanks!

Thanks

Thanks, @dannyskoog. Fixed! 🌸

Consider adding info related to point 1 under How to rebase on that the upstream has to be added if it's the first time pulling from it. I.e. performing git remote add upstream https://github.com/angular/angular.git. Otherwise the GIT command will fail

I guess after amend the commit message we have to force push right? git push -f

@risrawat90, yes, usually, but since a force push can overwrite someone elseʻs work, Iʻve left that up to the reader. So, if you were collaborating but didnʻt have the other personʻs changes locally, and you force pushed, youʻd overwrite their work. If youʻre working alone, it isnʻt a problem, you just use git push -f. I just hesitate to ever tell someone to outright force push, especially if theyʻre new to it.

Thank you, @dannyskoog. Adding now. :)

Edit: @risrawat90, I added a note. Thanks for pointing that out.

This is really helpful!

I would add a link to the commit message guidelines in the section about making your first commit.

I would also mention something about using Fixes #xxx or Closes #xxx in the footer as that isn't covered in those guidelines.

Added. Thank you, @Splaktar!

Absolute gold 🥇 👏

Thank you, @alyssamichelle!! ❤️🤗

Visiting this page REGULARLY ;)

Thanks for saving so much of my time!

Thank you, @BioPhoton!

Btw, we're adding an official doc based on this in case anyone is looking for clarification on any of the steps. 🎉Please everyone, feel free to comment on it, or on this doc (this one will stay up, even when that doc is merged). angular/angular#36379

Thank you for following up on my PR and recommending this gist, @kapunahelewong. This helped me get my first approval... ever.

This sentiment exactly-

Absolute gold 🥇 👏

Thank you for following up on my PR and recommending this gist, @kapunahelewong. This helped me get my first approval... ever.

This sentiment exactly-

Absolute gold 🥇 👏

Awwww, thank you, @alexDtorres!! I'm so glad! And congratulations!!!