Skip to content

Commit

Permalink
docs: links improvements (#2003)
Browse files Browse the repository at this point in the history
  • Loading branch information
ennru authored Nov 26, 2024
1 parent d9f143a commit 8640f6a
Show file tree
Hide file tree
Showing 11 changed files with 18 additions and 18 deletions.
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ These guidelines are meant to be a living document that should be changed and ad
We encourage changes that make it easier to achieve our goals in an efficient way.

Please also note that we have a *Code of Conduct* in place which aims keep our community a nice and helpful one.
You can read its full text here: [Lightbend Community Code of Conduct](https://www.lightbend.com/conduct).
You can read its full text here: [Akka Code of Conduct](https://akka.io/conduct).

## General Workflow

Expand All @@ -61,7 +61,7 @@ The steps are exactly the same for everyone involved in the project (be it core
- Please write additional tests covering your feature and adjust existing ones if needed before submitting your Pull Request. The `validatePullRequest` sbt task ([explained below](#the-validatepullrequest-task)) may come in handy to verify your changes are correct.
1. Once your feature is complete, prepare the commit following our [Creating Commits And Writing Commit Messages](#creating-commits-and-writing-commit-messages). For example, a good commit message would be: `Adding compression support for Manifests #22222` (note the reference to the ticket it aimed to resolve).
1. Now it's finally time to [submit the Pull Request](https://help.github.com/articles/using-pull-requests)!
1. If you have not already done so, you will be asked by our CLA bot to [sign the Lightbend CLA](https://www.lightbend.com/contribute/cla/akka) online CLA stands for Contributor License Agreement and is a way of protecting intellectual property disputes from harming the project.
1. If you have not already done so, you will be asked by our CLA bot to [sign the Akka CLA](https://www.lightbend.com/contribute/cla) online CLA stands for Contributor License Agreement and is a way of protecting intellectual property disputes from harming the project.
1. If you're not already on the contributors white-list, the @akka-ci bot will ask `Can one of the repo owners verify this patch?`, to which a core member will reply by commenting `OK TO TEST`. This is just a sanity check to prevent malicious code from being run on the Jenkins cluster.
1. Now both committers and interested people will review your code. This process is to ensure the code we merge is of the best possible quality, and that no silly mistakes slip through. You're expected to follow-up these comments by adding new commits to the same branch. The commit messages of those commits can be more lose, for example: `Removed debugging using printline`, as they all will be squashed into one commit before merging into the main branch.
- The community and team are really nice people, so don't be afraid to ask follow up questions if you didn't understand some comment, or would like to clarify how to continue with a given feature. We're here to help, so feel free to ask and discuss any kind of questions you might have during review!
Expand Down
8 changes: 4 additions & 4 deletions docs/src/main/paradox/apidesign.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
# API Design

When designing a gRPC API, you could take into consideration some of the
[Google Cloud API Design Patterns](https://cloud.google.com/apis/design/design_patterns).
[Google Cloud API Design Patterns](https://google.aip.dev/general#design-patterns).

## Methods without request or response

If you want to create an endpoint that takes no parameters or produces no
response, it might be tempting to use the `Empty` type as defined by
Google in their [empty.proto](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/empty.proto).
Google in their [empty.proto](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/empty.proto).

It is recommended to introduce your own (empty) message types, however, as
functionality may grow and this prepares you for adding additional (optional) fields
over time.

## Declare and enforce constraints for your request and response payloads with `protoc-gen-validate`

[`protoc-gen-validate` (PGV)](https://github.com/envoyproxy/protoc-gen-validate) defines
[`protoc-gen-validate` (PGV)](https://github.com/bufbuild/protoc-gen-validate) defines
a set of Protobuf options allowing to add additional rules on messages and fields in a declarative
fashion. A set of validators for different languages is also provided, to enforce these rules at
runtime.

### Java support

Validators for Java stubs are provided by [the project itself](https://github.com/envoyproxy/protoc-gen-validate#java).
Validators for Java stubs are provided by [the project itself](https://github.com/bufbuild/protoc-gen-validate#java).

Follow the instructions there for Maven and Gradle. If your are using sbt, you can get
`validate.proto` into the include path and run the protoc plugin generating the validators
Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/paradox/client/details.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ Java

## Rich error model

Beyond status codes you can also use the [Rich error model](https://www.grpc.io/docs/guides/error/#richer-error-model).
Beyond status codes you can also use the [Rich error model](https://grpc.io/docs/guides/error/#richer-error-model).

Extract the `GrpcServiceException` to access `code`, `message` and `details`.

Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/paradox/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ It features:

## Project Status

Akka gRPC is supported for users with an [Akka license](https://www.lightbend.com/akka#pricing).
Akka gRPC is supported for users with an [Akka license](https://akka.io/pricing).

Both client- and server-side APIs are based on Akka Streams.

Expand Down
4 changes: 2 additions & 2 deletions docs/src/main/paradox/proto.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
gRPC uses the Protobuf `.proto` file format to define your messages, services
and some aspects of the code generation.

For an in-depth description see the [Protocol buffers documentation](https://developers.google.com/protocol-buffers/docs/proto3),
For an in-depth description see the [Protocol buffers documentation](https://protobuf.dev/programming-guides/proto3/),
but here are a few quick examples:

## Messages
Expand All @@ -26,7 +26,7 @@ There are a number of options that can be set in the `.proto` definition that in

@@snip [helloworld.proto](/plugin-tester-scala/src/main/protobuf/helloworld.proto) { #options }

The (optional) [`package`](https://developers.google.com/protocol-buffers/docs/proto3#packages)
The (optional) [`package`](https://protobuf.dev/programming-guides/proto3/#packages)
in the `.proto` is used to resolve references from one `.proto` file to another.
It can also be used for the package name in the generated code, but it is
common to use the separate `java_package` option to override it. In the Akka gRPC
Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/paradox/quickstart-scala/testing.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Testing gRPC

The tests in the Hello World example illustrates use of the [ScalaTest](http://www.scalatest.org/) framework. The test coverage is not complete. It only shows how to get started with testing gRPC services. You could add to it as an exercise to increase your own knowledge.
The tests in the Hello World example illustrates use of the [ScalaTest](https://www.scalatest.org/) framework. The test coverage is not complete. It only shows how to get started with testing gRPC services. You could add to it as an exercise to increase your own knowledge.

Let's look at the test class definition in the `GreeterSpec.scala` source file:

Expand Down
4 changes: 2 additions & 2 deletions docs/src/main/paradox/server/details.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Java
: @@snip[ExceptionGreeterServiceImpl](/interop-tests/src/test/java/example/myapp/helloworld/grpc/ExceptionGreeterServiceImpl.java) { #streaming }

## Rich error model
Beyond status codes you can also use the [Rich error model](https://www.grpc.io/docs/guides/error/#richer-error-model).
Beyond status codes you can also use the [Rich error model](https://grpc.io/docs/guides/error/#richer-error-model).

This example uses an error model taken from [common protobuf](https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto) but every class that is based on @scala[`scalapb.GeneratedMessage`]@java[`com.google.protobuf.Message`] can be used.
Build and return the error as an `AkkaGrpcException`:
Expand All @@ -55,4 +55,4 @@ Scala
Java
: @@snip[RichErrorModelTest](/plugin-tester-java/src/test/scala/example/myapp/helloworld/RichErrorNativeImpl.java) { #rich_error_model_unary }

Please look @ref[here](../client/details.md) how to handle this on the client.
Please look @ref[here](../client/details.md) how to handle this on the client.
2 changes: 1 addition & 1 deletion docs/src/main/paradox/server/kubernetes.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ There are 3 ways to use HTTP/2:
* HTTP/2 over plaintext TCP ('h2c'), without negotiation. This assumes the client has prior knowledge that the server supports HTTP/2.

A straightforward way to expose a TCP endpoint outside the cluster is to create a Kubernetes `Service` of type `LoadBalancer`. Beyond that, Kubernetes supports many types of [Ingress Controllers](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/).
[GCE](https://github.com/kubernetes/ingress-gce/blob/master/README.md) and [NGINX](https://github.com/kubernetes/ingress-nginx/blob/master/README.md)
[GCE](https://github.com/kubernetes/ingress-gce/blob/master/README.md) and [NGINX](https://github.com/kubernetes/ingress-nginx/blob/main/README.md)
are the most widely known.

## LoadBalancer Service
Expand Down
2 changes: 1 addition & 1 deletion project/Dependencies.scala
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ object Dependencies {

// We don't force Akka updates because downstream projects can upgrade
// themselves. For more information see
// https://doc.akka.io//docs/akka/current/project/downstream-upgrade-strategy.html
// https://doc.akka.io/libraries/akka-core/current/project/downstream-upgrade-strategy.html
val akka = "2.10.0"
val akkaBinary = VersionNumber(akka).numbers match { case Seq(major, minor, _*) => s"$major.$minor" }
val akkaHttp = "10.7.0"
Expand Down
2 changes: 1 addition & 1 deletion project/plugins.sbt
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ addSbtPlugin("pl.project13.scala" % "sbt-jmh" % "0.4.7")
addSbtPlugin("com.github.sbt" % "sbt-ci-release" % "1.9.0")

// docs
addSbtPlugin("io.akka" % "sbt-paradox-akka" % "24.10.4")
addSbtPlugin("io.akka" % "sbt-paradox-akka" % "24.10.6")
addSbtPlugin("com.lightbend.paradox" % "sbt-paradox-dependencies" % "0.2.4")
addSbtPlugin("com.lightbend.sbt" % "sbt-publish-rsync" % "0.3")
addSbtPlugin("com.github.sbt" % "sbt-site-paradox" % "1.7.0")
Expand Down
4 changes: 2 additions & 2 deletions project/project-info.conf
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ project-info {
]
forums: [
{
text: "Lightbend Discuss"
url: "https://discuss.lightbend.com/c/akka/akka-grpc"
text: "Akka Discuss"
url: "https://discuss.akka.io/c/akka/akka-grpc"
}
]
}
Expand Down

0 comments on commit 8640f6a

Please sign in to comment.