web/video.js
1
0
Fork 0
mirror of https://github.com/videojs/video.js.git synced 2024-12-21 01:39:04 +02:00
Code Releases Activity

docs: Refresh README.md and point other docs to admin repo (#8837)

Browse Source 
Co-authored-by: mister-ben <1676039+mister-ben@users.noreply.github.com>
This commit is contained in:
Pat O'Neill 2024-08-23 13:50:20 -04:00 committed by GitHub
parent 73db132d86
commit f0db8f103c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 31 additions and 956 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
CODE_OF_CONDUCT.md
View File

@ -1,128 +1,3 @@
# Contributor Covenant Code of Conduct
# Video.js® Code of Conduct
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
## Table of Contents
* [Our Pledge](#our-pledge)
* [Our Standards](#our-standards)
* [Our Responsibilities](#our-responsibilities)
* [Scope](#scope)
* [Other Community Standards](#other-community-standards)
* [Enforcement](#enforcement)
* [Further Enforcement](#further-enforcement)
* [Who Watches the Watchers?](#who-watches-the-watchers)
* [Attribution](#attribution)
## Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
### Other Community Standards
As a project on GitHub, this project is additionally covered by the [GitHub Community Guidelines](https://help.github.com/articles/github-community-guidelines/).
Additionally, as a project hosted on npm, is is covered by [npm, Inc's Code of Conduct](https://www.npmjs.com/policies/conduct).
Enforcement of those guidelines after violations overlapping with the above are the responsibility of the entities, and enforcement may happen in any or all of the services/communities.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at gary@videojs.com or @gkatsev on [slack][]. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
### Further Enforcement
If you've already followed the [initial enforcement steps](#enforcement), these are the steps maintainers will take for further enforcement, as needed:
1. Repeat the request to stop.
1. If the person doubles down, they will have offending messages removed or edited by a maintainers given an official warning. The PR or Issue may be locked.
1. If the behavior continues or is repeated later, the person will be blocked from participating for 24 hours.
1. If the behavior continues or is repeated after the temporary block, a long-term (6-12mo) ban will be used.
On top of this, maintainers may remove any offending messages, images, contributions, etc, as they deem necessary.
Maintainers reserve full rights to skip any of these steps, at their discretion, if the violation is considered to be a serious and/or immediate threat to the health and well-being of members of the community. These include any threats, serious physical or verbal attacks, and other such behavior that would be completely unacceptable in any social setting that puts our members at risk.
Members expelled from events or venues with any sort of paid attendance will not be refunded.
### Who Watches the Watchers?
Maintainers and other leaders who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. These may include anything from removal from the maintainer team to a permanent ban from the community.
Additionally, as a project hosted on both GitHub and npm, [their own Codes of Conducts may be applied against maintainers of this project](#other-community-standards), externally of this project's procedures.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at [http://contributor-covenant.org/version/1/4][version]
The [Other Community Standards](#other-community-standards), [Further Enforcement](#further-enforcement),
and [Who Watches the Watchers?](#who-watches-the-watchers) sections are based on [weallbehave][weallbehave],
which is based on the [WeAllJS Code of Conduct][wealljs].
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/
[wealljs]: https://wealljs.org/code-of-conduct
[weallbehave]: https://npm.im/weallbehave
[slack]: http://slack.videojs.com
Please refer to: <https://github.com/videojs/admin/blob/main/CODE_OF_CONDUCT.md>

462
COLLABORATOR_GUIDE.md
View File

@ -1,461 +1,3 @@
# Collaborator Guide
# Video.js® Collaborator Guide
## Table of Contents
* [Issues and Pull Requests](#issues-and-pull-requests)
* [Labels](#labels)
* [Accepting changes](#accepting-changes)
* [Involving the TSC](#involving-the-tsc)
* [Landing a PR](#landing-a-pr)
* [Landing a PR manually](#landing-a-pr-manually)
* [Landing a PR manually with several changes](#landing-a-pr-manually-with-several-changes)
* [I just made a mistake](#i-just-made-a-mistake)
* [I accidentally pushed a broken commit or incorrect commit to main](#i-accidentally-pushed-a-broken-commit-or-incorrect-commit-to-main)
* [I lost changes](#i-lost-changes)
* [I accidentally committed a broken change to main](#i-accidentally-committed-a-broken-change-to-main)
* [Video.js releases](#videojs-releases)
* [Getting dependencies](#getting-dependencies)
* [npm access](#npm-access)
* [Deciding what type of version release](#deciding-what-type-of-version-release)
* [Doing a release](#doing-a-release)
* [Current Video.js](#current-videojs)
* [Legacy Video.js (5)](#legacy-videojs-5)
* [Edit git-semver-tags](#edit-git-semver-tags)
* [And now for the release](#and-now-for-the-release)
* [Deploy as a patch to the CDN](#deploy-as-a-patch-to-the-cdn)
* [Announcement](#announcement)
* [Doc credit](#doc-credit)
## Issues and Pull Requests
Full courtesy should always be shown in Video.js projects.
Collaborators may manage issues they feel qualified to handle, being mindful of our guidelines.
Any issue and PR can be closed if they are not relevant, when in doubt leave it open for more discussion. Issues can always be re-opened if new information is made available.
If issues or PRs are very short and don't contain much information, ask for more by linking to the [issue][issue template] or [PR][pr template] template. There is also a [response guide](https://github.com/videojs/video.js/wiki/New-Issue-Response-Guide) if you're unsure.
### Labels
There are labels that are useful to include on issues and PRs. A few of them are defined below:
| Label | Issue or PR | Description |
| ------------------------ | ------------ | -------------------------------------------------------------------------- |
| confirmed | Issue and PR | Issue: marks as reproducible. PR: marks as ready to be merged |
| 5.x | PR | Marks as a change to the 5.x branch only |
| bug | Issue | Marks as a confirmed bug |
| good first issue | Issue | Marks as a good bug or enhancement for first time contributors to Video.js |
| first-timers-only | Issue | Marks as a good bug or enhancement to be done by a newcomer to open source |
| minor, patch, major | PR | Marks PR with the expected semver classification of the change |
| needs: LGTM | PR | Marks PR to be reviewed by a collaborator |
| needs: more info | Issue | Marks as needing more information from the issue reporter |
| needs: reduced test case | Issue | Marks as needing a reduced test case from the issue reporter |
## Accepting changes
Any code change in Video.js should be happening through Pull Requests on GitHub. This includes core committers.
Before a PR is merged, it must be reviewed by at least two core committers, at least one if it comes from a core committer.
Feel free to @-mention a particular core committer if you know they are experts in the area that is being changed.
If you are unsure about the modification and cannot take responsibility for it, defer to another core committer.
Before merging the change, it should be left open for other core committers to comment on. At least 24 hours during a weekday, and the 48 hours on a weekend. Trivial changes or bug fixes that have been reviewed by multiple committers may be merged without delay.
For non-breaking changes, if there is no disagreement between the collaborators, the PR may be landed assuming it was reviewed. If there is still disagreement, it may need to be [escalated to the TSC](#involving-the-tsc).
Bug fixes require a test case that fails beforehand and succeeds after. All code changes should contain tests and pass on the CI.
### Involving the TSC
A change or issue can be elevated to the TSC by assigning the `tsc-agent` label. This should be done in the following scenarios:
* There will be a major impact on the codebase or project
* The change is inherently controversial
* No agreement was reached between collaborators participating in the discussion
The TSC will be the final arbiter when required.
## Landing a PR
Landing a PR is fairly easy given that we can use the GitHub UI for it.
When using the big green button on GitHub, make sure the "squash and merge" is selected -- it should be the only allowed option. If a PR has two features in it and should be merged as two separate commits, either ask the contributor to break it up into two, or follow the [manual steps](#landing-a-pr-manually).
The commit message should follow our [conventional changelog conventions][conventions]. They are based on the angularjs changelog conventions. The changelog is then generated from these commit messages on release.
The first line of the commit message -- the header, which is the first text box on GitHub -- should be prefixed with a type and optional scope followed by a short description of the commit.
The type is required. Two common ones are `fix` and `feat` for bug fixes and new features. Scope is optional and can be anything.
The body should contain extra information, potentially copied from the original comment of the PR.
The footer should contain things like whether this is a breaking change or what issues were fixed by this PR.
Here's an example:
```commit
fix(html5): a regression with html5 tech
This is where you'd explain what the regression is.
Fixes #123
```
### Landing a PR manually
_Optional:_ ensure you're not in a weird rebase or merge state:
```sh
git am --abort
git rebase --abort
```
Checkout and update the main branch:
```sh
git checkout main
git remote update
git rebase upstream/main
```
Check out the PR:
```sh
git fetch upstream pull/{{PR Number}}/head:{{name of branch}}
git checkout -t {{name of branch}}
```
> For example:
>
> ```sh
> git fetch upstream pull/123/head:gkatsev-html5-fix
> git checkout -t gkatsev-html5-fix
> ```
_Optional:_ If necessary, rebase against main. If you have multiple features in the PR, [landing a PR manually with several changes](#landing-a-pr-manually-with-several-changes)
```sh
git rebase main
```
Fix up any issues that arise from the rebase, change back to the main branch and squash merge:
```sh
git checkout main
git merge --squash --no-commit gkatsev-html5-fix
```
The `--no-commit` tells git not to make a commit on your behalf. It does stage everything for you, so, you can instead it:
```sh
git diff --cached
```
Now get the author from the original commit:
```sh
git log -n 1 --pretty=short gkatsev-html5-fix
```
Which shows:
```txt
commit 433c58224f5be34480c8e067ca6c5406ba1c1e9c
Author: Gary Katsevman <git@gkatsev.com>
Update TOC
```
Now you can commit the change the change with the author, following our commit guidelines
```sh
git commit --author "Gary Katsevman <git@gkatsev.com>"
```
Now that it's committed, push to main
```sh
git push upstream main
```
Congratulate yourself for a job well done and the contributor for having his change landed in main.
#### Landing a PR manually with several changes
Follow the same steps as before but when you rebase against main, you want to do an interactive rebase and then squash the changes into just a few commits.
```sh
git rebase -i main
```
This will give you an output like the following:
```txt
pick b4dc15d Update CONTRIBUTING.md with latest info
pick 8592149 Add Dev certificate of origin
pick 259dee6 Add grunt and doctoc npm scripts
pick f12af12 Add conventional-changelog-videojs link
pick ae4613a Update node's CONTRIBUTING.md url
pick 433c582 Update TOC
# Rebase f599ef4..433c582 onto f599ef4 (6 command(s))
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
Replace `pick` to `fixup` or `edit` depending on how you want the output to look. You can also re-order the commits, if necessary.
> `fixup` will squash the commit it's infront of up into the commit above it
>
> `edit` will allow you to edit the commit message before continuing
```txt
edit b4dc15d Update CONTRIBUTING.md with latest info
fixup 8592149 Add Dev certificate of origin
fixup f12af12 Add conventional-changelog-videojs link
fixup ae4613a Update node's CONTRIBUTING.md url
fixup 433c582 Update TOC
edit 259dee6 Add grunt and doctoc npm scripts
```
When you get to the edit commits, git will give more information, but you'd want to run amend the current commit while following our commit guidelines
```sh
git commit --amend
```
After going through and making the commits you want, you want to change back to main and then rebase the branch onto main so we get a clean history
```sh
git rebase gkatsev-html5-fix
```
This will put our two commits into main:
```txt
b4dc15d chore(contributing.md): Update CONTRIBUTING.md with latest info <Gary Katsevman>
259dee6 chore(package.json): Add grunt and doctoc npm scripts <Gary Katsevman>
9e20386 v5.12.6 <Gary Katsevman>
```
Now you're ready to push to main as in the normal instructions.
#### I just made a mistake
While `git` allows you to update the remote branch with a force push (`git push -f`). This is generally frowned upon since you're rewriting public history. However, if you just pushed the change and it's been less than 10 minutes since you've done with, you may force push to update the commit, assuming no one else has already pushed after you.
##### I accidentally pushed a broken commit or incorrect commit to main
Assuming no more than 10 minutes have passed, you may force-push to update or remove the commit. If someone else has already pushed to main or 10 minutes have passed, you should instead use the revert command (`git revert`) to revert the commit and then commit the proper change, or just fix it forward with a followup commit that fixes things.
##### I lost changes
Assuming that the changes were committed, even if you lost the commit in your current history does not mean that it is lost. In a lot of cases you can still recover it from the PR branch or if all else fails look at [git's reflog](https://git-scm.com/docs/git-reflog).
##### I accidentally committed a broken change to main
This is a great time to discover that something is broken. Because it hasn't been pushed to GitHub yet, it's very easy to reset the change as if nothing has happened and try again.
To do so, just reset the branch against main.
```sh
git reset --hard upstream/main
```
## Video.js releases
Releasing Video.js is partially automated through various scripts.
To do a release, all you need is just write access to the repo!
Releases in Video.js are done on npm and GitHub and eventually posted on the CDN.
These are the instructions for the npm/GitHub releases.
When we do a release, we release it as a `next` tag on npm first and then at least a week later, we promote this release to `latest` on npm.
You can promote it using `npm dist-tag add video.js@<version> <tag>`.
### Getting dependencies
#### npm access
To see who currently has access run this:
```sh
npm owner ls video.js
```
If you are a core committer, you can request access to npm from one of the current owners.
Access is managed via an [npm organization][npm org] for [Video.js][vjs npm].
### Deciding what type of version release
Since we follow the [conventional changelog conventions][conventions],
all commits are prepended with a type, most commonly `feat` and `fix`.
If all the commits are fix or other types such as `test` or `chore`, then the release will be a `patch` release.
If there's even one `feat`, the release will be a `minor` release.
If any commit has a `BREAKING CHANGE` footer, then the release will be a `major` release.
Most common releases will be either `patch` or `minor`.
### Doing a release
It is also recommended you have a clean clone of Video.js for each release line you want to release.
This is because different versions have different expectations for release process and have different dependencies.
Plus, during development you could end up with a dirty repo, so, it just usually easier if you have a clean release repo.
```sh
# for v8
git clone git@github.com:videojs/video.js.git videojs-8-release
# for v7
git clone git@github.com:videojs/video.js.git videojs-7-release
```
#### Current Video.js
Make sure go to the main branch and grab the latest updates.
```sh
git checkout main
git pull origin main
```
At this point, you should run `npm install` because dependencies may have changed.
Then, it's mostly a standard npm package release process with running `npm version`, followed by an `npm publish`.
```sh
npm version {major|minor|patch}
```
Depending on the commits that have been merged, you can choose from `major`, `minor`, or `patch` as the versioning values.
See [deciding what type of version release section](#deciding-what-type-of-version-release).
Optionally, you can run `git show` now to verify that the version update and CHANGELOG automation worked as expected.
Afterwards, you want to push the commit and the tag to the repo.
It's necessary to do this before running `npm publish` because our GitHub release automation
relies on the commit being available on GitHub.
```sh
git push --tags origin main
```
After the tag was pushed, GitHub actions will trigger the `release` workflow, which will do the following:
* Publish to npm with `next` or `next-{n}` depending on your current major version.
* Create GitHub pre-release with changelog and Netlify preview.
* Create a GitHub `releases` discussion linked to the GitHub release.
* Copy files to the CDN with the AWS CLI (this step requires approval, make sure to ping collaborators chat!)
And that's it. Congratulations - you've just released a new version of Video.js.
#### Legacy Video.js (5)
Make sure to go to the 5.x branch and grab the latest updates.
```sh
git checkout 5.x
git pull origin 5.x
```
> _Note:_ you probably need to delete v6 tags due to the way that the our CHANGELOG lib works.
>
> You can run this to delete them:
>
> ```sh
> git tag | grep '^v6' | xargs git tag -d
> ```
>
> This will find all tags that start with `^v6` and delete them.
At this point, you should run `npm install` because dependencies may have changed.
Then, we have a script that automates most of the steps for publishing. It's a little trickier than publishing v6.
##### Edit git-semver-tags
You'll need to edit `git-semver-tags` to support our usage of tags that are not part of the branch.
In the file `node_modules/conventional-changelog-cli/node_modules/conventional-changelog/node_modules/conventional-changelog-core/node_modules/git-semver-tags/index.js`, edit the line that says sets the `cmd` to be:
```js
var cmd = 'git log --all --date-order --decorate --no-color';
```
#### And now for the release
After getting rid of the tags and getting the latest updates, you can just run the release script:
```sh
VJS_GITHUB_USER=gkatsev VJS_GITHUB_TOKEN=123 ./build/bin/release-next.sh
```
It will prompt you for a version change type, so, input `patch` or `minor` or `major`.
See [deciding what type of version release section](#deciding-what-type-of-version-release).
When it's done building everything, it'll show you the commit that's made via the default pager (i.e., less).
At this point you can verify that things look normal rather than, for example, missing all the CSS.
After exiting the pager, it'll make sure you want to continue with publishing.
It will automatically release it as a `next-5` tag on npm.
Then push the local changes up:
```sh
git push --tags origin 5.x
```
Also, you'll need to copy the CHANGELOG for this version and manually edit the GitHub release to include it.
The current release's CHANGELOG could be copied from the [raw CHANGELOG.md file][raw chg] (or locally from the markdown file)
and then pasted into the correct [GitHub release](https://github.com/videojs/video.js/releases).
### Deploy as a patch to the CDN
Follow the steps on the [CDN repo][cdn repo] for the CDN release process.
If it's a `next` or `next-5` release, only publish the patch version to the CDN.
When the version gets promoted to `latest` or `latest-5`, the corresponding `minor` or `latest` version should be published to the CDN.
### Announcement
An announcement should automatically make it's way to #announcements channel on [slack][], it uses IFTTT and might take a while.
You can also post it to twitter or ask someone (like @gkatsev) to post on your behalf.
If it's a large enough release, consider writing a blog post as well.
## Doc credit
This collaborator guide was heavily inspired by [node.js's guide](https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md)
[issue template]: /.github/ISSUE_TEMPLATE.md
[pr template]: /.github/PULL_REQUEST_TEMPLATE.md
[conventions]: https://github.com/videojs/conventional-changelog-videojs/blob/main/convention.md
[vjs npm]: https://www.npmjs.com/org/videojs
[npm org]: https://docs.npmjs.com/misc/orgs
[slack]: http://slack.videojs.com
[cdn repo]: https://github.com/videojs/cdn
[raw chg]: https://raw.githubusercontent.com/videojs/video.js/5.x/CHANGELOG.md
Please refer to: <https://github.com/videojs/admin/blob/main/COLLABORATOR_GUIDE.md>

328
CONTRIBUTING.md
View File

@ -1,327 +1,3 @@
# CONTRIBUTING
# Video.js® Contributor Guide
So you want to help out? Great! There's a number of ways you can get involved.
## Table of Contents
* [Other repositories where issues could be filed](#other-repositories-where-issues-could-be-filed)
* [Filing issues](#filing-issues)
* [Reporting a Bug](#reporting-a-bug)
* [Requesting a Feature](#requesting-a-feature)
* [Labels](#labels)
* [Contributing code](#contributing-code)
* [Building video.js locally](#building-videojs-locally)
* [Forking and cloning the repository](#forking-and-cloning-the-repository)
* [Installing local dependencies](#installing-local-dependencies)
* [Running tests](#running-tests)
* [Building videojs](#building-videojs)
* [Testing Locally](#testing-locally)
* [Sandbox test directory](#sandbox-test-directory)
* [Running a local web server](#running-a-local-web-server)
* [Watching source and test changes](#watching-source-and-test-changes)
* [Making Changes](#making-changes)
* [Step 1: Verify](#step-1-verify)
* [Step 2: Update remote](#step-2-update-remote)
* [Step 3: Branch](#step-3-branch)
* [Step 4: Commit](#step-4-commit)
* [Step 5: Test](#step-5-test)
* [Step 6: Push](#step-6-push)
* [Code Style Guide](#code-style-guide)
* [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11)
* [Doc Credit](#doc-credit)
## Other repositories where issues could be filed
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)
* [Videojs.com](https://github.com/videojs/videojs.com)
* [HLS](https://github.com/videojs/videojs-contrib-hls)
* [DASH](https://github.com/videojs/videojs-contrib-dash)
* [Youtube Tech](https://github.com/videojs/videojs-youtube)
* [Vimeo Tech](https://github.com/videojs/videojs-vimeo)
* [Ads](https://github.com/videojs/videojs-contrib-ads)
* [Plugin generator](https://github.com/videojs/generator-videojs-plugin)
* [Linter][linter]
## 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**.
When filling out an issue, please respond to all of the questions in the template, including as much information as possible.
### 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. If your issue is with a particular video.js plugin or subproject, please open an issue against that project. See [list of some potential other projects above](#other-repositories-where-issues-could-be-filed)
1. Use the [GitHub issue search](https://github.com/videojs/video.js/issues) — check if the issue has already been reported.
1. Check if the issue has already been fixed — try to reproduce it using the latest `main` branch in the repository.
1. Isolate the problem — **create a [reduced test case](https://css-tricks.com/reduced-test-cases/)** with a live example. You can possibly use [this codepen template](https://codepen.io/gkatsev/pen/GwZegv?editors=1000#0) as a starting point -- don't forget to update it to the videojs version you use.
1. Answer all questions in the [issue template][]. The questions in the issue template are designed to try and provide the maintainers with as much information possible to minimize back-and-forth to get the issue resolved.
A good bug report should be as detailed as possible, so that others won't have to follow up for the essential details.
**[File a bug report](https://github.com/videojs/video.js/issues/new)**
### Requesting a Feature
1. [Check the plugin list](https://videojs.com/plugins/) for any plugins that may already support the feature.
1. [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.
1. If no previous requests exist, create a new issue. Please be as clear as possible about why the feature is needed and the intended use case.
1. Once again, be as details as possible and follow the [issue template][]
**[Request a feature](https://github.com/videojs/video.js/issues/new)**
### Labels
There are a few labels that might be added to your issue or PR by a maintainer. Here's a quick rundown of what they mean:
| Label | Issue or PR | Description |
| ------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| confirmed | Issue and PR | Issue: marks as reproducible by a maintainer. PR: marked by a maintainer as ready to be merged |
| 5.x | PR | Marks as a change to the 5.x branch only |
| bug | Issue | Marks as a confirmed bug by a maintainer |
| good first issue | Issue | Marked as a good bug or enhancement for first time contributors to Video.js |
| first-timers-only | Issue | Marked as a good bug or enhancement to be done by a newcomer to open source |
| minor, patch, major | PR | Marks PR with the expected [semver](https://semver.org/) classification of the change |
| needs: more info | Issue | Marked by a maintainer as needing more information from the issue reporter. Please update your issue with more information to help us reproduce the bug. |
| needs: reduced test case | Issue | Marked by a maintainer as needing a reduced test case from the issue reporter. Please create a test page that we can inspect to help us identify a bug. |
## Contributing code
To contribute 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/)
### Building video.js locally
#### Forking and cloning the repository
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
```sh
git clone https://github.com/<your-username>/video.js.git
```
Navigate to the newly cloned directory
```sh
cd video.js
```
Assign the original repo to a remote called "upstream"
```sh
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:
>
> ```sh
> git remote update
> git checkout main
> git pull upstream main
> ```
#### Installing local dependencies
Install the required node.js modules using node package manager
```sh
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.
#### Running tests
Tests can be run either from the shell or from the browser.
To run the tests from the shell, just run
```sh
npm test
```
This will build video.js locally and run the test suite using [Karma](https://karma-runner.github.io/1.0/index.html), which runs our tests in actual browsers.
To run tests from the browser, first start a local server with `npm start` (this also watches for changes and rebuilds video.js and the test files as necessary). Then navigate to `http://localhost:9999/test`, and you'll see a page that displays the results of all the tests. To rerun the tests after making changes, just refresh the page. To run an individual test, click the "Rerun" link next to the test's title.
#### Building videojs
To build video.js, simply run
```sh
npm run build
```
This outputs an `es5/` and `dist/` folder. The `es5/` folder is used by bundling tools like browserify and webpack to package video.js into projects. The `dist/` folder has pre-compiled versions of video.js, including a minified version and the CSS file. This file can be included in page via a `<script></script>` tag.
#### Testing Locally
Besides running automated tests, you often want to run video.js manually and play around with things as you're developing. A few things are provided to make it easier.
#### Sandbox test directory
There's a sandbox directory where you can add any file and it won't get tracked in git. To start you can copy the example index file.
```sh
cp sandbox/index.html.example sandbox/index.html
```
See [the following section](#running-a-local-web-server) for how to open the page in a browser.
#### Running a local web server
This ties in nicely with the sandbox directory. You can always open the `sandbox/index.html` file directly but in some cases it may not work properly.
> To get around this you must use a local web server.
To run the local webserver:
```sh
npm start
open http://localhost:9999/sandbox/index.html
```
The latter does some extra work which will be described in the next section.
#### Watching source and test changes
As you're developing, you want the build to re-run and update itself, and potentially re-run the tests. In addition, you want to launch a local web-server that you can open the `sandbox` directory in.
To do so, you just need to run
```sh
npm start
```
This sets up the local webserver using connect and then watches source files, test files, and CSS files for you and rebuilds things as they happen.
### Making Changes
#### Step 1: Verify
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, following the [issue filing guidelines](#filing-issues).
#### Step 2: Update remote
Before starting work, you want to update your local repository to have all the latest changes.
```sh
git remote update
git checkout main
git rebase upstream/main
```
#### Step 3: Branch
You want to do your work in a separate branch.
```sh
git checkout -b my-branch
```
#### Step 4: Commit
Commit changes as you go. Write thorough descriptions of your changes in your commit messages.
For more information see our [conventional changelog guidelines for video.js](https://github.com/videojs/conventional-changelog-videojs/blob/main/convention.md)
Follow these guidelines:
1. The first line should be less than 50 characters and contain a short description of the commit.
1. The body should contain a more detailed description. It can contain things like reasoning for the change and specifics of what changed.
1. A footer can be added if this fixes a particular issue on GitHub.
```sh
git add src/js/player.js
git commit
```
An example of the first line of a commit message: `fix: changed the footer to correctly display foo`
In the body of the commit message, we can talk about why we made the change. What the change entails.
Any testing considerations or things to think about when looking at the commit. For Example:
```txt
fix: one line commit explanation
In the body of the commit message, we can talk about why we made the change. What the change entails.
Any testing considerations or things to think about when looking at the commit.
Fixes #123. The footer can contain Fixes messages.
```
> Make sure that git knows your name and email:
>
> ```sh
> git config --global user.name "Random User"
> git config --global user.email "random.user@example.com"
> ```
#### Step 5: Test
Any code change should come with corresponding test changes. Especially bug fixes.
Tests attached to bug fixes should fail before the change and succeed with it.
```sh
npm test
```
See [Running tests](#running-tests) for more information.
#### Step 6: Push
```sh
git push origin my-branch
```
Then go to the [repo page](https://github.com/videojs/video.js) and click the "Pull Request" button and fill out the [pull request template](/.github/PULL_REQUEST_TEMPLATE.md)
### Code Style Guide
Our javascript is linted using [videojs-standard][linter].
## [Developer's Certificate of Origin 1.1](https://github.com/nodejs/node/blob/main/CONTRIBUTING.md#developers-certificate-of-origin-11)
By making a contribution to this project, I certify that:
* (a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
* (b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
* (c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
* (d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
## Doc Credit
This doc was inspired by some great contribution guide examples including [contribute.md template](https://github.com/contribute-md/contribute-md-template),
[grunt](https://github.com/gruntjs/grunt/wiki/Contributing),
[html5 boilerplate](https://github.com/h5bp/html5-boilerplate/blob/master/CONTRIBUTING.md),
[jquery](https://github.com/jquery/jquery/blob/master/CONTRIBUTING.md),
and [node.js](https://github.com/nodejs/node/blob/master/CONTRIBUTING.md).
[issue template]: /.github/ISSUE_TEMPLATE.md
[linter]: https://github.com/videojs/standard
Please refer to: <https://github.com/videojs/admin/blob/main/CONTRIBUTING.md>

68
README.md
View File

@ -1,15 +1,14 @@
![Video.js logo][logo]
[![Video.js logo][logo]][vjs]
# [Video.js - HTML5 Video Player][vjs]
[![Build Status][travis-icon]][travis-link]
[![Coverage Status][coveralls-icon]][coveralls-link]
[![Greenkeeper badge](https://badges.greenkeeper.io/videojs/video.js.svg)](https://greenkeeper.io/)
[![Slack Status][slack-icon]][slack-link]
# Video.js® - Web Video Player
[![NPM][npm-icon]][npm-link]
> Video.js is a web video player built from the ground up for an HTML5 world. It supports HTML5 video and Media Source Extensions, as well as other playback techs like YouTube and Vimeo (through [plugins][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~~ ~~100,000~~ ~~200,000~~ ~~400,000~~ [700,000 websites][builtwith].
Video.js is a full featured, open source video player for all web-based platforms.
Right out of the box, Video.js supports all common media formats used on the web including streaming formats like HLS and DASH. It works on desktops, mobile devices, tablets, and web-based Smart TVs. It can be further extended and customized by a robust ecosystem of [plugins][plugins].
Video.js was started in the middle of 2010 and is now used on over ~~50,000~~ ~~100,000~~ ~~200,000~~ ~~400,000~~ ~~700,000~~ [800,000 websites][builtwith].
## Table of Contents
@ -18,26 +17,16 @@
* [Code of Conduct](#code-of-conduct)
* [License](#license)
## Quick Start
## [Quick Start][getting-started]
Thanks to the awesome folks over at [Fastly][fastly], there's a free, CDN hosted version of Video.js that anyone can use. Add these tags to your document's `<head>`:
```html
<link href="//vjs.zencdn.net/8.3.0/video-js.min.css" rel="stylesheet">
<script src="//vjs.zencdn.net/8.3.0/video.min.js"></script>
<link href="//vjs.zencdn.net/8.17.3/video-js.min.css" rel="stylesheet">
<script src="//vjs.zencdn.net/8.17.3/video.min.js"></script>
```
> For the latest version of video.js and URLs to use, check out the [Getting Started][getting-started] page on our website.
Video.js version 7 (and newer) CDN builds do not send any data to Google Analytics.
In older versions of Video.js (6 and earlier), in the `vjs.zencdn.net` CDN-hosted versions we include a [stripped down Google Analytics pixel](https://github.com/videojs/cdn/blob/master/src/analytics.js) that tracks a random sampling (currently 1%) of players loaded from the CDN. This allows us to see (roughly) what browsers are in use in the wild, along with other useful metrics such as OS and device. If you'd like to disable analytics, you can simply include the following global before including Video.js via the free CDN:
```html
<script>window.HELP_IMPROVE_VIDEOJS = false;</script>
```
Alternatively, you can include Video.js by getting it from [npm](https://videojs.com/getting-started/#install-via-npm), downloading from [GitHub releases](https://github.com/videojs/video.js/releases) or by including it via [unpkg](https://unpkg.com) or another JavaScript CDN like CDNjs. These releases _do not_ include Google Analytics tracking at all.
Alternatively, you can include Video.js by getting it from [npm](https://videojs.com/getting-started/#install-via-npm), downloading it from [GitHub releases](https://github.com/videojs/video.js/releases) or by including it via [unpkg](https://unpkg.com) or another JavaScript CDN, like CDNjs.
```html
<!-- unpkg : use the latest version of Video.js -->
@ -45,12 +34,12 @@ Alternatively, you can include Video.js by getting it from [npm](https://videojs
<script src="https://unpkg.com/video.js/dist/video.min.js"></script>
<!-- unpkg : use a specific version of Video.js (change the version numbers as necessary) -->
<link href="https://unpkg.com/video.js@8.3.0/dist/video-js.min.css" rel="stylesheet">
<script src="https://unpkg.com/video.js@8.3.0/dist/video.min.js"></script>
<link href="https://unpkg.com/video.js@8.17.3/dist/video-js.min.css" rel="stylesheet">
<script src="https://unpkg.com/video.js@8.17.3/dist/video.min.js"></script>
<!-- cdnjs : use a specific version of Video.js (change the version numbers as necessary) -->
<link href="https://cdnjs.cloudflare.com/ajax/libs/video.js/8.3.0/video-js.min.css" rel="stylesheet">
<script src="https://cdnjs.cloudflare.com/ajax/libs/video.js/8.3.0/video.min.js"></script>
<link href="https://cdnjs.cloudflare.com/ajax/libs/video.js/8.17.3/video-js.min.css" rel="stylesheet">
<script src="https://cdnjs.cloudflare.com/ajax/libs/video.js/8.17.3/video.min.js"></script>
```
Next, using Video.js is as simple as creating a `<video>` element, but with an additional `data-setup` attribute. At a minimum, this attribute must have a value of `'{}'`, but it can include any Video.js [options][options] - just make sure it contains valid JSON!
@ -84,8 +73,7 @@ If you don't want to use automatic setup, you can leave off the `data-setup` att
var player = videojs('my-player');
```
The `videojs` function also accepts an `options` object and a callback to be invoked
when the player is ready:
The `videojs` function also accepts an `options` object and a callback to be invoked when the player is ready:
```js
var options = {};
@ -103,9 +91,9 @@ var player = videojs('my-player', options, function onPlayerReady() {
});
```
If you're ready to dive in, the [Getting Started][getting-started] page and [documentation][docs] are the best places to go for more information. If you get stuck, head over to our [Slack channel][slack-link]!
If you're ready to dive in, the [Getting Started][getting-started] page and [documentation][docs] are the best places to go for more information. If you get stuck, head over to our [Slack][slack-link]!
## Contributing
## [Contributing][contributing]
Video.js is a free and open source library, and we appreciate any help you're willing to give - whether it's fixing bugs, improving documentation, or suggesting new features. Check out the [contributing guide][contributing] for more!
@ -119,15 +107,15 @@ Please note that this project is released with a [Contributor Code of Conduct][c
Video.js is [licensed][license] under the Apache License, Version 2.0.
Video.js is a registered trademark of [Brightcove, Inc][bc].
[bc]: https://www.brightcove.com/
[browserstack]: https://browserstack.com
[builtwith]: https://trends.builtwith.com/media/VideoJS
[contributing]: CONTRIBUTING.md
[coveralls-icon]: https://coveralls.io/repos/github/videojs/video.js/badge.svg?branch=main
[coveralls-link]: https://coveralls.io/github/videojs/video.js?branch=main
[contributing]: https://github.com/videojs/admin/blob/main/CONTRIBUTING.md
[docs]: https://docs.videojs.com
@ -147,14 +135,8 @@ Video.js is [licensed][license] under the Apache License, Version 2.0.
[plugins]: https://videojs.com/plugins/
[slack-icon]: http://slack.videojs.com/badge.svg
[slack-link]: http://slack.videojs.com
[travis-icon]: https://travis-ci.org/videojs/video.js.svg?branch=main
[travis-link]: https://travis-ci.org/videojs/video.js
[slack-link]: https://slack.videojs.com
[vjs]: https://videojs.com
[coc]: CODE_OF_CONDUCT.md
[coc]: https://github.com/videojs/admin/blob/main/CODE_OF_CONDUCT.md