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

Updated readme and contrib guide. closes #645 close #397

Browse Source 
With changes from @sh1ps and myself
This commit is contained in:
Steve Heffernan 2013-07-17 17:51:29 -07:00
parent 150facab44
commit 91da153c02
5 changed files with 209 additions and 216 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
.zenflow
View File

@ -1,10 +0,0 @@
---
confirm_review: true
backup_remote: false
release_branch: stable
project: videojs
qa_branch: false
staging_branch: false
development_branch: master
remote: origin
confirm_staging: false

358
CONTRIBUTING.md
View File

@ -1,161 +1,34 @@
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.
CONTRIBUTING
============
So you want to help out? Great! There's a number of ways you can get involved.
* Bug reports and fixes
* Features and changes
* [Answer questions](http://stackoverflow.com/questions/tagged/video.js) on Stack Overflow
* Other Video.js projects
* [File and discuss issues](#filing-issues)
* [Contribute code](#contribute-code)
* [Build and share plugins](docs/plugins.md)
* [Answer questions on Stack Overflow](http://stackoverflow.com/questions/tagged/video.js)
Thanks again for helping out! One thing we ask is that you refer to the [code style guide](#code-style) when writing your code.
There's also other Video.js projects where you can help. (check the [video.js org](https://github.com/videojs) for an up-to-date list of projects)
# Getting started
* [Videojs.com](https://github.com/videojs/videojs.com)
* [Video.js flash player](https://github.com/videojs/video-js-swf)
* [Player skin designer](https://github.com/videojs/designer)
* [Contribflow](https://github.com/zencoder/contribflow)
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.
Filing issues
-------------
[GitHub Issues](https://github.com/videojs/video.js/issues) are used for all discussions around the codebase, including **bugs**, **features**, and other **enhancements**.
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
git clone https://github.com/<your-username>/video-js.git
# Navigate to the newly cloned directory
cd video-js
# Assigns the original repo to a remote called "upstream"
git remote add upstream https://github.com/zencoder/video-js.git
```
In the future, if you want to pull in updates to video.js that happened after you cloned the main repo, you can run:
```bash
git checkout master
git pull upstream master
```
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
```
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
```
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
```
To run the QUnit test suite, run:
```bash
grunt test
```
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
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
### Reporting a Bug
**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/videojs/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 already 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; **create a [reduced test case](http://css-tricks.com/6263-reduced-test-cases/)** with a live example. You can possibly use [this JSBin example](http://jsbin.com/axedog/7/edit) as a starting point.
A good bug report should be as detailed as possible, so that others won't have to follow up for the essential details.
@ -163,7 +36,7 @@ Here's an example:
> Short yet concise Bug Summary
>
> Description
> 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
@ -183,17 +56,189 @@ Here's an example:
> causing the bug, and potential solutions (and your opinions on their
> merits).
**[File a bug report](https://github.com/zencoder/video-js/issues/new)**
**[File a bug report](https://github.com/videojs/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 can do either of the following:
### Requesting a Feature
1. Do your development and testing using a local HTTP server.
1. [Check the plugin list](https://github.com/videojs/video.js/wiki/Plugins) for any plugins that may already support the feature.
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.
2. [Search the issues](https://github.com/videojs/video.js/issues) for any previous requests for the same feature, and give a thumbs up or +1 on existing requests.
# Code Style
2. If no previous requests exist, create a new issue. Please be as clear as possible about why the feautre is needed and the intended use case.
**[Request a feature](https://github.com/videojs/video.js/issues/new)**
Contributing code
-----------------
To contibute code you'll need to be able to build a copy of Video.js and run tests locally. There are a few requirements before getting started.
- Node.js -- 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 if that doesn't scare you. [Download and install Node.js](http://nodejs.org/download/)
- grunt-cli -- Install grunt-cli globally so that you will have the correct version of grunt available for any project that needs it.
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
```
- Contribflow -- A homegrown git workflow tool for managing feature/hotfix branches and submitting pull requests. If you have your own preferred git workflow, contribflow isn't required, but the following instructions will assume you're using it.
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
```
### Building your own copy of Video.js
First, [fork](http://help.github.com/fork-a-repo/) 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 own GitHub account.
Clone your fork of the repo into your code directory
```bash
git clone https://github.com/<your-username>/video.js.git
```
Navigate to the newly cloned directory
```bash
cd video.js
```
Assign the original repo to a remote called "upstream"
```
git remote add upstream https://github.com/videojs/video.js.git
```
>In the future, if you want to pull in updates to video.js that happened after you cloned the main repo, you can run:
>
> ```bash
> git checkout master
> git pull upstream master
> ```
Install the required node.js modules using node package manager
```bash
npm install
```
> 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.
> `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.
Build a local copy of video.js and run tests
```bash
grunt
grunt test
```
At this point you should have a built copy of video.js in a directory named `dist`, and all tests should be passing.
### Making Changes
Whether you're adding something new, making something better, or fixing a bug, you'll first want to search the [GitHub issues](https://github.com/videojs/video.js/issues) and [plugins list](https://github.com/videojs/video.js/wiki/Plugins) to make sure you're aware of any previous discussion or work. If an unclaimed issue exists, claim it via a comment. If no issue exists for your change, submit one, follwing the [issue filing guidelines](#filing-issues).
There are two categories of changes in video.js land, features and hotfixes (Video.js follows a branching model similar to [gitflow](http://nvie.com/posts/a-successful-git-branching-model/)). Hotfixes are for urgent fixes that need to be released immediately as a patch. Features are for everything else (including non-urgent fixes). If you think you have a hotfix scenario, verify that (via comment) before starting the work. We'll focus on features here, but you can swap `hotfix` for `feature` in any command.
Start a new development branch
```bash
contrib feature start
```
You'll 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! Be sure to read the [Code Style Guide](#code-style-guide).
While you're developing, you can ensure your changes are working by writing tests (in the `test` directory) and running `grunt test`.
There's also a sandbox directory where you can add any file and it won't get tracked as a change. To start you can copy the example index file and see a working version of a player (using the local source code) by loading it in a browser.
```bash
cp sandbox/index.html.example sandbox/index.html
open sandbox/index.html
```
> #### 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 can do either of the following:
>
> 1. Do your development and testing using a local HTTP server.
>
> 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.
Commit and push changes as you go (using git directly). Write thorough descriptions of your changes in your commit messages.
```bash
git add .
git commit -av
git push
```
> GitHub allows you to close an issue through your commit message using the [fixes](https://github.com/blog/831-issues-2-0-the-next-generation) keyword.
>
> ```bash
> My commit message. fixes #123
> Testing: (briefly describe any testing here, for example, 'unit tests and cross-browser manual tests around playback and network interruption')
> ```
### Submitting your changes
First, thoroughly test your feature or fix, including writing tests to make sure your change doesn't get regressed in a future update. 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.
Make sure your changes are pushed to origin
```bash
git push
```
Use contrib to submit a a pull request (make sure you're in your feature branch)
```bash
contrib feature 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.
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.
Code Style Guide
----------------
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.
### Style examples include:
@ -206,11 +251,6 @@ Please follow [Google's JavaScript Style Guide](http://google-styleguide.googlec
If you happen to find something in the codebase that does not follow the style guide, that's a good opportunity to make your first contribution!
# Other Video.js Pojects
* [Video.js SWF](https://github.com/zencoder/video-js-swf) - The light-weight flash video player that makes flash work like HTML5 video. This allows player skins, plugins, and other features to work with both HTML5 and Flash.
* [Videojs.com](http://videojs.com) - The public site with helpful tools and information about Video.js.
---
### Doc Credit
This doc was inspired by some great contribution guide examples including [contribute.md template](https://github.com/contribute-md/contribute-md-template),

48
README.md
View File

@ -1,50 +1,18 @@
# [Video.js - HTML5 and Flash Video Player](http://videojs.com) [![Build Status](https://travis-ci.org/zencoder/video-js.png?branch=master)](https://travis-ci.org/zencoder/video-js)
# [Video.js - HTML5 Video Player](http://videojs.com) [![Build Status](https://travis-ci.org/zencoder/video-js.png?branch=master)](https://travis-ci.org/zencoder/video-js)
Visit the main site at [videojs.com](http://videojs.com) for download options and instructions.
Video.js is a web video player built from the ground up for an HTML5 world. It supports HTML5 and Flash video, as well as YouTube and Vimeo (through [plugins](https://github.com/videojs/video.js/wiki/Plugins)). It supports video playback on desktops and mobile devices. This project was started mid 2010, and the player is now used on over 50,000 websites.
### PLEASE EXCUSE OUR DUST
We're finishing up a big overhaul of the libary which includes
* Closure compiler advanced mode support for drastically better minification over previous versions
* Flashy new automated builds and test using node.js and grunt
Check out our [contributing guide](https://github.com/zencoder/video-js/blob/master/CONTRIBUTING.md) for info on building a local version.
## About
Video.js was built to provide a fast and easy way to embed and work with video in a web page.
It was built from the ground up with the assumption that HTML5 is the future of web video, however it supports Flash equally well for older browsers and for advanced features not yet supported in HTML5.
Some of the focuses of Video.js are:
- Universal browser and device support
- Fast player loading
- Easily skinned (themed/chromed) using just CSS
- A JavaScript API for controlling the video that works consistently across video platforms (HTML5, Flash, and soon other players like youtube) as well as devices
## Getting Started
Check out our [getting started guide](http://videojs.com/#section5).
Visit [videojs.com](http://videojs.com) for an overview, download options, and instructions on how to use the player on your site.
## Contributing
Video.js is a free and open source library, and we appreciate any help you're willing to give. Check out the [contributing guide](CONTRIBUTING.md).
Check out our [contributing guide](https://github.com/zencoder/video-js/blob/master/CONTRIBUTING.md).
## Building your own Video.js from source
To build your own custom version read the section on [contributing code](CONTRIBUTING.md#contributing-code) and ["Building your own copy"](CONTRIBUTING.md#building-your-own-copy-of-videojs) in the contributing guide.
## License
Video.js is licensed under the Apache License, Version 2.0. [View the license file](LICENSE)
Copyright 2013 Brightcove, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

5
VERSION.yml
View File

@ -1,5 +0,0 @@
---
major: 3
minor: 2
patch: 3
pre:

4
docs/setup.md
View File

@ -12,8 +12,8 @@ You can download the Video.js source and host it on your own servers, or use the
### CDN Version ###
```html
<link href="http://vjs.zencdn.net/4.0/video-js.css" rel="stylesheet">
<script src="http://vjs.zencdn.net/4.0/video.js"></script>
<link href="http://vjs.zencdn.net/4.1/video-js.css" rel="stylesheet">
<script src="http://vjs.zencdn.net/4.1/video.js"></script>
```
### Self Hosted. ###