V0.4 Installing A Specific Branch or Release
There are lots of ways of installing plugins. One of the easiest is via a URL containing the location of an archived version of the repository. GitHub will generate an automatic archive for every commit, branch, and release. You just need to know how to find the one you want and how to use it within OctoPrint.
In this guide I will explain what the different types of installations are and how to find a URL for each.
Important Note: Installing from a branch, commit, or pre-release version may introduce unexpected issues. DO NOT install one of these unless you understand the risks associated with using pre-release or development versions. I also recommend you use the build-in Backup & Restore plugin (available within the OctoPrint settings menu) to create a full backup before installing any pre-release/development code. It's a good idea to backup regularly even if you only install release code (bugs exist in all software).
Github can be confusing. However, once you know where to look and what to look for, finding the installation URL you want is pretty simple. Below are a few different types of URLs you can choose from.
A release is a specific point in time where the developer decided to expose new code to the world. Typically additional testing is done and documentation is generated. These are probably the safest URLs discussed here to install from because extra care goes into a release versus a simple commit.
You can find all of the Octolapse releases here, where the most recent release is on top.
Some of these versions are development versions, some maintenance releases, and some are stable. All maintenance and development releases will have a Pre-Release tag:
Be sure to read the release notes before you install. Release notes often contain instructions, links, descriptions of solved and known issues, as well as a link to report feedback.
Each release will contain a couple Assets. You may need to expand the Assets before you can see the archives. Next, copy the Source code (zip) link:
Branches are a way for a developer to separate different changes, to experiment with new code, or to work on specific features or releases. Some branches will be deleted, some may go stale, and another branch may contain the latest stable release. Keep in mind that code changes can happen on these branches at any time, so the code you grabbed yesterday might be different today. I do not recommend that you install directly from a branch unless you have a very good reason to do so. In general, unless you are asked to install from a specific branch or if you are creating a pull request, I would NOT do this.
You can find all of the branches here. Some of the branches are uninteresting, but here are some you may want to check out:
https://github.com/FormerLurker/Octolapse/archive/master.zip - This branch always contains the latest stable release of Octolapse. This is the branch that is installed if you search for Octolapse in the Plugin Manger.
https://github.com/FormerLurker/Octolapse/archive/rc/maintenance.zip - This branch contains pre-release versions of Octolapse that are (usually) nearly ready for production. These are more thoroughly tested than the rc/devel branch but less tested than the master branch.
https://github.com/FormerLurker/Octolapse/archive/rc/devel.zip - This repository contains development work that usually involves preparing for a new rc/maintenance release. Additionally, any bugs found within an rc/maintenance will be first fixed and applied to the rc/devel build before carrying over to rc/maintenance.
https://github.com/FormerLurker/Octolapse/archive/devel.zip - This is the 'bleeding edge' branch. You can expect to find bugs or breaking changes at any time here. I don't recommend you install Octolapse from this branch unless you've been specifically told to do so within a support ticket. However, if you are planning to fork Octolapse and submit a pull request, this is the branch you should target. Shoot me an email if you plan to submit a pull request but are not sure what branch to target.
If you know which branch you want to install from, just copy the URL from the above list or navigate to the branch and copy the URL from the button located here:
Notice the Branch drop down circled on the left hand side. You can choose any branch you want from there.
Commits represent individual code changes. They are a log of what has changed since the previous commit. You can think of it as a snapshot in time for ever-changing code. Each release is actually tied to a commit. In fact, the URLs available for the Branches in the previous section actually just point to the most recent commit for each branch.
In general you will not want to install from a specific commit unless you are asked to do so. You can find a list of commits by first selecting a branch and then clicking on the commits link:
Clicking on the commits link above will take you to a list of commits made on the master branch. You can select any branch you like and view all of the commits in the same way.
Once you arrive at a specific commit, you can view a snapshot of the exact state of all files at that point in time by clicking on this link:
Now you can find and copy the installation URL here:
Notice the commit ID circled in the upper left corner.
Once the URL is copied into your clipboard, you are all set to install!
Once you have the proper URL, installation is easy! Just follow these steps:
- Open the OctoPrint settings by clicking on the wrench/spanner icon in the upper left hand corner.
- Click on the Plugin Manger link within the left menu.
- Click on the Get More... button.
- Paste the archive URL into the ... from URL text box and click the Install button to the right of the pasted URL.
It will take a while to install Octolapse, especially on slower hardware. This is because Octolapse has to compile quite a bit of code, which is a slow process. Please be patient. Also, be sure to reboot after installation is complete!