Refactor build script and add release docs

- Fixed the build script to more correctly prune unneeded content (like
  bootloader code) from the built arduino packages.
- Changed checkout directory name to `bundle-build-checkout` for clarity in `bin/build-arduino-package`
- Replaced `chdir` with `set_cwd` function for better readability and maintenance in `bin/build-arduino-package`
- Created `docs/maintainer/release-engineering.md` documenting the release process for Kaleidoscope

bin/build-arduino-package

@@ -114,44 +114,43 @@ if ( $version eq '' && $tag =~ /^v(\d.*)$/ ) {
     $version = $1;
 }
 
-my $checkout_dir = 'kaleidoscope-checkout';
+my $checkout_dir = 'bundle-build-checkout';
 
 my $build_base_url = $package_repo . "/raw/$main_branch_name/builds";
 $build_base_url =~ s|ssh://git@|https://|;
 
 print "Working directory: $working_dir\n";
-chdir($working_dir);
+set_cwd($working_dir);
 
 clone_repos( $tag, $gd32_tag, $bundle_repo, $gd32_core_repo, $checkout_dir, $package_repo );
 
-chdir( $working_dir . "/" . $checkout_dir );
+set_cwd( $working_dir . "/" . $checkout_dir );
 if ($only_latest_platform) {
+	print "Removing old builds from $builds_dir\n";
     `rm -rf $builds_dir/*`;
 }
 
 foreach my $arch (@ARCHES) {
+    my $release_dir = "Kaleidoscope-$arch-$version";
+    my $filename    = $release_dir . ".tar.bz2";
 
 
     # Get the specified Kaleidoscope build and all its plugins as libraries
     # into the checkout
     checkout_kaleidoscope($kaleidoscope_tag, "$working_dir/$checkout_dir/$arch/libraries/Kaleidoscope");
-    chdir("$working_dir/$checkout_dir/$arch/libraries/Kaleidoscope");
+    set_cwd("$working_dir/$checkout_dir");
     remove_unneeded_files($arch);
+    set_cwd("$working_dir/$checkout_dir/$arch/libraries/Kaleidoscope");
     lift_plugins_to_arduino_libs();
     set_plugin_versions( $working_dir, $checkout_dir, $arch, $version );
-
-    chdir($working_dir);
-
-    my $release_dir = "Kaleidoscope-$arch-$version";
-    my $filename    = $release_dir . ".tar.bz2";
-
+    set_cwd($working_dir);
     build_archive( $arch, $checkout_dir, $release_dir, $filename );
     deploy_build( $builds_dir, $filename );
 
 }
 
 update_index_file( $output_dir, $index_filename );
-chdir("$output_dir");
+set_cwd("$output_dir");
 commit_results($index_filename);
 finalize_action($push_package_repo);
 
@@ -162,7 +161,7 @@ sub set_plugin_versions {
     my $checkout_dir = shift;
     my $arch         = shift;
     my $version      = shift;
-    chdir("$working_dir/$checkout_dir/$arch/libraries");
+    set_cwd("$working_dir/$checkout_dir/$arch/libraries");
     `perl -pi -e's/version=0.0.0/version=$version/' */library.properties`;
 }
 
@@ -173,22 +172,25 @@ sub clone_repos {
     my $gd32_repo = shift;
     my $checkout_dir = shift;
     my $package_repo  = shift;
+    print "Checking out AVR cores to $checkout_dir\n";
 `git clone --depth=1 --quiet --recurse-submodules --branch $tag $bundle_repo $checkout_dir`;
 
+print "Checking out GD32 core to $checkout_dir/gd32\n";
 `git clone --depth=1 --quiet --recurse-submodules --branch $gd32_tag $gd32_repo $checkout_dir/gd32`;
     `git clone $package_repo $output_dir`;
 }
 
 sub checkout_kaleidoscope {
     my $tag = shift;
     my $checkout_dir = shift;
+    print "Checking out Kaleidoscope to $checkout_dir\n";
     `git clone --depth=1 --quiet --recurse-submodules --branch $tag $kaleidoscope_repo $checkout_dir`;
 }
 
 sub lift_plugins_to_arduino_libs {
     if ( -d 'plugins' ) {
-        chdir("plugins");
-
+        set_cwd("plugins");
+	print "Lifting plugins from ".`pwd`." to ../../\n";
         # move the plugins to be fullfledged arduino libraries
         `mv * ../../`;
     }
@@ -269,7 +271,7 @@ sub build_archive {
     `mv $checkout_dir/$arch $checkout_dir/$release_dir`;
     ;    # A hack to get consistent naming with the old setup
     `find "$checkout_dir/$release_dir" -name .git |xargs rm -rf`;
-    `tar cjvf $filename -C $checkout_dir/ $release_dir `;
+    `tar cjf $filename -C $checkout_dir/ $release_dir `;
 
     my $sha256 = `sha256sum $filename | cut -d' ' -f 1 `;
     chomp($sha256);
@@ -295,3 +297,9 @@ sub finalize_action {
     }
 
 }
+
+sub set_cwd {
+	my $dir = shift;
+	print "cd $dir\n";
+	chdir($dir);
+}

docs/maintainer/release-engineering.md

@@ -0,0 +1,40 @@
+# Building a numbered release of Kaleidoscope for Arduino
+
+1. Tag the release in the Kaleidoscope repo
+
+```git tag -s v1.99.9```
+
+
+```git push --tags```
+
+
+2. Tag the GD32 Arduino core
+```
+git clone https://github.com/keyboardio/ArduinoCore-GD32-Keyboardio
+cd ArduinoCore-GD32-Keyboardio
+git tag -s v1.99.9
+git push --tags
+```
+
+3. Tag the AVR and Virtual Arduino cores
+
+```
+git clone https://github.com/keyboardio/Kaleidoscope-Bundle-Keyboardio
+cd Kaleidoscope-Bundle-Keyboardio
+git tag -s v1.99.9
+git push --tags
+```
+
+
+4. Build the package
+
+Back inside a Kaleidoscope master checkout
+```perl bin/build-arduino-package --kaleidoscope-tag=v1.99.9 --bundle-tag=v1.99.9 --arch-gd32-tag=v1.99.9```
+
+This will check out fresh copies of all three repositories and their submodules, build arduino board index files, and package everything up. It will then tell you you need to verify the contents of the repo with a message like 
+
+"Now, you need to cd to /var/folders/80/n7lx0k152rd38svj1q8gsqvm0000gn/T/dri7ffIdp8/boards_manager_repo check the content and push it"
+
+Compare the new release to the previous release. At the very least, look over the size of the built packages to make sure it's not unexpectedly larger or smaller and that the updated index files look like they have the correct form and content.
+
+If everything looks good, it's time to push the boards_manager_repo changes to github, which will make the new release available.