gojira

package module
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 5, 2024 License: MIT Imports: 9 Imported by: 0

README

GoJira

Build Status Go Report Card CodeClimate Docs LOC License

This module contains code to access Jira, parsing both the JSON API via github.com/andygrunwald/go-jira in jirarest and code to parse a Jira XML file in jiraxml.

Various aggregate staticstics and reports are calculated/generated.

URL Formats

Accessing a list of issues by JQL is avialable via the UI and API:

  • UI: https://{jira_host}/issues/?jql=
  • API: https://{jira_host}/rest/api/2/search?jql=
REST API Authentication: Basic Auth

The API auth can be provided by Basic Auth using an personsal API Token.

Note on Hours Per Day and Days Per Week

This module supports custom hoursPerDay and daysPerWeek settings per Jira.

This is described here and set in the UI via the screenshot below,

Ref: https://community.atlassian.com/t5/Jira-Software-questions/What-it-JIRA-counting-as-a-quot-day-quot-in-Time-Tracking/qaq-p/1703409

Also of note is that the hours per day can be set to a decimal value, such as 8.5, but the UI may not show it:

Ref: https://community.atlassian.com/t5/Jira-questions/change-quot-Working-hours-per-day-quot-by-a-decimal-value/qaq-p/583095

Additional Discussion on Jira XML

General Discussion

General discussion including using Jira XML to:

  1. export comments and issue link types
  2. create CSV for flexible reporting and import

Ref: https://community.atlassian.com/t5/Jira-questions/JIRA-Issue-XML-Export-What-is-it-good-for/qaq-p/603308

Global Config

Working Hours Per Day and Working Days Per Week are global values and cannot be set on a per-project basis.

Ref: https://community.atlassian.com/t5/Jira-Software-questions/Time-Tracking-Hours-Is-it-still-a-global-change/qaq-p/1337399

JQL Examples

Goal Example
Query by key key = ABC-123
Query by parent parent = ABC-123
Query by linked issue issue in linkedIssues (ABC-123)
Query by reporter reporter = "foo@bar.com"

https://community.atlassian.com/t5/Jira-questions/How-to-search-all-linked-issues-with-issues-from-specific/qaq-p/1027269

Backlog

Downloading the project backlog view appears to be challenging. Here is some info on attempts to do this.

Roughly:

project = <project_name> AND resolution = Unresolved AND status!=Closed AND (Sprint not in openSprints() OR Sprint is EMPTY) AND type not in (Epic, Sub-Task) ORDER BY Rank ASC

Agile Life Cycle Stages

Stage is a common way to understand the stages of development given that many companies can use different statuses and workflows.

Stage the following stages (from Asana) and will provide a grouping capability for implementation-specific workflows into these standard meta statuses for consistent and canonical understanding of the process.

Not all the stages need to be used, however, the stages that are used can be understood in a canonical way.

image courtesy of Asana

An alternate, but related agile methodology is avialable from eSparkBiz:

image courtesy of eSparkBiz

As well as from BISS:

image courtesy of BISS

This is described as "The 5 Stages of the Agile Software Development Lifecycle" by Mendix.

image courtesy of Mendix

Documentation

Index

Constants

