Boards Manager Support File Locations on GitHub

Boards Manager JSON index file format specification:
https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.6.x-package_index.json-format-specification

Arduino IDE 1.6.4 introduced installation of Boards by adding URLs to File > Preferences > Additional Boards Manager URLS:. Boards Manager makes it easy for users to install and keep Boards files up to date. When you create a new version it will automatically be shown as an update option in Boards Manager.

You can see how others have implemented Boards Manager install support at the Unofficial list of 3rd party boards support urls.

Adding Boards Manager install support requires two files to be made available online:

• Installation Archive: This is a compressed file that contains all your board files.

• Package Index: This file provides information to Boards Manager. The URL of this file will be your Boards Manager install URL.

It's worth giving the location of the package index file some thought because it is best not to change the URL after people have already added it to their preferences. You could use a combination of these locations, one for the package index and another for the installation archive:

1. gh-pages branch(e.g., Adafruit)
   • Pros: URL is shorter(e.g., https://janedeveloper.github.io/myboard/package_janedeveloper_myboard_index.json).
   • Cons: May add another branch.

2. Preexisting branch(e.g., Sparkfun)
   • Pros: Doesn't add any more branches to the repository.
   • Cons: Adds files that are useless to someone doing a manual install.

3. Github Releases(e.g., Sanguino)
   • Pros: You may already be using Releases for your versions.
   • Cons:
     • The folder structure of the Boards Manager install file is different than the manual installation file(no avr folder) so this requires a separate Boards Manager install file to be added to each release. This may be confusing to users trying to figure out which file they need to download for manual installation. You may want to add wording to explain the purpose of the file.
     • Releases can't added or modified via pull request so updates will always be the responsibility of a project collaborator's.
     • The package index file could be added to a release but this is a bit confusing because a single file contains all the versions and you don't want to change the URL with each version.

Note: Using the archive file automatically generated by Github for each commit(e.g., https://github.com/user-name/project/archive/{commit ID}.zip) as an installation archive file is not a good idea because Github may later modify the file, making the checksum in the package index file incorrect. This will cause a CRC mismatch error during installation in Boards Manager.