Flux

Flux is a command-line tool that tries to eliminate the drudgery from your workflow.

It provides hooks for interacting with the following:

  • Tracker (currently only Pivotal Tracker is supported)
  • RCS (currently, git only)
  • Anything else you can think of, as long as someone implements it.

Some examples

Let's list all stories that have been scheduled (i.e., moved out of the icebox and into some iteration):

$ flux stories
ID        STATE      ASSIGNEE    STORY
12345678  unstarted              A developer can grab a story
12345679  finished   David Leal  A developer can link a branch to a story
12345680  finished   David Leal  A developer can mark a story as started
...

[TODO Complete workflow. For now try flux to see a list of implemented tasks.]

Configuration

A project is configured by placing a file named .flux in the project root. Each top level key represents a functional domain.

This project's .flux file is as follows:

trackers:
  adapter: pivotal_tracker
  project_id: 128808
rcs:
  adapter: git
workflows:
  adapter: mojotech

Local configuration

The .flux file should be used for project-wide configuration and kept under version control. Obviously you aren't going to store your account credentials there, so you need a different place where you can store them. That place is .flux.local. If you're using Git (and really, why wouldn't you?), this file should be added to the project's .gitignore.

Here's an example of a .flux.local file.

trackers:
  token: abcdef1234567890
  email: [email protected]

Note for Pivotal Tracker: Your API token is at https://www.pivotaltracker.com/profile

Code Reviews Workflow

start your feature on a branch

$ git checkout feature-branch

code your feature

$ git commit # rinse, repeat

make sure your code to review is available

$ git push

request a review

$ flux branches:review feature-branch [ --parent master ]

Note: currently, you must explicitly list your feature branch name

This feature branch name will be used to keep track of multiple rounds

of the review.

flux will generate a pull request and print its URL

Github takes sends out notices.

other devs review and comment

You fix up your commits.

$ git rebase -i origin/master

I'm in your branch... rewriting your history.

Time to resubmit for review

$ git push $ flux request-review feature-branch [ --parent master ] [ --close ]

flux closes old review request for feature-branch (optionally)

flux opens a new review request for feature-branch

The process repeats.

Now the reviewers want to see if you addressed their concerns.

They run:

$ flux branches:all_reviews

(TODO: should be able to limit this report to one feature branch)

They see: the most recent review request for each branch, but also links

to the diffs between each previous review request for that branch.

So, instead of repeating the entire review, they can look at just the "inter-diff"