Update docs and examples and tests to use `NewClient` instead of `Dial`

[dfawley]

After #7010 we need to make sure all our documentation recommends NewClient. We should still retain some tests for Dial but the majority of them should probably be converted to use NewClient as well.

Tasks:

• Tests cases that don't rely upon Dial (tests for WithTimeout/etc should keep using Dial).
• In documentation, update from Dial to NewClient everywhere (note: this includes http://github.com/grpc/grpc.io)
• Update anti-patterns doc to discuss the differences between Dial and NewClient and also mention WithTimeout specifically in the existing section about Dial.

[silaselisha]

@dfawley I would like to work on this issue

[dfawley]

Sounds good @silaselisha, that would be great -- we need to start only inside the repo for now, because we don't want to update any other documentation until our next release which includes the new function.

Note that we can't just do a trivial sed to replace grpc.Dial with grpc.NewClient (though maybe that's a decent way to start), because there are minor behavior differences that some of our tests probably (hopefully) will rely on.

[silaselisha]

@dfawley I'll start working on the example repo, and as mentioned I'll strictly traverse through the files just to manually replace grpc.Dial with grpc.NewClient.

[SamYuan1990]

To be specific, how to set timeout makes me confusing as this newclient function invoking WithTimeout in current test case which is marked as Deprecated... for details at #7093

[dfawley]

Timeouts are not supported in NewClient. See https://github.com/grpc/grpc-go/blob/master/Documentation/anti-patterns.md#dialing-in-grpc for more info.

If you need timeouts, feel free to keep using Dial or DialContext; they are not going to be deleted in 1.x, they are just not a good idea to use per the information above.

[SamYuan1990]

Timeouts are not supported in NewClient. See https://github.com/grpc/grpc-go/blob/master/Documentation/anti-patterns.md#dialing-in-grpc for more info.

If you need timeouts, feel free to keep using Dial or DialContext; they are not going to be deleted in 1.x, they are just not a good idea to use per the information above.

can we remove Deprecated on Dial or DialContext to avoid lint error?

[SamYuan1990]

https://github.com/Hyperledger-TWGC/tape/actions/runs/8551020475/job/23429132147?pr=384#step:5:25

Error: SA1019: grpc.DialContext is deprecated: use NewClient instead.  Will be supported throughout 1.x.  (staticcheck)

[dfawley]

https://www.merriam-webster.com/dictionary/deprecate

to withdraw official support for or discourage the use of (something, such as a software product) in favor of a newer or better alternative

"Deprecated" seems appropriate here. You should ideally stop using it, or update your linter if that's not possible.

See also https://en.wikipedia.org/wiki/Deprecation:

deprecation is the discouragement of use of some terminology, feature, design, or practice, typically because it has been superseded or is no longer considered efficient or safe, without completely removing it or prohibiting its use. Typically, deprecated materials are not completely removed to ensure legacy compatibility or back up practice in case new methods are not functional in an odd scenario.

[SamYuan1990]

Timeouts are not supported in NewClient. See https://github.com/grpc/grpc-go/blob/master/Documentation/anti-patterns.md#dialing-in-grpc for more info.

If you need timeouts, feel free to keep using Dial or DialContext; they are not going to be deleted in 1.x, they are just not a good idea to use per the information above.

For people who want to use Timeout with currently Dial or DialContext been marked as Deprecated, the lint as a part of static scan will fail, breaks OpenSSF practices.

Hence, IMO, which means gprc is not going to support timeout feature any more?

[dfawley]

breaks OpenSSF practices

What practices exactly are you referring to? Do you have documentation that you can refer to?

We will continue to test and support these functions. However, we don't recommend that you use them as they reinforce anti-patterns, hence they are marked as deprecated.