The Fabric 2 alpha/beta is here!

Opening remarks

This has been a hard blog post to write; not in a technical sense (though blogging always is - it’s why I don’t do more of it!) but simply because Fabric 2 has been “coming soon” for what feels like ages, and putting it out in the open turns out to involve a lot of emotions.

But here we are: Fabric 2 is no longer private!

I don’t want to bury the lede, so here are some important links:

• The updated Fabric roadmap (this & the rest of the updated WWW site will be published when 2.0.0 goes final.)
• An overview of why you might want to upgrade, with a juicy list of already-implemented new features.
• Details on what upgrading means and how it works.
• The rest of the v2 branch’s doc site.
• Finally, the v2 source code.

Read on for details.

The alpha/beta/release process

At a high level: I’m putting Fabric 2 out as an alpha/beta¹ now, and intend to gather general feedback about its approach & APIs to help pin down how much (if any) backwards incompatible work is truly needed before an official 2.0.0 release. Which I’m hoping will be by, during or shortly after PyCon US in a month’s time.

To make the process clearer, let’s break it down real quick.

Right now

• Fabric 2 is now public: it’s the v2 branch of the fabric/fabric repo.
• It’s not on PyPI yet; no 2.x releases exist at time of writing. To obtain Fabric 2, you’ll need to do one of:
  • install from git and use the v2 branch;
  • download a tag’s archive from Github’s releases page.
• The v2 branch can optionally be installed as fabric2 if one wants to use it alongside Fabric 1 for an easier upgrade; details in the upgrade doc.
• Expect missing features vs Fabric 1 - think tech preview, not drop-in replacement. (This is the ‘alpha’ in ‘alpha/beta’.)

Between now and release

• You can:
  • leave feedback as outlined below;
  • check the git commit list or Invoke’s changelog for ongoing changes;
  • git pull or look for new tag downloads
• I will:
  • figure out exactly which outstanding issues should be resolved before we can cut 2.0.0;
  • hack on those issues (and/or ask for specific help with them);
  • do a bunch of ticket cleanup.

At release (2.0)

• 2.0 will likely still lack feature parity compared to v1 (though it already has new features not present in v1)
• Its APIs will be considered stable (until 3.x, see below).
• It will be made available on PyPI as both fabric and fabric2, again as per the upgrade doc.
• The v2 branch will be renamed to master (or maybe something a bit less sinister sounding.)
• The old master will be renamed something like 1.x or v1 (or possibly just the latest stable release branch, e.g. 1.14.)
• www.fabfile.org will become updated for 2.0 (i.e. the contents of sites/www in the v2 branch will become deployed to the live site.)

Beyond 2.0

• Additional feature releases (2.1, 2.2, etc) will be put out to continually shrink the feature gap with v1, add brand new features, and so forth.
• When necessary, we will make 3.x, 4.x releases when backwards incompatibility is desired (driven either by Fabric’s own needs, or in order to declare compatibility with similar backwards-incompatible Paramiko or Invoke releases.)

How to leave feedback

I’d strongly prefer to limit the number of avenues used for concrete alpha/beta feedback, so please use either Github ticket comments or IRC to report missing features or issues with existing ones in the 2.0 codebase. Please don’t tweet at me, email me, or make new issues or PRs (I’ll be asking for new issues/PRs when I think they’re necessary!)

Ticket comments (no new tickets please)

To limit the number of notifications in my poor inbox, I’m planning to corral initial alpha/beta feedback into a single meta-ticket: fabric/fabric#1591.

IRC chat

Github comments are preferred as they’re more permanent and more visible, but if (for example) you’re unsure if feedback is useful, feel free to bounce it off me at irc.freenode.net/#fabric. I may not be active constantly, but I plan to check in more often than I have recently.

Ticket bankruptcy

During this period, one of my TODO items is to do a serious cleanup of the issue trackers (especially Fabric’s). Such a task is needed even for projects not undergoing a transition, but a 2.0 is an exceptionally good time for it.

Basically, I’ll be closing most tickets older than some arbitrary threshold² which lack involvement by myself or my ’lieutenants’. This doesn’t mean that they are closed forever - just comment with a reason why the issue is still outstanding and I’ll definitely consider reopening it.

The intent is to close out no-longer-applicable issues, and a date-based mass-close plus occasional reopening is significantly easier than judging every single open ticket on its own.

Self-indulgent numberwank

As a wrap-up (this is not required reading!), here are some mildly interesting numbers around repository size and test coverage:

• Fabric 1, at time of writing, is 3200 SLOC³, with 4100 SLOC of tests (not counting non-Python fixtures);
• Fabric 2 by itself is 800 SLOC with 2000 SLOC of tests;
• Invoke, which Fabric 2 heavily relies upon, is 2700 SLOC with 5400 SLOC of tests;
• Thus, “Fabric 2” as a complete unit (ignoring Paramiko, since it’s used by Fabric 1 too) consists of 3500 SLOC of active code, tested by 7400 SLOC of unit and integration tests.

As Fabric 2 both lacks functionality present in Fabric 1 and includes functionality not present in Fabric 1, it’s hard to judge this as a direct comparison – though the increase in test code isn’t an accident.

Fabric 1 never grew test coverage in its management tools, but I coaxed some out just now:

• Fabric 1’s test coverage is 74%, and its full test suite (unit + integration) takes 4m10s (!) to run while recording coverage.
• Invoke’s test coverage is 95%, and its coverage-oriented test run takes only 8s.
  • Its regular, no-coverage, unit tests take 4.9s, and I’ve honestly let it slip lately - it’s usually quicker.
• Fabric 2 (by itself; not factoring in the Invoke package) is 97% covered, and its full suite under coverage takes 14s to run.
  • Unit tests by themselves are only 4.1s (at the moment.)
  • As you might imagine, network-borne integration tests - even when the network is loopback - can be pretty slow. In this case they consist of far less code and yet take a full ~10s!

It’s a nice example of what test-oriented code organization (and, to be fair, a greater emphasis on mocking) can do - a significantly increased amount of coverage, in only a fraction of the time.