zoriya/v10
1
0
Fork 0
mirror of https://github.com/zoriya/v10.git synced 2026-08-16 02:45:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(root): update readme and contributing

Browse Source 
closes #70
This commit is contained in:
Rahim
2025-11-24 15:29:42 +11:00
parent f3b1b19917
commit 1c8ba68885
4 changed files with 34 additions and 703 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+27 -125
View File
@@ -2,89 +2,17 @@
First off, thank you for taking the time to contribute to **Video.js 10** ❤️
Your input helps shape the next generation of open web media players.
There are a variety of ways you can help out.
> [!NOTE]
> If you're looking to contribute to the current version of Video.js (v8), please refer to its [contributor guide][vjs-contributor-guide] instead.
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. Contributions and project decisions are overseen by the
[Video.js Technical Steering Committee (TSC)][vjs-gov].
## Table of Contents
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Filing issues](#filing-issues)
- [Reporting a Bug](#reporting-a-bug)
- [Requesting a Feature](#requesting-a-feature)
- [🎒 Contributing code](#-contributing-code)
- [Running locally](#running-locally)
- [Prerequisites](#prerequisites)
- [Fork & Clone](#fork--clone)
- [Install Dependencies](#install-dependencies)
- [🏗 Building & Development](#-building--development)
- [🧹 Style & Linting](#-style--linting)
- [🧪 Testing](#-testing)
- [📦 Managing Dependencies](#-managing-dependencies)
- [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: Commits](#step-4-commits)
- [Step 5: Test](#step-5-test)
- [Step 6: Pushing & Pull Requests](#step-6-pushing--pull-requests)
- [Community Engagement](#community-engagement)
- [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11)
- [Doc Credit](#doc-credit)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Filing issues
[GitHub Issues](https://github.com/videojs/v10/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. Use the [GitHub issue search](https://github.com/videojs/v10/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://stackoverflow.com/help/minimal-reproducible-example)** with a live example.
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/v10/issues/new?template=1.bug_report.yml)**
### Requesting a Feature
1. [Search the issues](https://github.com/videojs/v10/issues) and [ideas](https://github.com/videojs/v10/discussions/categories/ideas) 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 detailed as possible and follow the issue template.
- **[Request a smaller feature](https://github.com/videojs/v10/issues/new?template=2.feature_request.yml)**
- **[Propose a larger feature](https://github.com/videojs/v10/discussions/new?category=ideas)**
### Providing Docs Feedback
1. [Search the issues](https://github.com/videojs/v10/issues) for any potential overlapping docs feedback, 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 your docs feedback.
1. Once again, be as detailed as possible and follow the issue template.
**[Provide docs feedback](https://github.com/videojs/v10/issues/new?template=3.docs_feedback.yml)**
[vjs-gov]: https://github.com/videojs/admin/blob/main/GOVERNANCE.md
## 🎒 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.
Video.js 10 is set up a monorepo using [`pnpm` workspaces](https://pnpm.io/workspaces). As such, most scripts run will be done from the project/workspace root. Unless otherwise specified, assume commands and similar should be run from the root directory.
### Running locally
> [!IMPORTANT]
> Video.js 10 is set up a monorepo using [`pnpm` workspaces](https://pnpm.io/workspaces). As such, most scripts run will be done from the project/workspace root. Unless otherwise specified, assume commands and similar should be run from the root directory. For a high level breakdown of the monorepo structure, see the [README](./README.md#project-structure).
#### Prerequisites
### Getting Your Machine Ready
You’ll need the following installed:
@@ -97,16 +25,14 @@ You’ll need the following installed:
> PNPM will automatically use the correct Node version when running scripts.
> If you prefer NVM: after installing it, simply run `nvm use` in the repo root.
---
#### Fork & Clone
### Fork & Clone
1. [Fork on GitHub][vjs-gh].
2. Clone your fork locally and set up upstream tracking:
```sh
git clone https://github.com/{your-github-username}/v10.git
cd v10
cd vjs-10
git remote add upstream git@github.com:videojs/v10.git
git fetch upstream
@@ -121,9 +47,7 @@ git checkout main
git pull upstream main
```
---
#### Install Dependencies
### Install Dependencies
```sh
pnpm install
@@ -140,12 +64,7 @@ pnpm build:packages
> If imports like `react` are not resolving, set your TS version to the workspace one:
> `CMD/CTRL + Shift + P` → `TypeScript: Select TypeScript Version` → _Use Workspace Version_.
---
#### 🏗 Building & Development
To facilitate faster iterations when experimenting, smoke testing, and validating code changes, we employ "developer mode",
which watches for code changes and automatically rebuilds (and reloads) all core code, including framework packages, example applications, and our website.
### 🏗 Building & Development
To run the workspace in development mode:
@@ -155,9 +74,8 @@ pnpm dev
This will run the entire workspace in developer mode, meaning all applications (examples and website) will also be started on their respective ports.
To run a specific application:
```sh
# Run a specific app
pnpm dev:html
pnpm dev:react
pnpm dev:next
@@ -166,8 +84,6 @@ pnpm dev:site
Sometimes you may want to do (non-dev) builds, say, to validate the full build process or evaluate production artifacts.
As mentioned above, you can build just our framework packages via:
```sh
pnpm build:packages
```
@@ -178,11 +94,9 @@ To build all workspace packages and applications:
pnpm build
```
---
### 🧹 Style & Linting
#### 🧹 Style & Linting
For the bulk of our core code, we use a [slightly modified](./eslint.config.mjs) version of [`@antfu/eslint-config`](https://www.npmjs.com/package/@antfu/eslint-config) along with [`prettier`](https://prettier.io/) for things like markdown or svgs. Between IDE configs, pre-commit hooks, and manual CLI fixes, many styling and linting issues should get caught without too much concern.
For the bulk of our core code, we use a [slightly modified](./eslint.config.mjs) version of [`@antfu/eslint-config`](https://www.npmjs.com/package/@antfu/eslint-config) along with [`prettier`](https://prettier.io/) for things like markdown or svgs. Between IDE configs, pre-commit hooks, and manual CLI fixes, many styling and linting issues should get caught automatically.
To ensure your code follows our lint rules with:
@@ -193,14 +107,10 @@ pnpm lint:fix
Pre‑commit hooks automatically lint staged files via **simple-git-hooks** and **lint‑staged**.
---
#### 🧪 Testing
### 🧪 Testing
We use [Vitest](https://vitest.dev) for unit testing.
You can run tests with:
```sh
pnpm test # all workspace tests
pnpm test:core # just core package
@@ -208,9 +118,7 @@ pnpm test:core --watch
pnpm test:core file.spec
```
---
#### 📦 Managing Dependencies
### 📦 Dependencies
To add a dependency to a specific package, you can use [`pnpm` Filtering](https://pnpm.io/filtering) from the workspace root:
@@ -229,15 +137,16 @@ pnpm up <package>@<version> -r
> [!CAUTION]
> We try to be very intentional with any dependencies we add to this project. This is true of both developer/tooling dependencies and especially package-level (source) dependencies. If you find yourself needing to add a dependency, we strongly encourage you to check in with the core maintainers before proceeding to avoid wasted time and effort for everyone involved (yourself included!).
---
## Creating a Pull Request
### Making Changes
By submitting a pull request, you agree that your contribution is provided under the
[Apache 2.0 License](./LICENSE) and may be included in future releases. No contributor license agreement (CLA) has ever been required for contributions to Video.js. See the [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11).
#### Step 1: Verify
### 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/v10/issues) 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
### Step 2: Update remote
Before starting work, you want to update your local repository to have all the latest changes from `upstream/main`.
@@ -250,7 +159,7 @@ git pull upstream main
> [!NOTE]
> If `git pull upstream main` fails, this means either you've committed changes to your local clone of `main` or there was a (rare) change in `upstream/main`'s commit history. In either case, if you simply want to base your local clone off of the latest in `upstream/main`, you can simply run: `git checkout -B main upstream/main` (assuming you've already `fetch`ed). For more on `git checkout -B`, check out the [git docs](https://git-scm.com/docs/git-checkout#Documentation/git-checkout.txt-gitcheckout-b-Bnew-branchstart-point).
#### Step 3: Branch
### Step 3: Branch
You want to do your work in a separate branch. In general, you want to make sure the branch is based off of the latest in `upstream/main`.
@@ -265,7 +174,7 @@ One helpful naming convention approximates [conventional commits](conventional-c
- `docs/site-docs-for-x`
- `chore/repo-cleanup-task`
#### Step 4: Commits
### Step 4: Commit
We follow **[conventional commits semantics][conventional-commit-style]** to enable automated releases.
@@ -278,9 +187,7 @@ Examples:
> [!TIP]
> Run `git log` (or `git log --oneline`) to check recent examples before committing.
---
#### Step 5: Test
### 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.
@@ -291,9 +198,7 @@ pnpm test
See [Testing](#-testing) for more information.
---
#### Step 6: Pushing & Pull Requests
### Step 6: Push
When ready, push your branch up to your fork (or upstream if you are a core contributor):
@@ -301,13 +206,15 @@ When ready, push your branch up to your fork (or upstream if you are a core cont
git push --set-upstream origin fix/my-issue
```
Then, open a PR via the green **“Compare & Pull Request”** button. In the description, make sure you thoroughly describe your changes and [link](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) any related issues or discussions.
Then, open a PR via the green **“Compare & Pull Request”** button. In the description, make sure you thoroughly describe your changes and [link related issues or discussions][link-pr-issue].
- Keep PRs focused and small when possible.
- Give reviewers time to provide feedback.
- Even if a PR isn’t merged, your work helps shape the direction of Video.js 10 ❤️
## Community Engagement
[link-pr-issue]: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword
## Community
To discuss larger ideas or prototypes, or to help out with ongoing discussions, open a thread in:
@@ -340,12 +247,7 @@ By making a contribution to this project, I certify that:
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
## Doc Credit
This doc was heavily inspired by the [contributor guide][vjs-contributor-guide] for the current (v8) version of Video.js.
[vjs-gh]: https://github.com/videojs/v10
[conventional-commit-style]: https://www.conventionalcommits.org/en/v1.0.0/#summary
[discord]: https://discord.gg/JBqHh485uF
[gh-discussions]: https://github.com/videojs/v10/discussions
[vjs-contributor-guide]: https://github.com/videojs/admin/blob/main/CONTRIBUTING.md
README.md
+7 -57
View File
@@ -15,21 +15,6 @@ and early structure pointing in the direction we want to go with Video.js v10 (s
- Read the [v10 discussion topic](https://github.com/videojs/video.js/discussions/9035)
- Watch [Heff's recent presentation](https://players.brightcove.net/3737230800001/eyILA5XG7K_default/index.html?videoId=6379311036112)
## Table of Contents
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Timeline](#timeline)
- [Documentation](#documentation)
- [Project Structure](#project-structure)
- [Community](#community)
- [Contributing](#contributing)
- [Code of Conduct](#code-of-conduct)
- [How can I help?](#how-can-i-help)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Timeline
🚧 Detailed roadmap coming soon. 🚧
@@ -46,34 +31,6 @@ If you'd like to get started and learn more, you can find our documentation on o
- [Website][site]
- [Documentation][docs]
## Project Structure
This project is organized as a monorepo. Here's an overview:
- **Packages** - publicly published packages that make up the Video.js 10 media player framework
- [core](./packages/core/) - shared platform/framework agnostic functionality, including
- media store compositional definitions
- media renderer and playback Engine functionality
- common core component behaviors and functionality
- [icons](./packages/icons/) - core (svg) icon set definitions used by platform/framework-specific implementations
- [html](./packages/html/) - web component implementations of
- media UI components
- media icons
- media renderers
- media (state) providers
- [react](./packages/react/) - React implementations of
- media UI components
- media icons
- media renderers
- media (state) providers
- [utils](./packages/utils/) - various platform agnostic (shared) and platform specific (dom) utility functions
- **Examples** - example applications for using Video.js 10.
- [html-demo](./examples/html-demo/) - an example application for using and smoke testing [@videojs/html](./packages/html/)
- [react-demo](./examples/react-demo/) - an example application for using and smoke testing [@videojs/react](./packages/react/)
- [next-demo](./examples/html-demo/) - an example application for using and smoke testing [@videojs/react](./packages/react/) (Useful for validating things like SSR or other complexities not surfaced by [react-demo](./examples/react-demo/)
- **Other**
- [site](./site) - the codebase for the [Video.js 10 website](http://v10.videojs.org)
## Community
If you need help with anything related to Video.js 10, or if you'd like to casually chat with other
@@ -84,20 +41,7 @@ members:
## 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.md) for more! Contributions and project decisions are overseen by the
[Video.js Technical Steering Committee (TSC)](https://github.com/videojs/admin/blob/main/GOVERNANCE.md).
By submitting a pull request, you agree that your contribution is provided under the
[Apache 2.0 License](./LICENSE) and may be included in future releases. No contributor license agreement (CLA) has ever been required for contributions to Video.js. See the [Developer's Certificate of Origin 1.1
](./CONTRIBUTING.md#developers-certificate-of-origin-11).
## Code of Conduct
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/videojs/video.js/blob/main/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
## How can I help?
Join our community channels above and give us feedback! Keep in mind this is a technical preview
We'd love for you to join our community channels above and give us feedback! Keep in mind this is a technical preview
and we're working on a lot of polish over the coming months. Feedback on any of the following
would help us:
@@ -108,6 +52,12 @@ would help us:
- Repo, workspace, contributor guides
- Component structures and APIs
Please see our [contributing guide](./CONTRIBUTING.md) for getting setup locally and making code or docs changes.
## Code of Conduct
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/videojs/video.js/blob/main/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
[site]: http://v10.videojs.org
[docs]: http://v10.videojs.org/docs
[package]: https://www.npmjs.com/package/@videojs/core
package.json
-2
View File
@@ -18,7 +18,6 @@
"prepare": "simple-git-hooks",
"build:packages": "turbo run build --filter=./packages/**",
"build:site": "turbo run build --filter=site",
"docs:update": "doctoc README.md CONTRIBUTING.md",
"build": "turbo run build",
"clean": "turbo run clean",
"commitlint": "commitlint --config ./commitlint.config.js --edit $1",
@@ -43,7 +42,6 @@
"@ianvs/prettier-plugin-sort-imports": "^4.7.0",
"@prettier/plugin-xml": "^3.4.2",
"@types/node": "^22.18.6",
"doctoc": "^2.2.1",
"eslint": "^9.37.0",
"eslint-plugin-astro": "^1.3.1",
"eslint-plugin-format": "^1.0.2",
pnpm-lock.yaml
Generated
-519
View File
File diff suppressed because it is too large Load Diff