View Source 
const (
	FieldFilter  = "filter"
	FieldIssue   = "issue" // issue keys
	FieldKey     = "key"
	FieldParent  = "parent"
	FieldProject = "project" // project keys
	FieldStatus  = "status"
	FieldType    = "type"

	FieldIssuePlural = "issues"

	// Statuses: https://support.atlassian.com/jira-cloud-administration/docs/what-are-issue-statuses-priorities-and-resolutions/
	StatusOpen        = "Open"
	StatusInProgress  = "In Progress"
	StatusDone        = "Done"
	StatusToDo        = "To Do"
	StatusInReview    = "In Review"
	StatusUnderReview = "Under review"
	StatusApproved    = "Approved" // Done

	TypeIssue           = "Issue"
	TypeIssuePlural     = "Issues"
	TypeBug             = "Bug"
	TypeBugPlural       = "Bugs"
	TypeEpic            = "Epic"
	TypeEpicPlural      = "Epics"
	TypeSpike           = "Spike"
	TypeSpikePlural     = "Spikes"
	TypeStory           = "Story"
	TypeStoryPlural     = "Stories"
	TypeInitiative      = "Initiative"
	TypeInitiativePlura = "Initiatives"

	StagePlanning    = "Planning"
	StageDesign      = "Design"
	StageDevelopment = "Development"
	StageTesting     = "Testing"
	StageDeployment  = "Deployment"
	StageReview      = "Review"

	MetaStageReadyForPlanning    = metaStagePrefixReadyFor + StagePlanning
	MetaStageInPlanning          = metaStagePrefixIn + StagePlanning
	MetaStageReadyForDesign      = metaStagePrefixReadyFor + StageDesign
	MetaStageInDesign            = metaStagePrefixIn + StageDesign
	MetaStageReadyForDevelopment = metaStagePrefixReadyFor + StageDevelopment
	MetaStageInDevelopment       = metaStagePrefixIn + StageDevelopment
	MetaStageReadyForTesting     = metaStagePrefixReadyFor + StageTesting
	MetaStageInTesting           = metaStagePrefixIn + StageTesting
	MetaStageReadyForDeployment  = metaStagePrefixReadyFor + StageDeployment
	MetaStageInDeployment        = metaStagePrefixIn + StageDeployment
	MetaStageReadyForReview      = metaStagePrefixReadyFor + StageReview
	MetaStageInReview            = metaStagePrefixIn + StageReview
	MetaStageDone                = StatusDone

	WorkingHoursPerDayDefault float32 = 8.0
	WorkingDaysPerWeekDefault float32 = 5.0

	JiraXMLGenerated = time.UnixDate // "Fri Jul 28 01:07:16 UTC 2023"

	JQLMaxResults = 100
	JQLMaxLength  = 6000 // https://jira.atlassian.com/browse/JRASERVER-41005
	JQLInSep      = ","
)

Variables

This section is empty.

Functions

func DefaultStatusesMapSlice added in v0.12.0 

func DefaultStatusesMapSlice() map[string][]string

func IsMetaStage added in v0.14.0 

func IsMetaStage(status string) bool

func JQLStringsSimple added in v0.10.0 

func JQLStringsSimple(field string, exclude bool, vals []string, jqlMaxLength uint) []string

JQLStringsSimple provides a set of JQLs for a single field and values. The purpose of this function is to split very long lists of values so that each JQL is under a certain length limit.

func MetaStageOrder added in v0.14.0 

func MetaStageOrder() []string

func StatusesInactive added in v0.10.0 

func StatusesInactive() []string

func TimeRemaining 

func TimeRemaining(status string, timeOriginalEstimate, timeEstimate, timeSpent int) (timeRemainingOriginal, timeRemaining int)

TimeRemaining returns calculated timeRemainingOriginal and timeRemaiing and against the timeOriginalEstimate and timeEstimate respectively.

Types

type Config 

type Config struct {
	ServerURL          string
	WorkingHoursPerDay float32
	WorkingDaysPerWeek float32
	StatusesSet        *StatusesSet
}

func NewConfigDefault 

func NewConfigDefault() *Config

func (*Config) CapacityForDaysPeople 

func (c *Config) CapacityForDaysPeople(days, people float32) time.Duration

func (*Config) SecondsToDays 

func (c *Config) SecondsToDays(sec int) float32

func (*Config) SecondsToDaysString 

func (c *Config) SecondsToDaysString(sec int) string

type EstimateStats 

type EstimateStats struct {
	WithEstimate    int
	WithoutEstimate int
}

type EstimateVsActual 

type EstimateVsActual struct {
	ClosedCount             int
	ClosedCountWithEstimate int
	EstimateDays            float64
	ActualDays              float64
	EstimateRatio           float64
}

func (*EstimateVsActual) Inflate 

func (eva *EstimateVsActual) Inflate()

type IssuesStats 

type IssuesStats struct {
	WorkingHoursPerDay       float32
	WorkingDaysPerWeek       float32
	ItemCount                int
	ItemCountByStatus        map[string]int
	ItemCountByType          map[string]int
	EstimateStatsByType      map[string]EstimateStats
	TimeOriginalEstimate     time.Duration
	TimeOriginalEstimateDays float64
	AggregateTimeSpent       time.Duration
	AggregateTimeSpentDays   float64
	ClosedEstimateVsActual   EstimateVsActual
}

type JQL added in v0.10.0 

