A GitHub Guide To Fixing a Channel

There's that plug-in that you'd love if only it added that certain show, or maybe your favorite plug-in has just died because of recent website changes and the original developer has gone AWOL. What do you do? You might be happy having a play with the code, but how do you actually maintain your changes and submit them to the store? Well, in this post, we'll look at some really basic setups and workflow on how to push your fixes/improvements to Plex.

In the development of software, it's incredibly important to track and maintain all versions of your code. This can be used for simply reverting back to a previous version of the application or even attempting to determine when a specific bug got introduced. This type of system is known as a Version Control System. There are many alternatives out there, each have their own advantages and disadvantages. Git is an example of a distributed Version Control System which is currently used by Plex. Since it's classed as a “distributed” system, the underlying data can be hosted in various locations, i.e. locally on your computer or even online by a 3rd party server. A popular (free) public repository is available from GitHub and if you browse around, you'll be able to find all currently available Plex Plug-ins. I wouldn't worry too much how this system works under the hood; for now we'll simply walk through a number of scenarios on how to set it up and how to commit changes.

There are numerous different 3rd-party GUI applications that provide a front-end for Git. However, since we're going to be following some fairly simple workflows, we'll just focus on using the command line. After you've gained confidence in this, you can then checkout the applications available and find one that best suits your own needs.

GitHub Setup

The first thing that any budding plug-in developer needs is a GitHub account. It's quick and simple to sign up just by hitting this URL and selecting the “Free Account”. After you've run through the process of creating an account, you'll need to setup your main development machine. There are walkthroughs available for all operating systems:

Forking a Repository

Now that your machine is all ready, it's time to create your own copy of the plug-in. The terminology used is to “fork” the plug-in's repository. This is essentially copying the entire plug-in for your own work. You can then be free to make any changes you desire, before pushing these back to the original repository. Luckily GitHub has also provided us a nice walkthrough on this, including setting up your local copy, which can be found below. Remember, all official plug-ins that you might want to fork are kept in Plex's Plug-In Organization.

Related Page: How to Fork a Repo
Related Page: Plex Plug-in Organization

Work in Progress

What you might not know is that Plex Media Server will continually replace the plug-in bundles stored on your machine. This is to ensure that users always have the most up to date version as available in the store. While being incredibly helpful to most users, it can be a bit of a pain for plug-in developers since if you simply modify the working copy, it will be periodically reverted. There are a couple of workarounds for this problem. The first is to simply keep the bundle separate (i.e. on your desktop) and copy into the Plug-ins folder when ready to test. Another is to set the PlexPluginDevMode parameter to “1″ in the plug-ins plist so that Plex ignores this particular instance. The final option is to create a symbolic link from the Plug-ins folder to your local git repository. A nice simple tool for doing this on OS X can be found here. Once you've finished with your symbolic link, simply delete it and Plex Media Server will eventually replace the now missing plug-in with the one currently available from the store (hopefully your new and improved one!).

Please remember, always change your local repository of the plug-in, and NOT the one downloaded from the store!

Adding/Removing/Committing Changes

So, you've modified a few lines, maybe added a new file and even removed another. After testing your changes to make sure that they are now ready to be committed to the repository, we must first double check that the changed files are as expected. The following command line is a quick and simple way to get details of the current state of your repository:

git status 

If you're happy with the changed files, here are a few command lines to help you mark them as such:

git add path/to/file git rm path/to/file 

You'll notice that the add command is actually appropriate for either new files or simply modified files. Once you've marked all your files appropriately, it's now time to commit them to your local repository. This can be done with the following:

git commit -m "This is a commit message" 

Now that you've done this once, you can repeat this cycle as many times as you need. It's best to keep commits relatively small and focused on a particular issue/area; this makes the repository's commit history much more readable as to how the plug-in development progressed. After each commit, it's perfectly fine to update GitHub (see next section) or not. It's entirely up to you as to what works best for you but think of it this way: if it's been pushed to GitHub, it's safe from any type of failure (e.g. machine spontaneously blowing up).

Updating GitHub

Your local repository now has all the commits required and you'd like to update the repository stored on GitHub. This is particularly simple:

git push origin master 

Bingo, all done. Now check on the GitHub website and you should see that your forked repository now shows all the commits that you've made locally. If you're now done with the development, then there is only one thing left to do: send a Pull Request so that the Plex guys can pick up your changes.

Creating a Pull Request

A Pull Request is exactly what it sounds like. It collects all the commits that you've made since you forked the original repository and asks the owners of the original (e.g. Plex, in this case) if they would like to pull your changes too. The guys over at GitHub have been incredibly helpful and even produced a nice step by step guide on how to do this, which is linked below. It's worth spending a little bit of time on the request's title and details. It's possible that following a quick review, the Plex guys might ask for a few changes which will be done via the Pull Request's comments field. If you make any further changes to your local repository, and update the repository in GitHub, the Pull Request will be automatically updated to now contain your new commits.

Related Page: Creating A Pull Request

Rebasing [Advanced]

Ok, so this is a slightly more advanced topic that I don't want to go into too much detail. What happens if someone else modifies the same Plex repository as you? Imagine you forked a repo a week ago, then yesterday another user had a Pull Request accepted which has now led to modifications of the original. They might be in a slightly different area to yours, but you still want to pull these new changes back over. If you've followed the instructions linked above for Forking a Repository, the "original" repository will be known as “upstream”. However, if you omitted this, you can easily add a remote repo using the following command:

git remote add upstream git://github.com/...git 

Now you need to pull the recent changes from the original repository and rebase your local copy. This is done as follows:

git fetch upstream git rebase upstream/master 

This will essentially replay the new commits sequentially to your local instance. It's possible that you may have made some conflicting changes and therefore Git is unable to continue the process. Thankfully, it will notify you of the file it is struggling with and allow you to have a look at it, decide what the correct combination of commits should look like, and then continue.

Right, it's that simple! Please don't get put off by this. Once you've done it a couple of times, you'll start nailing those command lines without even thinking about it. Also, if you're unsure at all about any of this, just post a query in the Channel Development forum.

Related Page: Channel Development Forum