There are a number of ways to get involved with Fabric:
While we may not always reply promptly, we do try to make time eventually to inspect all contributions and either incorporate them or explain why we don’t feel the change is a good fit.
Create a new Git branch specific to your change(s). For example, if you’re adding a new feature to foo the bars, do something like the following:
$ git checkout master # or the latest release branch -- see below $ git pull $ git checkout -b foo-the-bars <hack hack hack> $ git push origin HEAD <submit pull request based on your new 'foo-the-bars' branch>
This makes life much easier for maintainers if you have (or ever plan to have) additional changes in your own master branch.
Base bugfixes off the latest release branch (e.g. 1.4) and new features off of master. If you’re unsure which category your change falls in, just ask on IRC or the mailing list – it’s often a judgement call.
Make sure documentation is updated – at the very least, keep docstrings current, and if necessary, update the ReST documentation in docs/. For example, new env.* settings should be added to docs/usage/env.rst.
Add a changelog entry at the top of docs/changelog.rst following existing entries’ styles. Don’t forget to attribute yourself if you’d like credit!
Try writing some tests if possible – again, following existing tests is often easiest, and a good way to tell whether the feature you’re modifying is easily testable.
Use hub pull-request when writing a patch for a pre-existing Github Issue. This isn’t an absolute requirement, but makes the maintainers’ lives much easier! Specifically: install hub and then run hub pull-request to turn the issue into a pull request containing your code.
Fabric tries hard to honor PEP-8, especially (but not limited to!) the following:
If a ticket-tracker ticket exists for a given issue, please keep all communication in that ticket’s comments – for example, when submitting patches via Github, it’s easier for us if you leave a note in the ticket instead of sending a Github pull request.
The core devs receive emails for just about any ticket-tracker activity, so additional notices via Github or other means only serve to slow things down.
While Fabric’s development methodology isn’t set in stone yet, the following items detail how we currently organize the Git repository and expect to perform merges and so forth. This will be chiefly of interest to those who wish to follow a specific Git branch instead of released versions, or to any contributors.
Fabric tries to follow open-source standards and conventions in its release tagging, including typical version numbers such as 2.0, 1.2.5, or 1.2b1. Each release will be marked as a tag in the Git repositories, and are broken down as follows:
Major releases update the first number, e.g. going from 0.9 to 1.0, and indicate that the software has reached some very large milestone.
For example, the 1.0 release signified a commitment to a medium to long term API and some significant backwards incompatible (compared to the 0.9 series) features. Version 2.0 might indicate a rewrite using a new underlying network technology or an overhaul to be more object-oriented.
Major releases will often be backwards-incompatible with the previous line of development, though this is not a requirement, just a usual happenstance. Users should expect to have to make at least some changes to their fabfiles when switching between major versions.
Minor releases, such as moving from 1.0 to 1.1, typically mean that one or more new, large features has been added. They are also sometimes used to mark off the fact that a lot of bug fixes or small feature modifications have occurred since the previous minor release. (And, naturally, some of them will involve both at the same time.)
These releases are guaranteed to be backwards-compatible with all other releases containing the same major version number, so a fabfile that works with 1.0 should also work fine with 1.1 or even 1.9.
The third and final part of version numbers, such as the ‘3’ in 1.0.3, generally indicate a release containing one or more bugfixes, although minor feature modifications may (rarely) occur.
This third number is sometimes omitted for the first major or minor release in a series, e.g. 1.2 or 2.0, and in these cases it can be considered an implicit zero (e.g. 2.0.0).
The 0.9 series of development included more significant feature work than is typically found in tertiary releases; from 1.0 onwards a more traditional approach, as per the above, is used.
Major and minor releases do not mark the end of the previous line or lines of development:
We hope that this policy will allow us to have a rapid minor release cycle (and thus keep new features coming out frequently) without causing users to feel too much pressure to upgrade right away. At the same time, the backwards compatibility guarantee means that users should still feel comfortable upgrading to the next minor release in order to stay within this sliding support window.