jellyfin/jellyfin-web
1
0
Fork 0
mirror of https://github.com/jellyfin/jellyfin-web.git synced 2026-09-02 19:43:13 +03:00
Code Issues Packages Projects Releases Wiki Activity

Add contributing guide and pr checklist

Browse Source
This commit is contained in:
Bill Thornton
2026-03-20 09:38:51 -04:00
parent 9547577630
commit e03d32db82
2 changed files with 106 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/pull_request_template.md
+22 -8
View File
@@ -3,13 +3,27 @@ Ensure your title is short, descriptive, and in the imperative mood (Fix X, Chan
For a good inspiration of what to write in commit messages and PRs please review https://chris.beams.io/posts/git-commit/ and our https://jellyfin.org/docs/general/contributing/issues page.
-->
**Changes**
<!-- Describe your changes here in 1-5 sentences. -->
### Changes
<!--
Describe your changes here in 1-5 sentences.
Please include before/after screenshots of any UI changes.
-->
**Issues**
<!-- Tag any issues that this PR solves here.
ex. Fixes # -->
### Issues
<!--
Tag any issues that this PR solves here.
ex. Fixes #
-->
**Code assistance**
<!-- If code assistance was used, describe how it contributed
e.g., code generated by LLM, explanation of code base, debugging guidance. -->
### Code assistance
<!--
If code assistance was used, describe how it contributed
e.g., code generated by LLM, explanation of code base, debugging guidance.
-->
---
* [ ] I have read and followed the [contributing guidelines](https://github.com/jellyfin/jellyfin-web/blob/master/CONTRIBUTING.md).
* [ ] I have tested these changes.
* [ ] I have verified that this is not duplicating changes in an existing PR.
* [ ] I have provided a *substantive* review of [another web PR](https://github.com/jellyfin/jellyfin-web/pulls?q=is%3Apr+is%3Aopen+-label%3Adependencies+-label%3Ablocked+-label%3Abackend+-label%3Ainvalid+-label%3A"merge+conflict"+-label%3Astale+-author%3A%40me).
CONTRIBUTING.md
+84
View File
@@ -0,0 +1,84 @@
# Contributing to Jellyfin Web
Thanks for taking the time to contribute! :purple_heart:
Jellyfin is an entirely volunteer-driven project, so without contributors like you it could not exist!
Below are some general guidelines and information about this project.
If you have any questions, please join one of our [development chat rooms](https://jellyfin.org/contact/) to discuss them!
## Contributor Guidelines
### New Code
* New files **MUST** be written in TypeScript.
* API interactions **MUST** be made using the Jellyfin TypeScript SDK.
* **SHOULD** be covered by unit tests when possible (legacy component/view code is deemed untestable).
* **SHOULD** avoid whitespace only changes in unchanged sections of code.
* **SHOULD NOT** overuse dynamic imports. We use dynamic imports at the page level; otherwise we should let our build tooling deal with code-splitting for the best bundle sizes.
* **SHOULD NOT** reference browser globals. Globals exist for plugins/legacy compatibility. Use direct imports for any dependencies instead.
### Localization
* Translation changes or additions **MUST** be made via the [Jellyfin Weblate instance](https://translate.jellyfin.org/) except for the source language (`en-us`).
* Existing translation keys **SHOULD NOT** be renamed without a significant reason. Weblate cannot track key name changes so a key name change requires retranslation in ALL languages.
### Pull Requests
* **MUST** follow [project guidelines](https://jellyfin.org/docs/general/contributing/development#pull-request-guidelines).
* **SHOULD NOT** use "Conventional Commits" for titles or commit messages.
* **SHOULD NOT** rebase once reviews are in progress.
* **MUST** follow the [LLM development policy](https://jellyfin.org/docs/general/contributing/llm-policies).
* **MUST** test that the change works as expected before marking a PR as ready for review.
* **SHOULD** represent a singular focus (i.e. a PR to fix a bug should not include unrelated refactoring).
* **SHOULD NOT** update from `master` needlessly once opened (only update if conflicts exist).
## Application Architecture
### Tech Stack
* [Bulletproof React based structure](https://forum.jellyfin.org/t-proposed-update-to-the-structure-of-jellyfin-web) ([official reference](https://github.com/alan2207/bulletproof-react/blob/master/README.md)) &mdash; General file structure
* [TypeScript](https://www.typescriptlang.org/docs/handbook/intro.html) &mdash; Programming language
* [Jellyfin TypeScript SDK](https://typescript-sdk.jellyfin.org/) &mdash; Jellyfin API library
* [React](https://react.dev/reference/react) &mdash; User Interface library
* [React Router](https://reactrouter.com/) &mdash; Routing library
* [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview) &mdash; State management library for server data
* [MUI](https://mui.com/material-ui/getting-started/) components (in Dashboard and Experimental layouts) &mdash; UI component library
* [Webpack](https://webpack.js.org/concepts/) &mdash; Bundler / build tooling
* [Vitest](https://vitest.dev/api/) &mdash; Test library
#### Legacy Stack
| Library | Replacement |
| --- | --- |
| [Emby WebComponents](https://github.com/jellyfin/jellyfin-web/tree/master/src/elements) | MUI components (Dashboard + Experimental apps ONLY; Untested on TVs) |
| [App Router](https://github.com/jellyfin/jellyfin-web/blob/master/src/components/router/appRouter.js) | React Router |
| [View Manager](https://github.com/jellyfin/jellyfin-web/tree/master/src/components/viewManager) | React Router |
| [Jellyfin ApiClient](https://github.com/jellyfin-archive/jellyfin-apiclient-javascript) | Jellyfin TypeScript SDK |
| [jQuery](https://api.jquery.com/) | None (use plain JavaScript/TypeScript) |
#### Supported Browsers
This codebase supports a wide variety of platforms including TVs that are stuck on ancient versions of browser engines.
As a result, we can only use JavaScript and CSS features that are either directly supported by these browser versions or can be otherwise compiled or polyfilled for compatibility.
The official list of supported browser versions can be found in the `browserlist` section of the [package.json file](https://github.com/jellyfin/jellyfin-web/blob/master/package.json).
## Application Components
* Stable App `src/apps/stable`
* Main user application
* Supports TV layout
* Experimental App `src/apps/experimental`
* Ongoing rewrite of the Stable App using MUI components
* Currently reuses (most) pages from the Stable App to maintain parity
* Does not currently support TV layout!
* Dashboard App `src/apps/dashboard`
* Admin dashboard and metadata editor pages
* Almost completely rewritten using MUI components
* No TV support (dashboard pages are not available)
* Wizard App `src/apps/wizard`
* First time setup wizard
* Plugins `src/plugins`
* This is a terrible name as it has nothing to do with server plugins
* Modular functionality that is loaded dynamically at runtime
* ALL media player implementations are plugins
* Allows native wrapper overrides