README.md in pivotoolz-0.1.3 vs README.md in pivotoolz-0.2.0

- old
+ new

@@ -25,10 +25,27 @@ Or install it yourself as: $ gem install pivotoolz +To take full advantage of the tools, ensure you have the following +environment variables set: +```bash +PIVOTAL_TRACKER_API_TOKEN # Get this from your pivotal tracker account profile page +SLACK_WEBHOOK_URL # Get this by creating a new Incoming Webhook integration in Slack +``` + +Set the environment variables by either adding them to your `.bashrc` file +or exporting them prior to usage: +Set the environment variables by exporting them with the following commands: +`export PIVOTAL_TRACKER_API_TOKEN=YOUR_TOKEN` +`export SLACK_WEBHOOK_URL=YOUR_WEBHOOK_URL` + +Alternatively, you can simply add those export statements to your `.bashrc` file +so that you won't have to keep typing it every time you want to use +`post-slack-message` or `deliver-deployed-stories` and their ilk. + ## Usage Pivotoolz is a collection of tiny programs that can be used individually or composed together for more powerful features. The manner of usage of each is described below: @@ -37,62 +54,107 @@ Deliver all stories that have been deployed to the given environment since the previous and last deployment. Example: -`bundle exec deliver-deployed-stories ENVIRONMENT` +`deliver-deployed-stories ENVIRONMENT` Where `ENVIRONMENT` is the environment you consider to be where stories can be accepted/rejected. Example: Let's say we have an `acceptance` environment where we deploy our app to test out stories. As long as we label our deployed git SHAs with tags (using `tag-it`), we can automatically deliver any finished stories that went out in the last deployment by simply running the command: -`bundle exec deliver-deployed-stories acceptance` +`deliver-deployed-stories acceptance` +Add the command to your deployment process to have your stories automatically delivered +on a successful deployment. + +![usage](assets/deliver-deployed-stories-demo.gif) + ### `deliver-story` Deliver a given story provided in JSON format. The minimum JSON attributes required are `id` and `current_state` Typically used with output from `get-story-info-from-id` piped in. Example: -`bundle exec get-story-info-from-id STORY_ID | bundle exec deliver-story` +`get-story-info-from-id STORY_ID | deliver-story` OR -`bundle exec deliver-story '{"id": 123, "current_state": "finished"}'` +`deliver-story '{"id": 123, "current_state": "finished"}'` If `current_state` is not `finished`, the story will not be delivered. -### `stories-deployed` +### `story-ids-deployed` -Returns a list of all stories deployed to a given environment. +Returns a newline delimited list of all story ids deployed +to the given environment. -Output is of the form: +Example: +``` +story-ids-deployed production -STORY_TITLE: -LINK_TO_STORY +# Output: +123 +456 -STORY_TITLE: -LINK_TO_STORY +``` + + +### `merge` + +Tired of running multiple commands to merge your branch when all you +really want to do is 'just merge' your branch? Now you can! +Just run `merge TARGET_BRANCH` where target branch is the branch +you want to merge into. The `merge` program takes care of rebasing the +latest local and upstream changes from target branch into your branch, +pushing your rebased branch, and then merging with the `--no-ff` flag. +Life is short, the time saved adds up real fast! + Example: +When in a branch you want to merge, just run +`merge master` to merge it into the `master` branch. You will end up +with a clean git history and all commits in your branch will be bundled +nicely under a top-level merge commit. + +![usage](assets/merge-demo.gif) + +### `tag-it` + +Tag the current git HEAD with a given tag (usually environment you're about to deploy to). + +Example: +`tag-it production` - Will tag the current git HEAD with `production/TIMESTAMP` + +![usage](assets/tag-it-demo.gif) + +### `stories-deployed` + +If you use `tag-it` to label your git SHAs for deployment, this will return a list +of all stories deployed between the previous and last deployments using the tags to +scan a commit range. + +Example: ``` -bundle exec stories-deployed production +stories-deployed production # You may need to prepend bundle exec depending on your setup # Output: Update README: https://www.pivotaltracker.com/story/show/123 Update dependencies https://www.pivotaltracker.com/story/show/456 ``` +![usage](assets/stories-deployed-demo.gif) + Use with `post-slack-message` to post a message in a slack deployment channel with the list of stories that just got deployed. ### `post-slack-message` @@ -100,31 +162,46 @@ a webhook integration](https://api.slack.com/incoming-webhooks) on slack first. Once you have done so, copy your Webhook URL into an environment variable `SLACK_WEBHOOK_URL`. If the `SLACK_WEBHOOK_URL` has been defined correctly, you will be able to post a message in slack to any channel as follows: -`bundle exec post-slack-message CHANNEL "MESSAGE_TEXT"` +```bash +post-slack-message CHANNEL "MESSAGE_TEXT" +``` Where CHANNEL is of the form "#channel" or "@user". You can also pipe a message to the `post-slack-message` program. For example: -`{ echo Stories deployed to production:; bundle exec stories-deployed production; } | bundle exec post-slack-message '#production-deploys'` +```bash +{ echo Stories deployed to production:; stories-deployed production; } | post-slack-message '#production-deploys' +``` -### `story-ids-deployed` +`post-slack-message` can be helpful if you just want to have fun trolling your co-workers too. -Returns a newline delimited list of all story ids deployed -to the given environment. +![usage](assets/post-slack-message-demo.gif) +### `pv-git-branch` + +Wouldn't it be nice to have all your Git branch names consistent with your dev team? Well now +you can with `pv-git-branch`. Just pass `pv-git-branch` a Pivotal Story ID, and it will return +branch name for you based on author name, the pivital story category, the pivotal story +name and the pivotal story id. Be sure to set your `PIVOTAL_TRACKER_API_TOKEN` env variable is +exported in your `.bashrc` file. If you want to explicitly set your initials as the author name, +set your git config user initials like this: `git config --add user.initials af`. Otherwise it +will take your `git config user.name` or `whoami` information. + Example: +```bash +pv-git-branch 111222333 ``` -bundle exec story-ids-deployed production +This would return something like: `af/features/building-someting-greate-111222333` -# Output: -123 -456 - +So it can be used with git like this: +```bashr +git checkout -b $(pv-git-branch 111222333) ``` +![usage](assets/pv-git-branch-demo.gif) ## Development After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.