docs(dev): rewrite most of the dev docs

eGlobeBizCom · Mar 29, 2014 · cc6386f · cc6386f
1 parent 862667b
commit cc6386f
Show file tree

Hide file tree

Showing 7 changed files with 219 additions and 73 deletions.
diff --git a/docs/dev/01-contributing.md b/docs/dev/01-contributing.md
@@ -0,0 +1,46 @@
+pageTitle: Contributing to Karma
+
+
+You wanna contribute to Karma? That is truly great!
+Here are some tips to get you started...
+
+You might also find [set up the workspace] helpful.
+
+### Help others
+The best way to start contributing to any open source project is to help other people.
+You can answer questions on the [mailing list] or [Stack Overflow].
+Either find something you already know the answer for, or something you feel interested in and
+dig into it a little bit to find the answer.
+
+Soon, you will realize you know Karma pretty well...
+
+
+### Improve the documentation
+You don’t feel like hacking on the code, but still wanna help?
+Improving the documentation is very valuable as it will help many others.
+
+All the source code is in [`docs/`].
+
+
+### Fix something that bothers you
+You found a bug that really bothers you? It’s more likely it bothers other users too and maybe
+it’s not that hard to fix it! Try to find an existing issue. If it does not exist yet, create one.
+Look into the code and let others know what solution you are thinking about.
+Then, send a pull request and let other contributors to review.
+
+[Here](./making-changes.html) is some more info on how to set up your workspace and send a pull
+request.
+
+### Review others work
+Check out the list of outstanding pull requests if there is something you might be interested in.
+Maybe somebody is trying to fix that stupid bug that bothers you. Review the PR.
+Do you have any better ideas how to fix this problem? Let us know...
+
+### I wanna help more
+Check out [Maintaining Karma]. Becoming a Karma maintainer is simple.
+You just do it. There is no test to pass ;-)
+
+[mailing list]: https://groups.google.com/forum/#!forum/karma-users
+[Stack Overflow]: http://stackoverflow.com/questions/tagged/karma-runner
+[`docs/`]: https://github.com/karma-runner/karma/tree/master/docs
+[Maintaining Karma]: ./maintaining.html
diff --git a/docs/dev/02-making-changes.md b/docs/dev/02-making-changes.md
@@ -0,0 +1,99 @@
+<!---
+TODO:
+- add more info about updating PR
+  - rebasing/squashing changes
+  - making sure Travis is green
+- how to run tests on sauce labs
+- how to set up plugins
+-->
+
+If you are thinking about making Karma better, or you just want to hack on it, that’s great!
+Here are some tips on how to set up a Karma workspace and how to send a good pull request.
+
+## Setting up the Workspace
+
+* Make sure you have a [GitHub account](https://github.com/signup/free).
+* [Fork the repository] on GitHub.
+* Clone your fork.
+  ```bash
+  $ git clone git@github.com:<your-username>/karma.git
+  $ cd karma
+  ```
+* Init the workspace
+  ```bash
+  $ ./scripts/init-dev-env.js
+  ```
+
+## Testing and Building
+- Run the tests via:
+  ```bash
+  $ grunt test:unit
+  $ grunt test:e2e
+  $ grunt test:client
+
+  # All tests.
+  $ grunt test
+  ```
+
+- Lint the code via:
+  ```bash
+  $ grunt lint
+  ```
+
+- Build the client code via:
+  ```bash
+  $ grunt build
+  ```
+
+The default task, just calling `grunt` will run `build lint test`.
+
+## Changing the Code
+Checkout a new branch and name it accordingly to what you intend to do:
+- Features get the prefix `feature-`.
+- Bug fixes get the prefix `fix-`.
+- Improvements to the documentation get the prefix `docs-`.
+```bash
+$ git checkout -b <branch_name>
+```
+
+Open your favourite editor, make some changes, run the tests, change the code, run the tests,
+change the code, run the tests, etc.
+
+- Please follow http://nodeguide.com/style.html (with exception of 100 characters per line).
+
+
+## Sending a Pull Request
+
+- Commit your changes (**please follow our [commit message conventions]**):
+  ```bash
+  $ git commit -m "..."
+  ```
+- Push to your github repo:
+  ```bash
+  $ git push origin <branch_name>
+  ```
+- Go to the github page and click "Open a Pull reguest".
+- Write a good description of the change.
+
+After sending a pull request, other developers will review and discuss your change.
+Please address all the comments. Once everything is all right, one of the maintainers will merge
+your changes in.
+
+
+## Contributor License Agreement
+Please sign our Contributor License Agreement (CLA) before sending pull requests.
+For any code changes to be accepted, the CLA must be signed. It's a quick process, we promise!
+- For individuals we have a [simple click-through form].
+- For corporations we'll need you to print, sign and one of scan+email, fax or mail [the form].
+
+## Additional Resources
+
+- [Mailing List](https://groups.google.com/forum/#!forum/karma-users)
+- [Issue tracker](https://github.com/karma-runner/karma/issues)
+- [General GitHub documentation](http://help.github.com/)
+- [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
+
+[commit message conventions]: git-commit-msg.html
+[simple click-through form]: http://code.google.com/legal/individual-cla-v1.0.html
+[the form]: http://code.google.com/legal/corporate-cla-v1.0.html
+[Fork the repository]: https://github.com/karma-runner/karma/fork
diff --git a/docs/dev/03-contributing.md b/docs/dev/03-contributing.md
diff --git a/docs/dev/03-maintaining.md b/docs/dev/03-maintaining.md
@@ -0,0 +1,74 @@
+pageTitle: Maintaining Karma
+
+
+
+This document is for people working on Karma. It describes common tasks such as triaging or merging
+pull requests.
+
+If you are interested in contributing to Karma, you might check out [Contributing to Karma].
+
+We use [gitter/karma-runner] to talk about pull requests and issues, stuff like,
+“hey this is important, can you look into it...”, “I’m not sure what to do about this issue...”.
+
+
+## Triaging issues
+New issues pop up every day. We need to identify urgent issues (such as “nobody can install karma”),
+close duplicates, answer questions, etc.
+
+See [angular/TRIAGING.md] for more info.
+
+An issue or pull request is untriaged (needs to be triaged) when it is not assigned to any milestone.
+
+## Merging a pull request
+Please, make sure:
+- Travis build is green.
+- At least one owner (other than you) approved the PR
+  - by commenting “LGTM” or something like that.
+  - if it’s just a simple docs change or a typo fix, feel free to skip this step.
+- All the commits follow the [convention].
+  - This is very important, because the auto-release tasks depend on it.
+  - Commits are squashed. Each change is a single commit.
+    - e.g. if the PR contains two changes such as, `fix(web-server): xxx` and then `style(web-server): missing semicolons`; it should be two separate changes
+    - e.g. if the first commit is `fix(web-server): serve binary files` and a second commit is “fix unit tests broken in the previous commit”, you should squash them into a single commit.
+  - It’s alright to ask the author of the pull request to fix any of the above.
+
+### There are two branches:
+- **master** is what gets automatically released into the “canary” channel (`npm install karma@canary`).
+- **stable** is what gets automatically released into the “stable” channel (`npm install karma`)
+
+Once the PR is ready to be merged, merge it into the master.
+You can use the “green button” on GitHub.
+
+If it’s a bug fix or just a documentation change that is relevant to the current stable branch,
+please cherry pick the change to the stable branch too.
+
+**No new features or breaking changes can go into the stable branch.**
+
+An easy way to merge a pull request is to use the [fetch_pr] and [merge_pr] scripts.
+
+
+## Ownership
+Every project has one or more owners (or “maintainers”), listed in `owners` field of the
+`package.json`. Typically, owners have push permissions.
+
+Being a maintainer of one plugin doesn’t mean you can’t contribute to some other plugins.
+In fact, you can be a maintainer of multiple projects. The main point is to have people who are
+familiar with the codebase and therefore can better decide what is a good change or not.
+
+
+## Becoming a maintainer
+If you are interest in becoming a Karma maintainer, start by triaging issues, reviewing pull
+requests and stop by at [gitter/karma-runner]. Once we see you are helping, we will give you push
+permissions. Being a maintainer is not an obligation. You can help when you have time and be less
+active when you don’t. If you get a new job and get busy, that’s alright.
+
+These are all just recommendations, something we found to be helpful for us to be more efficient.
+Nothing is set in a stone. If you feel like there is a way to improve this workflow,
+please send a proposal to [karma-devs@googlegroups.com](mailto:karma-devs@googlegroups.com).
+
+[gitter/karma-runner]: https://gitter.im/karma-runner
+[convention]: http://karma-runner.github.io/0.12/dev/git-commit-msg.html
+[fetch_pr]: https://github.com/vojtajina/dotfiles/blob/master/bin/fetch_pr
+[merge_pr]: https://github.com/vojtajina/dotfiles/blob/master/bin/merge_pr
+[Contributing to Karma]: ./contributing.html
+[angular/TRIAGING.md]: https://github.com/angular/angular.js/blob/master/TRIAGING.md
diff --git a/docs/dev/01-public-api.md → docs/dev/04-public-api.md b/docs/dev/01-public-api.md → docs/dev/04-public-api.md
diff --git a/docs/dev/02-plugins.md → docs/dev/05-plugins.md b/docs/dev/02-plugins.md → docs/dev/05-plugins.md
diff --git a/docs/dev/04-git-commit-msg.md → docs/dev/06-git-commit-msg.md b/docs/dev/04-git-commit-msg.md → docs/dev/06-git-commit-msg.md