Jira::Sprint::Tool

The purpose of this tool is to make it easier to make adjustments to the sprints of multiple teams. See the feature files for some behavior examples.

• Principles
• Installation
• Setup
• Usage
  • Warning
  • Add Sprints
  • Adjusting The End Date Of Sprints
  • Align Time In Sprint Dates
  • List Sprints
  • List Sprint Prefixes (Teams)
  • Rename Sprints
  • Team Sprint Mapping
  • Team Ticket Sprint Dispatching
• Development
  • Install Dependencies
  • Continuous Testing While Making Changes
  • Experiment Using An Interactive Prompt
  • Install Locally
  • Release
• Contributing
• License
• Code of Conduct

Following a convention over configuration approach:

• All Scrum boards from the Jira instance are scanned to identify the ones matching the search criteria (the list is cached for a day for performance reasons to deal with Jira instances having thousands of boards);
• For each board, only the unclosed sprints are considered;
• Sprint manipulations only apply to those sprints whose names match the following format: sprint_prefix_25.4.3
• Creating new sprints will use the existing ones as a reference for the prefix and the length of the sprint.

1. Install Ruby.
2. Install the gem...

   • ... and add to the application's Gemfile by executing:

     bundle add jira-auto-tool

   • ... if bundler is not being used to manage dependencies, by executing:

     gem install jira-auto-tool

1. Create an example configuration file

   jira-auto-tool --env-setup

2. Adjust the file to your context.

The following environment variables have to be set to use this tool. Except for the JIRA_API_TOKEN that should be done via the configuration file.

Some explanations:

• JIRA_USERNAME - Your Jira account username (e.g., "user@company.com").
• JIRA_API_TOKEN - Your Jira API authentication token.
• JIRA_SITE_URL - Base URL of your Jira instance (e.g., "https://your-domain.atlassian.net").
• JIRA_BOARD_NAME - Name of the Jira board to work with (e.g., "Team Board").
• JIRA_BOARD_NAME_REGEX - Regular expression pattern to match board names (e.g., "ART 16|unconventional board name").
• JIRA_PROJECT_KEY - Key of the Jira project (e.g., "PROJ").
• JAT_TICKETS_FOR_TEAM_SPRINT_TICKET_DISPATCHER_JQL - Query to identify tickets requiring sprint dispatching (e.g., "project = PROJ AND Sprint IS EMPTY"). See Team Ticket Dispatching.
• JIRA_SPRINT_FIELD_NAME - Custom field name for Sprint (e.g., "Sprint").
• IMPLEMENTATION_TEAM_FIELD_NAME - Custom field name for storing team assignments (e.g., "Implementation Team").

Optional environment variables:

• ART_SPRINT_REGEX - Can be used to limit the sprints that are going to be manipulated (e.g., "ART-16|(4.1)"). See sprint filtering.
• JIRA_CONTEXT_PATH - Context path for Jira instance (if needed typically "/jira").
• JIRA_HTTP_DEBUG - Enable HTTP debug logging (set to "true" or "false").
• JAT_RATE_INTERVAL_IN_SECONDS - Interval for rate limiting in seconds (e.g., "1").
• JAT_RATE_LIMIT_PER_INTERVAL - Rate limit for Jira API calls (e.g., "1") See Control Jira HTTP request rate.

• Use the tool integrated help:

  jira-auto-tool --help

• Leverage the specification by examples for a detailled understand of the features.
• Note that usually the long option names have a short version equivalent to reduce typing.

1. You should familiarize yourself with this tool in a Jira sandbox project before applying it to your context. That can be done easily by creating a free Atlassian account like it has been done to document this tool features using executable specifications.

2. Remember that you are not allowed to use confidential/sensitive information when familiarizing with this tool in such a cloud sandbox. Though, if the sandbox belongs to the target context (e.g., sandbox project on the client Jira instance) you can experiment with the parameters you intend to use later.

Below are a few examples.

The following is going to add sprints sprint_prefix_25.4.3 until sprint_prefix_25.4.6 to the teams respective sprint prefixes.

jira-auto-tool --sprint-add=25.4.3,4

The following is going to adjust the end date of sprints named sprint_prefix_25.1.5 and shift the subsequent ones by adjust their start and end dates:

jira-auto-tool --sprint-update-end-date=25.1.5,"2025-02-25 16:00:00 UTC"

jira-auto-tool --sprint-align-time-in-dates="14:15 UTC"

jira-auto-tool --sprint-list

jira-auto-tool --sprint-prefix-list

jira-auto-tool --sprint-rename=25.3.5,25.4.1

jira-auto-tool --team-sprint-mapping-list

jira-auto-tool --team-sprint-mapping-dispatch-tickets

After checking out this repository.

bundle install

bundle exec guard

bin/console

To install this gem onto your local machine, run bundle exec rake install.

1. Bump the gem version:

   bundle exec rake version:bump[{major|minor|patch}]   

2. Release the version to rubygems.org:

   bundle exec rake release

   which will:
   • create a git tag for the version
   • push git commits and the created tag
   • push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/cbroult/jira-auto-tool. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Jira::Sprint::Tool project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.