type JQL struct {
	FiltersIncl  [][]string // outer level is `AND`, inner level is `IN`.
	FiltersExcl  [][]string
	IssuesIncl   [][]string
	IssuesExcl   [][]string
	KeysIncl     [][]string
	KeysExcl     [][]string
	ParentsIncl  [][]string
	ParentsExcl  [][]string
	ProjectsIncl [][]string
	ProjectsExcl [][]string
	StatusesIncl [][]string
	StatusesExcl [][]string
	TypesIncl    [][]string
	TypesExcl    [][]string
}

JQL is a JQL builder. It will create a JQL string using `JQL.String()` from the supplied infomration.

func (JQL) String added in v0.10.0 

func (j JQL) String() string

type ProjectMeta added in v0.11.0 

type ProjectMeta struct {
	Key      string
	TeamSize float32
}

type ProjectsMeta added in v0.11.0 

type ProjectsMeta struct {
	Projects map[string]ProjectMeta
}

func NewProjectsMeta added in v0.11.0 

func NewProjectsMeta() ProjectsMeta

func (*ProjectsMeta) AddMap added in v0.11.0 

func (pm *ProjectsMeta) AddMap(info map[string]float32)

func (*ProjectsMeta) CapacitySimple added in v0.12.0 

func (pm *ProjectsMeta) CapacitySimple(itemsPerWeekPerFTE, weekCount float32) float32

func (*ProjectsMeta) FTEs added in v0.12.0 

func (pm *ProjectsMeta) FTEs() float32

type StatusesSet added in v0.12.0 

type StatusesSet struct {
	Map            map[string]string
	MetaStageOrder []string
}

func NewStatusesSet added in v0.12.0 

func NewStatusesSet() StatusesSet

func (*StatusesSet) Add added in v0.12.0 

func (ss *StatusesSet) Add(status, metaStatus string)

func (*StatusesSet) AddMapSlice added in v0.12.0 

func (ss *StatusesSet) AddMapSlice(m map[string][]string)

AddMapSlice should be a map where the keys are meta statuses and the values are slices of Jira statuses.

func (*StatusesSet) DedupeMetaStageOrder added in v0.14.0 

func (ss *StatusesSet) DedupeMetaStageOrder()

func (*StatusesSet) MetaStage added in v0.14.0 

func (ss *StatusesSet) MetaStage(status string) string

MetaStage returns the metastatus for a status. If there is no metastatus, an empty string is returned.

func (*StatusesSet) MetaStageOrderMap added in v0.14.0 

func (ss *StatusesSet) MetaStageOrderMap() map[string]uint

MetaStageOrderMap returns a `map[string]uint` where the key is the meta status and the value is the index.

func (*StatusesSet) StatusesDone added in v0.12.0 

func (ss *StatusesSet) StatusesDone() []string

func (*StatusesSet) StatusesForMetaStage added in v0.14.0 

func (ss *StatusesSet) StatusesForMetaStage(metaStatus string) []string

func (*StatusesSet) StatusesInDevelopment added in v0.14.0 

func (ss *StatusesSet) StatusesInDevelopment() []string

func (*StatusesSet) StatusesInDevelopmentAndDone added in v0.14.0 

func (ss *StatusesSet) StatusesInDevelopmentAndDone() []string

func (*StatusesSet) StatusesReadyForPlanning added in v0.14.0 

func (ss *StatusesSet) StatusesReadyForPlanning() []string

type TimeStats 

type TimeStats struct {
	TimeUnit                      string
	WorkingHoursPerDay            float32
	WorkingDaysPerWeek            float32
	ItemCount                     int
	TimeSpent                     float32
	TimeEstimate                  float32
	TimeOriginalEstimate          float32
	AggregateTimeOriginalEstimate float32
	AggregateTimeSpent            float32
	AggregateTimeEstimate         float32
	TimeRemaining                 float32
	TimeRemainingOriginal         float32
}

func (TimeStats) SecondsToDays 

func (ts TimeStats) SecondsToDays() (TimeStats, error)

type TimeStatsSet 

type TimeStatsSet struct {
	Map map[string]TimeStats
}

type TimeStatsSets 

type TimeStatsSets struct {
	Map map[string]TimeStatsSet
}

func (*TimeStatsSets) AddIssue 

func (tss *TimeStatsSets) AddIssue(iss jira.Issue)

Source Files

View all Source files

Directories

Path Synopsis
cmd
customfields
jirabacklog
jiraissuemeta

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.