Resty v2 release plan and Create migration guide from v1 to v2

[jeevatkm]

This issue is to provide v2 release plan and track the migration guide from v1.x to v2.x

Release Plan:

• Create a v1 branch from master branch
  • v1 branch will be kept for critical bug fixes only for 6 months, no enhancements and no feature additions
  • Any bug fixes will be ported to master branch to reflect on v2 series
  • v1 will be unsupported and locked down in 6 months from the date of v2 release
• Make Release Candidates
  • Fix any issues arises
• Merge v2 branch into the master branch
• Make a v2.0.0 release from the master branch

Release Candidates:

v2.0.0-rc.1 is ready to try it out.

# add it go.mod
github.com/go-resty/resty v2.0.0-rc.1

Migration Guide: (In-progress)

v2 brings https://github.com/go-resty/resty/issues?q=is%3Aclosed+milestone%3A%22v2.0.0+Milestone%22

[jeevatkm]

@Crevil, @1995parham, @moorereason, @h7kanna, @sudo-suhas, @topillar, @pborzenkov, @incubus8, @xakep666, @neganovalexey

I have just gathered the names from resty v2 discussion since v2 release candidate 1 is ready I thought to collect the user feedback. Could you please try rc1 and share feedback?

Thanks.

[sudo-suhas]

@jeevatkm The go module support has not been implemented correctly:

➜ mkdir -p /tmp/scratchpad/hello && cd $_

➜ go mod init github.com/sudo-suhas/hello
go: creating new go.mod: module github.com/sudo-suhas/hello

➜ cat <<EOF > main.go
package main

import (
	"fmt"
)

func main() {
	fmt.Println("hello")
}
EOF

➜ cat go.mod
module github.com/sudo-suhas/hello

➜ go get github.com/go-resty/resty@v2
go get github.com/go-resty/resty@v2: no matching versions for query "v2"

➜ go get github.com/go-resty/resty@v2.0.0-rc.1
go: finding github.com/go-resty/resty v2.0.0-rc.1
go: finding golang.org/x/net v0.0.0-20190311183353-d8887717615a
go: finding golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2
go: finding golang.org/x/text v0.3.0
go: finding golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a
go: downloading github.com/go-resty/resty v0.0.0-20190313065924-46fc51a18d33
go: downloading golang.org/x/net v0.0.0-20190311183353-d8887717615a

➜ cat go.mod
module github.com/sudo-suhas/hello

require github.com/go-resty/resty v0.0.0-20190313065924-46fc51a18d33 // indirect

Ideally, I should refer to resty with the import github.com/go-resty/resty/v2 but that won't work:

➜ cat main.go
package main

import (
	"fmt"
	_ "github.com/go-resty/resty/v2"
)

func main() {
	fmt.Println("hello")
}

➜ go build
go: downloading github.com/go-resty/resty/v2 v2.0.0-rc.1
main.go:5:2: unknown import path "github.com/go-resty/resty/v2": cannot find module providing package github.com/go-resty/resty/v2

See https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher, https://blog.samwhited.com/2019/01/supporting-go-modules/, https://www.youtube.com/watch?v=ms5l0zxC-uM

[moorereason]

It's not clear to me that using the /v2 import path and @v2 version should work yet. According to semver, v2.0.0-rc.1 < v2.0.0. My reading of the Go docs says that /v2 and @v2 means v2.0.0 or higher.

It's odd that go build downloads the rc.1 pre-release and then won't build with it. That may be a bug in the Go tools.

[jeevatkm]

@moorereason Releasing multiple version has more than one approach with go mod. I have tested them with the sample program for v2.0.0-rc.1.

Are you getting any build error? what is it? please let me know.

[jeevatkm]

@sudo-suhas As mentioned in this issue main content. Please refer it as -

github.com/go-resty/resty v2.0.0-rc.1

[Crevil]

I'll try to test this out this week or the next. Do you have a time frame for feedback that I need to aim for?

[1995parham]

I tried with github.com/go-resty/resty v2.0.0-rc.1 then after running go build it replaces it with github.com/go-resty/resty v0.0.0-20190313065924-46fc51a18d33 is it ok?

[jeevatkm]

@1995parham It is okay. This is pre-release of major version, that's why it resolves like this. Any feedback about v2 usage?

[1995parham]

@jeevatkm I switched to v2 in one of my projects and everything looks good to me. Thanks for your awesome work. If anything happens I will comment about it here.

[jeevatkm]

@1995parham I'm glad to hear your feedback 👍, please keep me posted.

FYI, there will be one more breaking change with new feature addition on Retry, refer to #237, I will make rc.2 once it's ready 😄

[moorereason]

I updated one of my tools to v2. Below is a snippet of the diff that captures the essence of the changes. It was pretty simple.

