General Discussion: Features/Changes in V2

[ghostsquad]

Overview

This issue is to discuss what kind of breaking changes we want in V2.

We have several PRs that can't be merged in V1 due to backwards incompatibility.

I'll start with my wishlist:

• Support for Contexts (Add support for context package #182)
• All Timestamps Parsed
• Better support for custom fields
• Better error handling
• Don't use nil for optional parameters (this is an anti-pattern)
  If a nil httpClient is provided, http.DefaultClient will be used.
  Alternative:
  https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis
• More use of Interfaces
• Use pkg/errors.Errorsf instead of fmt.Errorsf

To Be Continued... as I review more

Custom Fields

https://developer.atlassian.com/server/jira/platform/jira-rest-api-examples/
https://docs.atlassian.com/software/jira/docs/api/REST/8.0.2/#api/2/customFields-getCustomFields

Custom fields are defined here. It would be useful have definitions for each customField type, and additional points for being able to generate code for a project based on the custom fields defined for that project. I have yet to encounter a Jira Library that makes working with custom fields an enjoyable experience.

[hdshah-dev]

Hello Andy,
I am using go-jira client version 1.11.1. I am trying to see an option to change the transition of an issue with a comment (as part of the update). I do see DoTransitionWithPayload() method to allow a payload TransitionPayload (struct). However I dont see a way to set the comment in TransitionPayload struct or there is one to be used. Can you please confirm if this feature is yet to be implemented or if otherwise can you provide an example to do?
Thanks

[ghostsquad]

@hdshah-dev I created #248 issue for you. As this is the wrong place to ask for support.

For clarification, I'll edit the topic of this issue as well.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity in the last 60 days. It will be closed in 7 days if no further activity occurs. Thank you for your contributions.

[andygrunwald]

/unstale.

Maybe it is time to think about a v2 more actively.
Maybe we should check all open PRs, tagging the latest state and open master for v2 + breaking changes?

[andygrunwald]

Thanks, @ghostsquad for kicking this off. Valuable to exchange about the plans for v2.
I agree with your current list you have put together. Those are important parts that should add value to this library.

I would like to extend the discussion on this issue and discuss pieces next to breaking changes:

Being more explicit

We should state what we are officially supporting when it comes to Jira (Product variant, product version extensions/plugins, ...), Go and similar.

Issues like

• Which Jira product are we supporting? #295
• Support of Go versions #290

can help here.
This provides clarity for every user and makes decisions + discussions easier.

Potential of go generate + automation

Can we leverage the potential of go generate + automation to provide more quality to this library? Things that come into my mind:

• Updating API URLs
• Generating structs + data structures for API responses + API requests (e.g. options)
• Keeping API endpoints up to date (or maybe providing a list of API endpoints we support + not supports (and where help is needed)).

google/go-github is using this and might be an inspiration. See

• go-github/github/gen-accessors.go
• go-github/github/gen-stringify-test.go
• go-github/update-urls
• Go generate should validate and fix all documentation URLs #1476
• go generate in CONTRIBUTING.md

Using official API descriptions/definitions

Jira provides a machine-readable API description/definition:

Jira Server

The Jira Server platform REST API resources are also documented in this WADL file: jira-rest-plugin.wadl.

Source: https://developer.atlassian.com/server/jira/platform/rest-apis/

Jira Cloud

• OpenAPI spec
• Postman collection

Source: https://developer.atlassian.com/cloud/jira/platform/rest/v2/

Can we use this to

• generate API endpoints/structs?
• validate our code?
• check how "complete" we are?

Maybe this can be combined with the go generate idea.

---

Please keep in mind, this is more a braindump and various ideas. Nothing concrete right now, and everything open to discuss. I am curious about your (@ghostsquad, @rbriski + community) opinion here. What do you think?

[ghostsquad]

@andygrunwald just wanted to let you know that I've decided to start on the V2 rewrite!

I'm going to use the v2 subfolder method that's recommended by Golang (https://blog.golang.org/v2-go-modules)

Stay tuned for a PR!

[andygrunwald]

@ghostsquad Sounds super nice! Let me know how I can help (or review something). Feel free to push early ideas as a PR and mark it as a draft.

[ghostsquad]

@andygrunwald VERY EARLY draft PR has been made. I literally just did git add of the files that I've been working on... nothing works, does not compile, no tests... still in the exploration/discovery phases... see #300

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity in the last 60 days. It will be closed in 7 days if no further activity occurs. Thank you for your contributions.

[andygrunwald]

Adding a few notes from my desk about the features we aim to put into v2/wishlist:

• Options Arguments
• Generation of Code for API endpoints (swagger files?)
• Unified / more useful error responses
• A better/Easier custom field implementation
• API Client Completion // Tracking of what is implemented
• Differentiation between On-Premise and Cloud-Version of Jira (might have different APIs)

[jef]

I would like to see some of the APIs that require boardId to be consistent with either int or string type.

Example:

// GetAllSprints wraps GetAllSprintsWithContext using the background context.
func (s *BoardService) GetAllSprints(boardID string) ([]Sprint, *Response, error) {
	return s.GetAllSprintsWithContext(context.Background(), boardID)
}

// --snip--

// GetAllSprintsWithOptions wraps GetAllSprintsWithOptionsWithContext using the background context.
func (s *BoardService) GetAllSprintsWithOptions(boardID int, options *GetAllSprintsOptions) (*SprintsList, *Response, error) {
	return s.GetAllSprintsWithOptionsWithContext(context.Background(), boardID, options)
}

[jason-barbier-tcc]

• Support for GDPR strict mode

[andygrunwald]

Hey @jason-barbier-tcc

• Support for GDPR strict mode

Do you have a bit more information on what this means for a library and how we can support this?
E.g. a link with more information?

[jason-barbier-tcc]

@andygrunwald Sure
So it's basically this https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/
The TL;DR on it is the cloud version, and if you select GDPR strict on prem no longer uses usernames and you can not do User.Get() with a username you must use the jira user id.
If you need to find the user ID you need to use the longer query process and find users via other interfaces like https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users/#api-rest-api-3-user-bulk-migration-get or https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-user-search/#api-rest-api-3-user-search-get

[andygrunwald]

Thanks @jason-barbier-tcc.
So it boils down to supporting multiple ways to retrieve a user, correct?

[jason-barbier-tcc]

@andygrunwald yep, multiple or different ways to retrieve users due to a change to make it easier to comply with GDPR.

[andygrunwald]

Thanks, @jason-barbier-tcc.
Just want to ensure that this library contains as little magic as possible and providing power to the user.
Sounds good from my side.

[andygrunwald]

Another note that was triggered by #337:

• Full support for context

[andygrunwald]

Hey all,

i used this issue as a foundation to create own tickets per request.
Here is the list:

• Support for Contexts: Support Context for HTTP requests #337
• All Timestamps Parsed: Unify and parse all timestamps as time.Time #476
• Better support for custom fields: Better support for custom fields #477
• Don't use nil for optional parameters (this is an anti-pattern)
  If a nil httpClient is provided, http.DefaultClient will be used.
  Alternative:
  https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis
  Think about to make use of functional options #479
• Use pkg/errors.Errorsf instead of fmt.Errorsf: Migrate to native errors #478
• Evaluate the potential of go generate + automation: Evaluate the potential of go generate + automation #480

I dropped the following items, because they are a bit unclear what the current issue is:

• More use of Interfaces
• Better error handling

There are more tickets, see https://github.com/andygrunwald/go-jira/issues?q=is%3Aopen+is%3Aissue+label%3Av2

[andygrunwald]

See also #489