Thursday, August 15, 2013

This article assumes you've used github but that you're not a pro at contributing to large projects.

After rolling out some internal angular.js apps for my team I found a lot of people can be confused by the angular docs. Its documentation covers many things, but the examples and explanations don't always make sense to those new to angular. Just the same as with any open-source project, the poor documentation is just as much my responsibility as it is the responsibility of anyone on the Angular team.

How much documentation had I written? How many pull requests had I sent? The answer, obviously was none, so I went to github, forked the project and decided to make theng:class docssuck a little bit less.

I was pretty sure at this point that it would take me about 5 minutes to come up with a better example, but it ended up taking me many nights to get it just right and finally get some small changes merged back into the main project.

I don't want you thinking it's too hard or a waste of time.It is totally worth it!I'll share what mistakes I made and what I found complicated, so you can help improve the docs right away!

Getting Setup

Before starting you'll need to have reasonably new versions of the following software installed on your machine:

Where is the documentation?

All of the documentation, including examples, is found within the angular.js source code. For example, the ng:class source code is located inside of thesrc/ng/directive/ngClass.jsfile. The code examples use custom markup (angular directives) that look something like this:

These correspond with the tabs generated in the example portion of the documentation.

Making Changes

When you are ready to start editing the documentation examples you can just press the "Edit" button included on each page. This button will take you to a working version of that example on a 3rd party site that you can modify to your liking.

Once you've modified the code enough paste it back into the comments of your source code, comment it out and make sure it works.

After you make a change you should

grunt docs:process

Once that's done you can check your work locally by running a webserver and viewing the documentation.

Some of the CSS used in the angular docs may be different from what is used on the site where you edited your example, so make sure you check out your example on the actual documentation site.

Testing your work

Angular has this amazing things where the tests are run from within the documentation. This is done inside of the<file name="scenario.js"></file>area in the<example></example>. More than likely the example you're updating already has some basic test, but you'll want to update it with your current code, process the docs, and the run them:

grunt docs:process
grunt test:e2e

Try to make your tests as comprehensive as possible.

Submitting your work

Once you have made sure your tests pass and you've got what you think is a better example than before you can submit your pull request to the team. Point your pull request at angular.js/master.

You will probably receive a lot of feedback about your pull request. My small changes to ng-class took about a month of back and forth before being merged whichyou can read yourself.

But I was super happy when they finally went live recently. Hurary

Helpful Tips

The team suggests that you rebase your code into a single commit. More info about usinggit rebase.

Solving Problems

What happens if my branch gets really out of date with the main angular branch?

In these cases you should rebase with the main angular repo and resolve any conlicts. The first step to doing that is setting up a new remote origin calledupstreamthat will let you hook directly into the angular repo.

git remote add upstream https://github.com/angular/angular.js.git

The second step will be to rebase your branch against that repo:

git rebase upstream/master

For more information about rebasing please check out github's suggested regarding this matter.

What about filling out the CLA?

A community licensicing agreement is basically a way for Google's lawyers to be sure that you're not going to claim you have any rights to the code after you give it to them. You can't sue them for abusing your pull request. It's unclear for contributing docs if it's required, but the instructions can be found here:http://docs.angularjs.org/misc/contribute