index c2e0bfb..44873f1 100644
--- a/api/api.go
+++ b/api/api.go
@@ -143,10 +143,10 @@ func (c *Config) UpdateSet(set *Set, v url.Values) error {

        uri := fmt.Sprintf("%s/sets/%d", apiBaseURL, set.ID)

-       _, err := resty.SetDebug(c.Debug).R().
+       _, err := resty.New().SetDebug(c.Debug).R().
                SetHeader("Accept", "application/json").
                SetAuthToken(c.AuthToken).
-               SetMultiValueFormData(v).
+               SetFormDataFromValues(v).
                SetResult(&newSet).
                SetError(&e).
                Put(uri)

My contribution to a "migration guide" of the breaking API changes that affected me:

• Global DefaultClient variable has been removed. As a result, AddRetryCondition(), OnAfterResponse(), OnBeforeRequest(), RemoveProxy(), and all Set*() functions were removed. Use resty.New() instead.
• *Request.SetMultiValueFormData() was renamed to *Request.SetFormDataFromValues().
• *Request.SetMultiValueQueryParams() was renamed to *Request.SetQueryParamsFromValues().

[jeevatkm]

@moorereason Thanks for trying out rc.1 and sharing your notes.

I would like to mention one thing from your git diff above. Do not create Resty Client for every request.

-       _, err := resty.SetDebug(c.Debug).R().
+       _, err := resty.New().SetDebug(c.Debug).R().

---

@Crevil

I'll try to test this out this week or the next. Do you have a time frame for feedback that I need to aim for?

Actually I do not have fixed timeline for now. I'm hoping I could make the v2 release in month of April.

[jeevatkm]

All - I have just made a v2.0.0-rc.2 release.

[jeevatkm]

v2 Release notes draft is ready. Just finishing up final user request changes.

---

Release Notes

How to get?

go.mod

require github.com/go-resty/resty v2.0.0

go get

go get -u github.com/go-resty/resty

How to use?

import "github.com/go-resty/resty"

New Features

• Dial a TCP connection from a specific Local Interface/IP Address Add support to Dial a TCP connection from a specific Local Interface/Address #226 @jeevatkm
• On-Demand Resty Request/Responce tracer, Add on-demand tracer into resty #216 @jeevatkm, see TraceInfo, see Client.EnableTrace and see Request.EnableTrace - idea born from @moorereason example gist
• New RetryAfterFunc addition into Resty's retry capabilities PR change Backoff() algorithm #237 @neganovalexey, see RetryAfterFunc

Enhancements

• Build User-Agent string only once PR Build User-Agent string only once #221 @moorereason
• Retry Backoff algorthim and follow enhancement PR change Backoff() algorithm #237 @neganovalexey
• Log request and response debug log together for easy debugging, its highly helpful for parallel Log request and response debug log together for easy debugging #218 @jeevatkm
• Default values set while http.Transport creation simliar to Langauge default client Set Sane default timeouts for client and transport #212 @jeevatkm
  • Timeout, KeepAlive, MaxIdleConns, IdleConnTimeout, TLSHandshakeTimeout, ExpectContinueTimeout, MaxIdleConnsPerHost
• Added support to multipart/form-data payload without filename and content type values PR fix multipart/form-data without filename and content type #236 @larryhu
• Added HTTP verb PATCH into multipart support PATCH multipart/form-data #239 @jeevatkm

Breaking Changes - Migrating v1.x to v2

• Resty v2 import path have changed to github.com/go-resty/resty Refactored resty to move away from gopkg.in in favor of go mod #215 @jeevatkm
  • Resty v1 import path is not affected.
• Resty Default Client approach have been removed. Create an instance of Resty client with appropriate settings for usage Remove default client approach from Resty, make resty further simple to use #232 @jeevatkm
• PreRequestHook signature have been updated to func(cl *Client, r *http.Request) error Update PreRequestHook method signature #217 @jeevatkm
• Retry condition function signature updated to RetryConditionFunc func(*Response, error) bool change Backoff() algorithm #237, Pass error returned by resty.Client.execute() to retry condition callback #214 @neganovalexey, @jeevatkm
• Resty v2 supports go1.8 and above Make Resty minimum Go version support to go1.8 #233 and its related to new feature Tracer ability Add on-demand tracer into resty #216 @jeevatkm
• Resty v2 brings new Logger interface Make logger interface based with minimal methods #229, refer to godoc @jeevatkm
• Methods to accept type url.Values for Query string and Form data on Request struct Add method into struct Request to accept type url.Values for Query strings #213 @jeevatkm
  • Refactored method from Request.SetMultiValueQueryParams to Request.SetQueryParamsFromValues
  • Refactored method from Request.SetMultiValueFormData to Request.SetFormDataFromValues

[jeevatkm]

I'm closing this one, preparing for v2 release.