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/beta1 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.
- Fabric 2 is now public: it’s the
v2branch of the
- 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
- download a tag’s archive from Github’s releases page.
- install from git and use the
- The v2 branch can optionally be installed as
fabric2if 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:
- 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
fabric2, again as per the upgrade doc.
v2branch will be renamed to
master(or maybe something a bit less sinister sounding.)
- The old
masterwill be renamed something like
v1(or possibly just the latest stable release branch, e.g.
www.fabfile.orgwill become updated for 2.0 (i.e. the contents of
v2branch will become deployed to the live site.)
- 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.
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.
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 threshold2 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.
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
4100SLOC of tests (not counting non-Python fixtures);
- Fabric 2 by itself is
2000SLOC of tests;
- Invoke, which Fabric 2 heavily relies upon, is
5400SLOC of tests;
- Thus, “Fabric 2” as a complete unit (ignoring Paramiko, since it’s used by
Fabric 1 too) consists of
3500SLOC of active code, tested by
7400SLOC 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
- 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.