open-source-mirrors
/
jellyfin
mirror of https://github.com/jellyfin/jellyfin
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated Contributing to Jellyfin (markdown)

master
Joshua M. Boniface 5 years ago
parent 0bbc92d2c5
commit 31e0ad8a51
1 changed files with 104 additions and 34 deletions
Show Stats Download Patch File Download Diff File

138
Contributing-to-Jellyfin.md
Unescape

@ -1,58 +1,128 @@
Thank you for your interest in contributing to Jellyfin! We are a community project made up of volunteers doing our best to keep a Free Software version of Emby alive and moving forward.
Thank you for your interest in contributing to Jellyfin! We are a community project made up of volunteers seeking to build the best possible Free Software media system, and we can use all the help we can!
This page details how you can help contribute to Jellyfin. Please give this a read-through before opening an Issue or PR, or if you're not sure how to do either.
Are you a coder and interested in [writing and maintaining C# or Javascript code]? Or are you not a coder and interested in [reporting an issue] or [contributing in other ways]?
# Contributing Code to Jellyfin
The Jellyfin project consists of a C# core server, a Javascript-based UI, and a number of client applications written in various languages and frameworks. If you have experience with these languages, we're always grateful for any contribut
ions you might want to make!
## What should you do?
The best way to get going is to look through the [Issues list], find an issue you would like to work on, and start hacking. Our issues are triaged regularly by the administrative team, and labels assigned that should help you find issues within your skill-set.
### Major Issue Types
These first two are broad categories for which part of Jellyfin the issue affects:
* `UI`: An issue that mainly relates to the UI frontend code.
* `Backend`: An issue that mainly relates to the server backend code.
* `build/platform`: An issue that mainly relates to building or packaging the project.
These types help determine how critical an issue is:
* `regression`: An issue in need of immediate attention due to a regression from the last build.
* `bug`: A bug in the code that affects normal usage.
* `enhancement`: An issue that requests a modification of an existing feature.
* `feature`: An issue that requests a new feature not present in Jellyfin.
Finally there are a few more issue types to assist in managing the project:
* `Good first issue`: Something that should be very straightforward to do, and is a great place to get started.
* `help wanted`: An issue that currently has no clear expert within the project and could use outside assistance.
* `roadmap`: A meta-issue related to the future roadmap of the project.
* `documentation`: An issue related to the documentation of the project.
* `fork`: An issue related to the forking from Emby.
### What if there isn't an issue?
If there isn't already an issue dealing with the changes you want to make, please [create an issue] to track it first, then ensure your PR(s) reference the issue in question. Especially useful for bugs that are found and then fixed by the
author.
## How should you make changes?
Once you've found something you want to work on or improve, the next step is to make your changes in the code, test them, then submit a PR. This section details how to go about doing that. For simplicity, all examples assume the developer
is operating on Linux with SSH access to GitHub, however the general ideas can be translated to Windows or OSX.
If you aren't familiar with Git, we recommend the [official documentation](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) to get yourself going.
### Set up your copy of the repo
The first step is to set up a copy of the repo that you can work from. Jellyfin follows a "fork and PR" methodology.
This document describes how to contribute to Jellyfin via GitHub, and is applicable to anyone who might wish to open up an issue or do a pull request. Please give it a read-through first.
1. On GitHub, "Fork" the Jellyfin repo to your own user.
1. Clone your fork to your local machine: ```git clone git@github.com:yourname/jellyfin.git```
1. Add the "upstream" remote: ```git remote add upstream git@github.com:jellyfin/jellyfin.git```
1. Initialize submodules: ```git submodule update --init```
Before contributing it is advised to read over our [coding style guide](https://github.com/jellyfin/jellyfin/wiki/Jellyfin-Coding-Style) to ensure consistent coding as well as name usage.
You should now be ready to begin building or modifying the project.
## How can I contribute?
### Making changes to the repo
If you're a .NET C# or Javascript developer, please feel free to jump right in - we can use all the help we can get! A section on our Pull Request policy is below.
Jellyfin uses a "feature branch" model, though usually a feature branch is local to each developer and is integrated in one shot, though in the future project-wide feature branches may become common. This section assumes a local feature br
anch.
If you're not a developer, please consider helping out by contributing documentation, testing the latest releases and reporting bugs, or by telling your friends about the project! Any little bit helps.
1. Rebase your local branches against upstream `master`/`dev`: ```git fetch --all && git rebase upstream/<BRANCH>```
1. Create a local feature branch off of `dev`: ```git checkout dev && git checkout -b my-feature```
1. Make your changes and commits to this local feature branch, `git rebase`ing off of `dev` regularly, especially before submitting a PR.
1. Push up your local feature branch to your GitHub fork: ```git push --set-upstream origin my-feature```
1. On GitHub, create a new PR against the upstream `dev` branch.
## Issues
### CONTRIBUTORS.md
If it's your first time contributing code, please add yourself to the `CONTRIBUTORS.md` file at the bottom of the `Jellyfin Contributors` section. While GitHub does track this, having the written document makes things clearer if the code l
eaves GitHub and lets everyone quickly see who's worked on the project for copyright or praise!
### Pull Request guidelines
Issues should be one of three things:
When submitting a new PR, please ensure you do the following things. If you haven't, please read [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) as it is a great resource for writing useful commit messages.
* Write a good title that quickly describes what has been changed. For example, "Adds LDAP support to Jellyfin".
* For anything but the most trivial changes (that can be described fully in the title), write a detailed PR body to describe, in detail:
1. *Why* the changes are being made. Reference specific issues with keywords (`fixes`, `closes`, `addresses`, etc.) if at all possible.
1. *How*, in broad strokes, you approached the issue (if applicable) and briefly describe the changes, especially for large PRs.
1. *Which area* of the project this addresses, to assist in tagging.
* Manually update the target branch from `master` to `dev`; PRs against `master` are only considered in the most exceptional circumstances and all new work should go to `dev`. GitHub does not know this, so you must be explicit with every P
R.
* Expect review and discussion. If you can't back up your changes with a good description and through review, please reconsider whether it should be done at all. All PRs to `dev` require at least one approving review from an administrative
team member, however we welcome and encourage reviews from any contributor, especially if it's in an area you are knowledgeable in. More eyes are always better.
1. A software bug with Jellyfin.
2. A feature request or suggestion.
3. A task to be done with Jellyfin.
## The Master branch
All other discussions should be directed towards the [Jellyfin Riot channel](https://matrix.to/#/#jellyfin:matrix.org), the [Jellyfin development Riot channel](https://matrix.to/#/#jellyfin-dev:matrix.org), or [our subreddit](https://reddit.com/r/jellyfin).
The `master` branch is the current working branch of Jellyfin. Until we reach a first official release with our own versioning, releases are limited to build identifiers (i.g. `3.5.2-X`). Each update to `master` occurs through a roll-up PR
made by an admin team member, on a semi-regular basis, which will identify the relevant PRs (and issues) that are fixed and help ensure there is a consistent trail of development work in the history. `master` merges must be approved by tw
o administrative team members, thus ensuring a majority of the team accepts the changes.
When writing an issue, please ensure you capture as much relevant detail as possible - having to request additional information just leads to wasted time. Please include any log output, configuration options, and system details you can get in the initial issue, and provide anything requested as quickly as possible.
# Other Contributions to Jellyfin
## Pull Requests
Even if you can't contribute code, you can still help Jellyfin! The two main things you can help with are testing and creating Issues, and contributing to documentation, translations, and other non-code components.
We adhere to a fairly standard fork-and-PR model of development:
## Issue guidelines
1. Fork a copy of the Jellyfin repository to your own user.
Issues should be one of three things:
2. Make your changes on a local feature branch of your copy of the repository.
1. A software bug with Jellyfin.
1. A feature request or suggestion.
1. A task to be done with Jellyfin.
3. Submit a pull request from your feature branch back to the upstream `dev` branch. PRs that target `master` will be changed to target `dev`, so please double-check this when submitting.
All other discussions should be directed towards one of the [Jellyfin Riot channels](https://github.com/jellyfin/jellyfin/wiki/Riot-Matrix-Rooms), or [our subreddit](https://reddit.com/r/jellyfin).
Please ensure you provide a detailed explanation, in each pull request discription, of what problems the PR solves (with action keywords and links to issue numbers if possible), and how the PR solves them. This aids both in review, as well as in future understanding of why a given set of changes were made. More detail is always better here. Also please ensure that if your issue fixes an issue (or several issues), that you explicitly reference this, preferably with the `closes` or `fixes` keywords, e.g. `Closes #199`, in the original description.
When writing an issue, please ensure you capture as much relevant detail as possible - this is very important to assist in troubleshooting and triaging/investigating the issue. Please include any log output, configuration options, and system details you can in the initial issue, and provide anything requested as quickly as possible.
All PRs to the `develop` branch require review by at least 1 member of the core team. Once that is done, if the PR is not tagged with the WIP label, it should be merged by the reviewer if able. We do however encourage reviews from any contributor as more eyes always helps.
To assist in triaging, if you know which label(s) should applied to your issue, please add them to the beginning of the issue name in square brackes, like this: "[feature][UI] Add the widget to the front panel". Issues will be triaged in time by the administrative team, and these flags will be removed from the title and issue labels added. This is required due to GitHub's permission system.
Merges from `develop` back into `master` will occur when needed, and must be reviewed by at least 2 members of the core team. Once that is done, a third core team member should review the reviews and merge the commit.
### Searching for issues and upvoting
### Example setup procedure on Linux with GitHub SSH access:
Before opening an issue, please searched both open and closed issues to see if a similar problem or feature request has been reported. Duplicate issues clutter the repository and should be avoided.
1. On GitHub, "Fork" the Jellyfin repo to your own user.
2. From your copy, clone it down: ```git clone git@github.com:yourname/jellyfin.git```
3. Add the "upstream" remote: ```git remote add upstream git@github.com:jellyfin/jellyfin.git```
4. Initialize submodules: ```git submodule update --init```
5. Update your local branches against upstream `master`/`dev`): ```git fetch --all && git rebase upstream/<BRANCH>```
5. Do new development in a local feature branch off of `dev`: ```git checkout dev && git checkout -b my-feature```
6. Push up your local feature branch once ready: ```git push --set-upstream origin my-feature```
7. On GitHub, do a PR against `dev`.
If you do find an issue that matches, or closely matches, your issue, please make use of the :+1: reaction to confirm the issue also affects you or that you support the feature request. If you wish, add a comment as well describing your version of the issue or feature usecase.
If the existing issue is closed, please read through it to see if the accepted workaround(s) apply to your case. If not, leave a comment and the issue will be reopened. Note that, since PRs go into `dev` first but releases are built from `master`, an issue's fix won't be immediately available in the official sources, but will be included in the next release.
## CONTRIBUTORS.md
## Documentation
If it's your first time contributing code, please add yourself to the `CONTRIBUTORS.md` file at the bottom of the `Jellyfin Contributors` section. While GitHub does track this, having the written document makes things clearer if the code leaves GitHub.
Documentation is incredibly helpful to us, though we're still figuring out exactly where to put it all - `readthedocs` is a likely choice. For now, please write up any documentation suggestions you have, preferably in Markdown formatting, and open up an issue to get it added!
## Developer Access
## Translations
Currently the core team consists of @joshuaboniface, @nvllsum, @JustAMan, @dcrdev, and @anthonylavado. At least one of the core team members is required to merge code. We may augment this team in the future at our discretion, but for now we seek to keep this team a small group while we establish ourselves.
We're still working to set up a translation system that will help automate this, but for now translations occur in the frontend code. This is a complex process so please ask for help if you wish to assist right now.
Write Preview
Loading…
Cancel
Save