Testing Branches (Why and How To)

[zeffii]

Each new official Blender release means someone should be testing if the addon still works as expected. API changes in Blender's Python interface are a fact of life, and usually mean we can write less complicated code to achieve some functionality. In practice this means that functions sometimes get renamed or removed. If BioBlender happens to use one of those functions it will fail in the latest Blender until we rectify the lines of code involved. These changes are usually easy to follow and fix.

My intention is to get BioBlender working in the latest official Blender Release (which is at the time of this post , 2.73a ). To confirm that features work it is vital that the various branches are tested by people who will notice if something isn't behaving as intended.

Not everyone using the addon is a programmer or knows how GIT and the concept of 'version control` works and there are some standard questions to get out of the way.

Q: What is a branch? A: It's a version of this software with sometimes small differences in code, and other times big differences. Usually the end-user won't notice any difference, or if they do it should be a positive change. None of the content inside the branches affects the master, so it's a safe place to explore ideas. If stuff gets broken in a branch it is easy to revert and continue from a less broken state.

At present these branches are listed in the dropdown:

You see the current branch being viewed is ticked, it is master. Eventually the code changes/ experiments done in branches will be pulled into master, and then the branches have served their purpose and can be deleted.

Testing a branch

first
Because my intention is to make the addon 273 compatible, it is a prerequisite. Either get an official release from Blender.org or download a cutting edge nightly build from https://builder.blender.org/download/

then
This can be done several ways, the least imposing of which tends to be the most labour intensive in the long run. Whereas the easiest in the long run takes a little more brain-effort at the beginning, after which it is supremely convenient.

[zeffii]

Method 1 ( Using the zip )

In GitHub switch to the branch you want to try by clicking the dropdown, and picking a branch. After selecting the branch the dropdown will change to something like

The download becomes a different file after switching branches. You may see something like: Saving to disk would then save that version of the addon. From that point you may want to make a local copy of the BioBlender addon folder (just in case). Exit Blender if it's running. Then you could delete the content of the BioBlender folder (not the folder itself), Proceed to drag in or paste the content from the recently downloaded zip. The next time you start Blender it will be loading the 2.73 version.

[zeffii]

This description is a work in progress.

Method 2 ( using GitHub Desktop client)

Of the following steps only the last one is repeated any time you want to switch / synchronize a branch for testing.

Step 1: Install a git Client

• Download and install the GitHub desktop application for windows , mac is available too.
• it will ask you to sign in with GitHub username + password.

Step 2: make the repository local

• With the installation complete, point your browser at https://github.com/MonZop/BioBlender/
• Press The Clone in Desktop button, it will open the GitHub desktop Application and ask where to download the files to. (personally I have it in a GitHub directory inside Documents (full path C:\Users\dealga\Documents\GitHub)
• This downloads the repository into the chosen directory. making C:\Users\dealga\Documents\GitHub\BioBlender

Here comes what I think might be the conceptual hurdle, which I would like to introduce by means of an analogy. A satellite beams information from one location to another, we as users of the technology don't need to know where the signal came from originally, all we need to worry about is pointing our receiver dish in the right direction. Similarly, Blender doesn't need to know where the addon files are as long as the addons folder has a symbolic link to the files.

Step 3: symbolic link between addon folder and repository

The next step is to tell Blender where to find the addon. To show this I will use my system as an example of what the paths might look like:

# my local BioBlender2 GitHub folder is located in
C:\Users\dealga\Documents\GitHub\BioBlender

# my local Blender installation is at
C:\blender_trunk\blender.exe

# further version specific directories are:
C:\blender_trunk\2.73
C:\blender_trunk\2.73\scripts\addons     or    \addons_contrib

• delete the BioBlender folder from C:\blender_trunk\2.73\scripts\addons_contrib

• then open a cmd terminal at C:\blender_trunk\2.73\scripts\addons_contrib and type:

  mklink /j BioBlender C:\Users\dealga\Documents\GitHub\BioBlender

  

  this makes a folder called BioBlender in ..\scripts\addons_contrib, the content of which is located in the GitHub\BioBlender folder. This is a symbolic link. A proxy, a satellite.

If this was successful the operating system will say 'succesfully created junction between x and y ` In Windows Explorer such linked folder has a slightly different icon. Mine looks like:

Step 4: Pick a Branch

With GitHub Desktop App open, select the BioBlender addon and click

To check for changes you can press the Sync in the top right of the GitHub app, if changes have been made to that Branch you will see a number with an arrow up or down,

this reflects the amount of commits that must be synced.

[zeffii]

people can be pointed to this issue if they need help testing branches

[zeffii]

on windows scripts / add-ons can be stored in 2 main areas

[1] C:\Program Files\Blender Foundation\Blender\2.73\scripts\addons\BioBlender
[2] C:\Users\Username\AppData\Roaming\Blender Foundation\Blender\2.73\scripts\addons\BioBlender

remember that the current master on github is something you can revert back to easily if everything fails. I propose that for convenience you:

with Blender closed

• delete BioBlender from [1]. (And any branches you may have dragged in)
• delete all branches you may have installed in [2] (perhaps BioBlender-master-first-fixes, ..etc. except BioBlender-master-mff-experiments. Also delete the BioBlender folder. The only mention remaining of BioBlender inside addons would then be BioBlender-master-mff-experiments.
• rename BioBlender-master-mff-experiments to BioBlender.

with Blender open

• go to user preferences / addons and untick any BioBlender (or Branches)
• Save User Settings
• hit Refresh.
• Close and re open Blender
• enable the BioBlender addon.
• Save User Settings.

[zeffii]

Once the GIT repository is set up correctly all you need to test different branches is (literally)

• open the GitHub desktop application
• make sure it's viewing the BioBlender repo (a one button click)
• select which Branch (also one button click)
  • selecting different branches changes the files in the BioBlender directory in-situ (in-place?)

I will make a diagram / graphic to show this better. It's so simple, but difficult to describe in words

[zeffii]

[MonZop]

Thanks Zeffii, I get the concept. I will try to make it work as soon as I get back to Pisa. Until now, I have adopted the 'superficially easier' option of downloading the branch, and installing every time. But in the long run, it sounds better to learn to use GitHub. It should not be beyond my (limited) capabilities !

[zeffii]

I have no doubt that you can.