web/video.js
1
0
Fork 0
mirror of https://github.com/videojs/video.js.git synced 2024-11-24 08:42:25 +02:00
Code Releases Activity

Merge branch 'contrib-guide' of git://github.com/BCjwhisenant/video-js into BCjwhisenant-contrib-guide

Browse Source 
Conflicts:
	CONTRIBUTING.md
This commit is contained in:
Steve Heffernan 2013-07-17 17:49:19 -07:00
commit 150facab44
1 changed files with 121 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

198
CONTRIBUTING.md
View File

@ -1,18 +1,19 @@
So you're telling me you want to spend some of your precious time giving back to this humble project? You're crazy. But since you're here...there are some ways you can help make Video.js a faster, easier, more compatible, and more fully-featured video player.
If you're on this page, you must be interested in spending some time giving back to this humble project. If that's the case, fantastic! Here are some ways you can help make Video.js a faster, easier, and more fully-featured video player.
* Bug reports and fixes
* Features and changes (pull requests)
* Features and changes
* [Answer questions](http://stackoverflow.com/questions/tagged/video.js) on Stack Overflow
* Other Video.js projects
Don't miss the [code style guide](#code-style).
Thanks again for helping out! One thing we ask is that you refer to the [code style guide](#code-style) when writing your code.
# Getting started
1. [Download and install Node.js](http://nodejs.org/download/). Video.js uses Node for build and test automation.
There is a known issue between Node.js version 0.10.x and phantomjs. This will manifest itself during the node module installation (see step 4 below). For the time being, please install Node.js version 0.8.22 or earlier. You can find earlier versions of Node.js [here](http://nodejs.org/dist/).
1. [Download and install Node.js](http://nodejs.org/download/). Video.js uses Node for build and test automation. Node is available for Windows, Mac OS X, Linux, and SunOS, as well as source code, in case you want to build it yourself.
2. [Fork](http://help.github.com/fork-a-repo/) and clone the video.js git repository.
2. Fork the video.js git repository. At the top of every github page, there is a Fork button. Click it, and the forking process will copy Video.js into your organization. You can find more information on [Forking a Github repository](http://help.github.com/fork-a-repo/) here.
3. Clone your copy of video.js to your local workstation.
```bash
# Clones your fork of the repo into the current directory in terminal
@ -30,124 +31,167 @@ Don't miss the [code style guide](#code-style).
git pull upstream master
```
3. Install the grunt-cli package so that you will have the correct version of grunt available from any project that needs it. This should be done as a global install:
4. Install the grunt-cli package so that you will have the correct version of grunt available for any project that needs it. This should be done as a global install:
On Unix-based systems, you'll have to do this as a superuser:
```bash
sudo npm install -g grunt-cli
```
On Windows, you can just run:
```bash
npm install -g grunt-cli
```
4. Install required node.js modules using node package manager.
5. Install the contribflow package. This is a package from Zencoder that video.js developed to streamline the workflow for new features and hotfixes.
On Unix-based systems, you'll have to do this as a superuser:
```bash
sudo npm install -g contribflow
```
On Windows, you can just run:
```bash
npm install -g contribflow
```
6. Install required node.js modules using node package manager.
You do not need to install these modules as a superuser, so for all platforms run:
```bash
npm install
```
5. Build a local copy. Video.js uses [grunt](http://gruntjs.com), a node-based task automation tool for building and tesing. The following will compile a local copy in the dist/ directory and run tests. It will also create a sourcelist.js file that can be used to load the video.js source scripts in a page.
A note to Windows developers: If you run npm commands, and you find that your command prompt colors have suddenly reversed, you can configure npm to set color to false to prevent this from happening.
```bash
npm config set color false
```
Note that this change takes effect when a new command prompt window is opened; the current window will not be affected.
7. Build a local copy and run the current suite of tests.
```bash
grunt
```
6. When you're ready to add a feature, make a change, or fix a bug, first create a new branch for it. Prefix the branch with the correspoding [issue number](https://github.com/zencoder/video-js/issues). If there isn't one, submit a new issue. Anything more complicated than simple docs changes should have an issue.
To run the QUnit test suite, run:
```bash
git checkout -b <####-branch-name>
grunt test
```
Be sure to reference your issue in any commit message. Github allows you to do this though the [fixes or closes](https://github.com/blog/831-issues-2-0-the-next-generation) keywords.
8. Depending on whether you're adding something new, making a change or fixing a bug, you'll want to do some up-front preparation.
1. If you're fixing a bug, submit an issue for it. If you're fixing an existing bug, claim it by adding a comment to it. This will give a heads-up to anyone watching the issue that you're working on a fix. Please refer to the [Bugs](#bugs) section below for guidelines on filing new issues.
2. Create a new branch for your work.
If you're adding new functionality instead, you only need to create a new branch for your work. When you submit a Pull Request, Github automatically opens a new issue to track it.
Since the issue filing process is described elsewhere, let's assume that you've filed or claimed the issue already.
Next, create the branch. You'll use contrib to do this task.
Run this command for new features:
```bash
My commit message. fixes #123
contrib feature start
```
Run this command if you're fixing an issue:
```bash
contrib hotfix start
```
You will be prompted to name the branch. After that, contrib will create the branch locally, and use git to push it up to your origin, and track it. You're now ready to start building your feature or fixing that bug!
9. Thoroughly test your feature or fix. If you're fixing a bug, we recommend in addition to testing the fix itself, to do some testing around the areas that your fix has touched. For example, a brief smoketest of the player never hurts.
10. Commit and push your feature or hotfix locally. You'll use Git directly for these tasks.
Be sure to reference your issue in any commit message. Github allows you to do this through the [fixes](https://github.com/blog/831-issues-2-0-the-next-generation) keyword.
```bash
My commit message. fixes issue#123
Testing:
(briefly describe any testing here, for example, 'unit tests and cross-browser manual tests around playback and network interruption')
```
11. Use contrib to submit your [Pull Request](#pull-requests).
First, checkout your feature or issue branch:
```bash
git checkout (branchname)
```
Next, submit your Pull Request, for your new feature:
```bash
contrib feature submit
```
Or for your bug fix:
```bash
contrib hotfix submit
```
You'll be prompted for title and description for the Pull Request. After that, contrib will use Git to submit your Pull Request to video.js.
12. You're Done! (except for cleanup.) To clean up your feature or hotfix branch:
First, checkout your feature or issue branch:
```bash
git checkout (branchname)
```
Run this command to clean up your feature:
```bash
contrib feature delete
```
Run this command to clean up your bug fix:
```bash
contrib hotfix delete
```
PLEASE NOTE: THIS WILL DELETE YOUR LOCAL AND REMOTE COPIES OF THE FEATURE.
This is meant to clean up your local and remote branches, so make sure any changes you don't want to lose have been pulled into the parent project or another branch first.
# Bugs
A bug is a _demonstrable problem_ that is caused by the code in the
repository. Good bug reports are extremely helpful - thank you!
**A bug is a demonstrable problem** that is caused by the code in the repository. Good bug reports are extremely helpful. Thank You!
Guidelines for bug reports:
1. **Use the [GitHub issue search](https://github.com/zencoder/video-js/issues)** &mdash; check if the issue has already been reported.
1. Use the [GitHub issue search](https://github.com/zencoder/video-js/issues) &mdash; check if the issue has already been reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the latest `master` branch in the repository.
2. Check if the issue has been fixed &mdash; try to reproduce it using the latest `master` branch in the repository.
3. **Isolate the problem** &mdash; ideally create a [reduced test
case](http://css-tricks.com/6263-reduced-test-cases/) and a live example.
3. Isolate the problem &mdash; ideally create a [reduced test case](http://css-tricks.com/6263-reduced-test-cases/) and a live example.
A good bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as possible in your report. What is your environment? What steps will reproduce the issue? What browser(s), OS, and devices experience the problem? What would you expect to be the outcome? All these
details will help people to fix any potential bugs.
A good bug report should be as detailed as possible, so that others won't have to follow up for the essential details.
Example:
Here's an example:
> Short and descriptive example bug report title
> Short yet concise Bug Summary
>
> A summary of the issue and the browser/OS environment in which it occurs. If
> suitable, include the steps required to reproduce the bug.
> Description
> Happens on Windows 7 and OSX. Seen with IE9, Firefox 19 OSX, Chrome 21, Flash 11.6 and 11.2
>
> 1. This is the first step
> 2. This is the second step
> 3. Further steps, etc.
>
> `<url>` (a link to the reduced test case)
> Expected:
> (describe the expected outcome of the steps above)
>
> Actual:
> (describe what actually happens)
>
> `<url>` (a link to the reduced test case, if it exists)
>
> Any other information you want to share that is relevant to the issue being
> reported. This might include the lines of code that you have identified as
> causing the bug, and potential solutions (and your opinions on their
> merits).
**[File a bug report](https://github.com/h5bp/html5-boilerplate/issues/)**
**[File a bug report](https://github.com/zencoder/video-js/issues/new)**
### NOTE: Testing Flash Locally in Chrome
Chrome 21+ (as of 2013/01/01) doens't run Flash files that are local and loaded into a locally accessed page (file:///). To get around this you need to [disable the version of Flash](http://helpx.adobe.com/flash-player/kb/flash-player-google-chrome.html#How_can_I_run_debugger_or_alternate_versions_of_Flash_Player_in_Google_Chrome) included with Chrome and enable a system-wide version of Flash.
Chrome 21+ (as of 2013/01/01) doens't run Flash files that are local and loaded into a locally accessed page (file:///).
To get around this you can do either of the following:
1. Do your development and testing using a local HTTP server.
## Pull requests
Good pull requests - patches, improvements, new features - are a fantastic help. They should remain focused in scope and avoid containing unrelated commits. If your contribution involves a significant amount of work or substantial changes to any part of the project, please open an issue to discuss it first.
Make sure to adhere to the coding conventions used throughout a project (indentation, accurate comments, etc.). Please update any documentation that is relevant to the change you're making.
Please follow this process; it's the best way to get your work included in the project:
1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork, and configure the remotes:
```bash
# Clones your fork of the repo into the current directory in terminal
git clone https://github.com/<your-username>/html5-boilerplate.git
# Navigate to the newly cloned directory
cd html5-boilerplate
# Assigns the original repo to a remote called "upstream"
git remote add upstream https://github.com/h5bp/html5-boilerplate.git
```
2. If you cloned a while ago, get the latest changes from upstream:
```bash
git checkout master
git pull upstream master
```
3. Create a new topic branch to contain your feature, change, or fix:
```bash
git checkout -b <topic-branch-name>
```
4. Commit your changes in logical chunks. Please adhere to these [git commit message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) or your pull request is unlikely be merged into the main project. Use git's [interactive rebase](https://help.github.com/articles/interactive-rebase) feature to tidy up your commits before making them public.
5. Locally merge (or rebase) the upstream development branch into your topic branch:
```bash
git pull [--rebase] upstream master
```
6. Push your topic branch up to your fork:
```bash
git push origin <topic-branch-name>
```
10. [Open a Pull Request](http://help.github.com/send-pull-requests/) with a clear title and description.
2. [Disable the version of Flash included with Chrome](http://helpx.adobe.com/flash-player/kb/flash-player-google-chrome.html#How_can_I_run_debugger_or_alternate_versions_of_Flash_Player_in_Google_Chrome) and enable a system-wide version of Flash instead.
# Code Style
Please follow [Google's JavaScript Style Guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml) to the letter. If your editor supports [.editorconfig](http://editorconfig.org/#download) it will make it easier to manage differences from your own coding style.