allocpool is undocumented and written in Perl

[aspiers]

allocpool is a small but critical part of our CI. It would be helpful if it was documented and also written in a language which doesn't violate our policy. This is increasingly important as new people join the team who have been hired as Python/Ruby/shell hackers, not Perl hackers.

[aspiers]

The reason I mention this is that I just wasted several hours trying to freeze an mkcloud environment created by Jenkins. Each time it got reclaimed by another Jenkins job shortly after finishing. My previous understanding was that this was controlled by /root/allocations, but apparently that's not the case. After staring at this code for 20-30 mins I figured out it's actually controlled by /root/pool (I think).

The fact that I struggled with this during a time when most people are on FTO is one good example of why documentation is important.

BTW there's actually quite a lot of cryptic code in this area, e.g.

mkcloudwrapper="${automationrepo}/scripts/mkcloudhost/allocpool ${automationrepo}/scripts/mkcloudhost/mkcloude"

So Jenkins calls an undocumented wrapper around an undocumented wrapper around mkcloud. Even without docs it could be made a lot easier to understand with a tiny amount of effort in choosing clear names, like alloc-pool-worker-cloud and set-cloud-env-vars. And why do we have routed.cloud and runtestn? Two cryptic and totally different names for doing basically the same thing.