Skip to content

Latest commit

 

History

History
310 lines (209 loc) · 8.37 KB

CONTRIBUTING.md

File metadata and controls

310 lines (209 loc) · 8.37 KB
Raw

Contributing to PlexTraktSync

We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:

  • Reporting a bug
  • Discussing the current state of the code
  • Submitting a fix
  • Proposing new features
  • Becoming a maintainer

We Develop with GitHub

We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.

We Use GitHub Flow, So All Code Changes Happen Through Pull Requests

Pull requests are the best way to propose changes to the codebase (we use GitHub Flow). We actively welcome your pull requests:

  1. Fork the repo and create your branch from the default branch (main).
  2. If you've added code that should be tested, add tests.
  3. If you've changed APIs, update the documentation.
  4. Ensure the test suite passes.
  5. Make sure your code lints.
  6. Issue that pull request!

Any contributions you make will be under the MIT Software License

In short, when you submit code changes, your submissions will be understood under the same MIT License that covers the project.

Feel free to contact the maintainers if that's a concern.

Report bugs using GitHub's issues

We use GitHub issues to track public bugs. Report a bug by opening a new issue; it's that easy!

Checking out code

If you checkout a specific version, this can be done in one of different ways:

Note: Development should be done against the main branch and not a specific tag.

GitHub download

Proceed to Install dependencies

Git clone

To switch to a different version, find the latest tag and checkout:

git fetch --tags
git checkout <tag>

Proceed to Install dependencies

Install dependencies

This applies to GitHub download and Git clone.

In the PlexTraktSync directory, install the required Python packages:

python3 -m pip install -r requirements.txt

To run from PlexTraktSync directory:

python3 -m plextraktsync

Or use a wrapper which is able to change directory accordingly:

/path/to/PlexTraktSync/plextraktsync.sh

or alternatively you can use pipenv:

python3 -m pip install pipenv
pipenv install
pipenv run plextraktsync

Install code from Pull request

This requires prior installation with pipx. Replace 838 with a pull request you intend to install.

plextraktsync self-update --pr 838

It will create new binary plextraktsync@838 for that pull request. You need to run this binary instead of plextraktsync.

To pull new changes for the same pull request:

plextraktsync@838 self-update

If you need to do the same in docker container, you should:

͏ ͏ ͏1. first prepare the container with:

$ docker-compose run --rm --entrypoint sh plextraktsync
/app # pip install pipx
/app # pipx install plextraktsync
/app # apk add git
/app # plextraktsync self-update --pr 969
/app # plextraktsync@969 info

͏͏͏͏ ͏ ͏2. then run the script with:

/app # plextraktsync@969 sync

Alternatively you can build image yourself.

To remove the versions:

$ pipx list
venvs are in /Users/glen/.local/pipx/venvs
apps are exposed on your $PATH at /Users/glen/.local/bin
   package plextraktsync 0.20.9, installed using Python 3.10.5
    - plextraktsync
   package PlexTraktSync 0.20.0.dev0 (PlexTraktSync@838), installed using Python 3.10.5
    - plextraktsync@838
   package PlexTraktSync 0.20.0.dev0 (PlexTraktSync@984), installed using Python 3.10.5
    - plextraktsync@984

$ pipx uninstall plextraktsync@838
uninstalled PlexTraktSync@838! ✨ 🌟 ✨
$ pipx uninstall plextraktsync@984
uninstalled PlexTraktSync@984! ✨ 🌟 ✨
$

Building docker image

You can build docker image from default branch:

docker build https://github.com/Taxel/PlexTraktSync.git#HEAD -t plextraktsync

To build for a pull request:

docker build https://github.com/Taxel/PlexTraktSync.git#refs/pull/1281/head -t plextraktsync/1281

To build from pull request in docker-compose:

services:
  plextraktsync:
    build: https://github.com/Taxel/PlexTraktSync.git#refs/pull/1892/head

Git: setup pre-commit

For convenience this project uses pre-commit hooks:

brew install pre-commit
pre-commit install

It's usually a good idea to run the hooks against all of the files when adding new hooks (usually pre-commit will only run on the changed files during git hooks):

pre-commit run --all-files

You can update your hooks to the latest version automatically by running pre-commit autoupdate. By default, this will bring the hooks to the latest tag on the default branch.

Testing

We use pytest for testing.

First, ensure you have dependencies installed:

pip3 install -r tests/requirements.txt

To run all tests:

python3 -m pytest

To run specific test:

python3 -m pytest tests/test_version.py

Trakt API

You can use such shell script helper to make requests to trakt api. The .pytrakt.json file can be found from PlexTraktSync Config dir (plextraktsync info).

#!/bin/sh
: ${TRAKT_API_KEY=$(jq -r .CLIENT_ID < .pytrakt.json)}
: ${TRAKT_AUTHORIZATION=Bearer $(jq -r .OAUTH_TOKEN < .pytrakt.json)}

curl -sSf \
     --header "Content-Type: application/json" \
     --header "trakt-api-version: 2" \
     --header "trakt-api-key: $TRAKT_API_KEY" \
     --header "Authorization: $TRAKT_AUTHORIZATION" \
	 "$@"
$ ./trakt-api.sh "https://api.trakt.tv/users/me" | jq -C | less

Sharing Plex Media Server Database

Sometimes it is useful to share your copy of your Plex Media Server database and send it to developers.

The database contains only metadata of your library, not actual media files.

The database contains everything about your setup, including local accounts, so send your database only to people you trust. Plex removes password hashes from the download, so passwords are not exposed, not even in hashed form.

To download and send the database:

  1. Visit Plex Web -> Manage Server -> Settings -> Troubleshooting -> Download database. This is typically https://app.plex.tv/desktop/#!/settings/server/<your_server_id>/manage/help
  2. To find developer email, take any commit made by them, add .patch to the url.
  3. Upload the downloaded database Plex Media Server Databases_*.zip to https://wetransfer.com/
  4. Provide it to PlexTraktSync developer privately via their e-mail

Plex Media XML

Sometimes it's useful to share a fragment, or a complete XML of the item in your library.

The XML can be viewed from Plex Media Servers that you own:

  • Overflow menu → Get Info → View XML in bottom-left corner of the modal

You can read more from Investigate Media Information and Formats Plex support documentation.

License

By contributing, you agree that your contributions will be licensed under its MIT License.

References

This document was adapted from @briandk gist which itself was adapted from the open-source contribution guidelines for Facebook's Draft.