You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pekko.apache.org by fa...@apache.org on 2023/02/16 12:11:25 UTC
[incubator-pekko] branch main updated: Update CONTRIBUTING.md (#194)
This is an automated email from the ASF dual-hosted git repository.
fanningpj pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-pekko.git
The following commit(s) were added to refs/heads/main by this push:
new b6b902e886 Update CONTRIBUTING.md (#194)
b6b902e886 is described below
commit b6b902e88658ac40d6774284067788910288cbb0
Author: PJ Fanning <pj...@users.noreply.github.com>
AuthorDate: Thu Feb 16 13:11:20 2023 +0100
Update CONTRIBUTING.md (#194)
---
CONTRIBUTING.md | 62 ++++++++++++++++++++++++++++-----------------------------
1 file changed, 31 insertions(+), 31 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ea9d35bd09..1b282a799d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@ We follow the standard GitHub [fork & pull](https://help.github.com/articles/usi
You're always welcome to submit your PR straight away and start the discussion (without reading the rest of this wonderful doc or the README.md). The goal of these notes is to make your experience contributing to Pekko as smooth and pleasant as possible. We're happy to guide you through the process once you've submitted your PR.
-## The Pekko Community
+## The Apache Pekko Community
If you have questions about the contribution process or discuss specific issues, please interact with the community using the following resources.
@@ -52,7 +52,7 @@ Pull request validation states:
## Pekko contributing guidelines
-These guidelines apply to all Pekko projects, by which we currently mean both the `apache/incubator-pekko` repository, as well as any plugins or additional repositories.
+These guidelines apply to all Apache Pekko projects, by which we currently mean both the `apache/incubator-pekko` repository, as well as any plugins or additional repositories.
These guidelines are meant to be a living document that should be changed and adapted as needed.
We encourage changes that make it easier to achieve our goals efficiently.
@@ -65,20 +65,20 @@ The steps are exactly the same for everyone involved in the project, including t
1. To avoid duplicated effort, it might be good to check the [issue tracker](https://github.com/apache/incubator-pekko/issues) and [existing pull requests](https://github.com/apache/incubator-pekko/pulls) for existing work.
- If there is no ticket yet, feel free to [create one](https://github.com/apache/incubator-pekko/issues/new/choose) to discuss the problem and the approach you want to take to solve it.
1. [Fork the project](https://github.com/apache/incubator-pekko/fork) on GitHub. You'll need to create a feature-branch for your work on your fork, as this way you'll be able to submit a pull request against the mainline Pekko.
-1. Create a branch on your fork and work on the feature. For example: `git checkout -b custom-headers-akka-http`
+1. Create a branch on your fork and work on the feature. For example: `git checkout -b custom-headers-pekko-http`
- Please make sure to follow the general quality guidelines (specified below) when developing your patch.
- 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.
- Use the `verifyCodeStyle` sbt task to ensure your code is properly formatted and includes the proper copyright headers.
1. Once your feature is complete, prepare the commit following our guide [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. If it's a new feature or a change of behavior, document it on the [docs](https://github.com/apache/incubator-pekko/tree/main/docs). When the feature touches Scala and Java DSL, document both the Scala and Java APIs.
1. Now it's finally time to [submit the pull request](https://help.github.com/articles/using-pull-requests)!
- - Please make sure to include a reference to the issue you're solving *in the comment* for the Pull Request, as this will cause the PR to be linked properly with the issue. Examples of good phrases for this are: "Resolves #1234" or "Refs #1234".
+ - Please make sure to include a reference to the issue you're solving *in the comment* for the Pull Request, as this will cause the PR to be linked properly with the issue. Examples of good phrases for this are: "Resolves #1234" or "Refs #1234".
1. If you are a first time contributor, a core member must approve the CI to run for your pull request.
1. For non-trivial changes, you will be asked to sign the [CLA](https://www.apache.org/licenses/contributor-agreements.html) if you have not done so before.
1. Now, both committers and interested people will review your code. This process ensures that the code we merge is of the best possible quality and that no silly mistakes slip through. You're expected to follow-up on these comments by adding new commits to the same branch. The commit messages of those commits can be more loose, for example: `Removed debugging using printline`, as they all will be squashed into one commit before merging into the main branch.
- - The community and core 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 clarification on how to continue with a given feature. We're here to help, so feel free to ask and discuss any questions you might have during the review process!
+ - The community and core 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 clarification on how to continue with a given feature. We're here to help, so feel free to ask and discuss any questions you might have during the review process!
1. After the review, you should fix the issues as needed (pushing a new commit for a new review, etc.), iterating until the reviewers give their approval signaled by GitHub's pull-request approval feature. Usually, a reviewer will add an `LGTM` comment, which means "Looks Good To Me".
- - In general, a PR is expected to get 2 approvals from the team before it is merged. If the PR is trivial or under exceptional circumstances (such as most of the core team being on vacation, a PR was very thoroughly reviewed/tested and surely is correct), a single LGTM may be fine as well.
+ - In general, a PR is expected to get 2 approvals from the team before it is merged. If the PR is trivial or under exceptional circumstances (such as most of the core team being on vacation, a PR was very thoroughly reviewed/tested and surely is correct), a single LGTM may be fine as well.
1. If the code change needs to be applied to other branches as well (for example, a bugfix needing to be backported to a previous version), one of the team members will either ask you to submit a PR with the same commits to the old branch or will do this for you.
- Follow the [backporting steps](#backporting) below.
1. Once everything is said and done, your pull request gets merged :tada:! Your feature will be available with the next "earliest" release milestone (i.e. if backported so that it will be in release x.y.z, find the relevant milestone for that release). Of course, you will be given credit for the fix in the release stats during the release's announcement. You've made it!
@@ -158,23 +158,23 @@ To run a single multi-jvm test:
```shell
sbt
-project akka-cluster
-MultiJvm/testOnly akka.cluster.SunnyWeather
+project cluster
+MultiJvm/testOnly org.apache.pekko.cluster.SunnyWeather
```
To format the Scala source code:
```shell
sbt
-akka-cluster/scalafmtAll
-akka-persistence/scalafmtAll
+cluster/scalafmtAll
+persistence/scalafmtAll
```
To format the Java source code:
```shell
sbt
-project akka-actor
+project actor
javafmtAll
```
@@ -182,7 +182,7 @@ To keep the *import*s sorted with:
```shell
sbt
-project akka-actor
+project actor
sortImports
```
@@ -226,8 +226,8 @@ To use the task, simply type `validatePullRequest`, and the output should includ
```shell
> validatePullRequest
[info] Diffing [HEAD] to determine changed modules in PR...
-[info] Detected uncomitted changes in directories (including in dependency analysis): [akka-protobuf,project]
-[info] Detected changes in directories: [akka-actor-tests, project, akka-stream, docs, akka-persistence]
+[info] Detected uncomitted changes in directories (including in dependency analysis): [protobuf,project]
+[info] Detected changes in directories: [actor-tests, project, stream, docs, persistence]
```
By default, changes are diffed with the `main` branch when working locally. If you want to validate against a different
@@ -247,13 +247,13 @@ e.g. `allCluster`, `allTyped`.
Binary compatibility rules and guarantees are described in depth in the [Binary Compatibility Rules
](https://pekko.apache.org/) section of the documentation.
-Pekko uses [MiMa](https://github.com/lightbend/mima) to validate the binary compatibility of incoming pull requests. If your
+Pekko uses [MiMa](https://github.com/lightbend/mima) to validate the binary compatibility of incoming pull requests. If your
PR fails due to binary compatibility issues, you may see an error like this:
```
-[info] akka-stream: found 1 potential binary incompatibilities while checking against org.apache.pekko:akka-stream_2.12:2.4.2 (filtered 222)
-[error] * method foldAsync(java.lang.Object,scala.Function2)akka.stream.scaladsl.FlowOps in trait akka.stream.scaladsl.FlowOps is present only in current version
-[error] filter with: ProblemFilters.exclude[ReversedMissingMethodProblem]("akka.stream.scaladsl.FlowOps.foldAsync")
+[info] stream: found 1 potential binary incompatibilities while checking against org.apache.pekko:pekko-stream_2.12:2.4.2 (filtered 222)
+[error] * method foldAsync(java.lang.Object,scala.Function2)org.apache.pekko.stream.scaladsl.FlowOps in trait org.apache.pekko.stream.scaladsl.FlowOps is present only in current version
+[error] filter with: ProblemFilters.exclude[ReversedMissingMethodProblem]("org.apache.pekko.stream.scaladsl.FlowOps.foldAsync")
```
In such situations it's good to consult with a core team member whether the violation can be safely ignored or if it would indeed
@@ -266,7 +266,7 @@ Situations when it may be acceptable to ignore a MiMa issued warning include:
- if it is touching any class marked as `private[pekko]`, `/** INTERNAL API*/` or similar markers
- if it is concerning internal classes (often recognisable by package names like `dungeon`, `impl`, `internal` etc.)
-- if it is adding API to classes / traits which are only meant for extension by Akka itself, i.e. should not be extended by end-users
+- if it is adding API to classes / traits which are only meant for extension by Pekko itself, i.e. should not be extended by end-users
- other tricky situations
The binary compatibility of the current changes can be checked by running `sbt +mimaReportBinaryIssues`.
@@ -334,8 +334,8 @@ Alternatively, use `docs/paradoxBrowse` to open the generated docs in your defau
Pekko Paradox supports directives to link to the Scaladoc- and Javadoc-generated API documentation:
* `@apidoc[Flow]` searches for the class name and creates links to Scaladoc and Javadoc (see variants in [sbt-paradox-apidoc](https://github.com/lightbend/sbt-paradox-apidoc#examples))
-* `@scaladoc[Flow](akka.stream.scaladsl.Flow)` (see [Paradox docs](https://developer.lightbend.com/docs/paradox/current/directives/linking.html#scaladoc-directive))
-* `@javadoc[Flow](akka.stream.javadsl.Flow)` (see [Paradox docs](https://developer.lightbend.com/docs/paradox/current/directives/linking.html#javadoc-directive))
+* `@scaladoc[Flow](org.apache.pekko.stream.scaladsl.Flow)` (see [Paradox docs](https://developer.lightbend.com/docs/paradox/current/directives/linking.html#scaladoc-directive))
+* `@javadoc[Flow](org.apache.pekko.stream.javadsl.Flow)` (see [Paradox docs](https://developer.lightbend.com/docs/paradox/current/directives/linking.html#javadoc-directive))
#### Scaladoc
@@ -393,7 +393,7 @@ Follow these guidelines when creating public commits and writing commit messages
3. Following the single line description should be a blank line followed by an enumerated list with the details of the commit.
4. You can request a review by a specific team member for your commit (depending on the degree of automation we reach, the list may change over time):
- * "Review by @gituser "- if you want to notify someone on the team. The others can and are encouraged to participate.
+ * "Review by @gituser "- if you want to notify someone on the team. The others can and are encouraged to participate.
Example:
@@ -423,7 +423,7 @@ For existing contributors, Github Actions will run without requiring any manual
For first time contributors, the workflow will be run after an approval from a core team member. After that, whenever new commits are pushed to the pull request, a validation job will be automatically started.
-To speed up PR validation times the Akka build contains a special sbt task called `validatePullRequest`,
+To speed up PR validation times the Pekko build contains a special sbt task called `validatePullRequest`,
which is smart enough to figure out which projects should be built if a PR only has changes in some parts of the project.
For example, if your PR only touches `persistence`, no `remote` tests need to be run, however the task
will validate all projects that depend on `persistence` (including samples).
@@ -438,10 +438,10 @@ sbt -Dpekko.test.tags.exclude=performance,timing,long-running -Dpekko.test.multi
It is also possible to exclude groups of test by their names. For example:
```shell
-sbt -Dpekko.test.names.exclude=akka.cluster.Stress
+sbt -Dpekko.test.names.exclude=org.apache.pekko.cluster.Stress
```
-Will exclude any tests that have names containing `akka.cluster.Stress`.
+Will exclude any tests that have names containing `org.apache.pekko.cluster.Stress`.
### Source style
@@ -459,7 +459,7 @@ not needed to use `sbt scalafmtAll` when editing with IntelliJ.
PR validation includes checking that the Scala sources are formatted and will fail if they are not.
-Pekko prefers flattened imports rather than grouped, which helps reduce merge conflicts.
+Pekko prefers flattened imports rather than grouped, which helps reduce merge conflicts.
If you are using IntelliJ IDEA, you can disable it by unchecking: `Preferences` -> `Code Style` -> `Scala` -> `Imports` -> `Merge imports with the same prefix into one statement`.
@@ -473,7 +473,7 @@ PR validation includes checking that the Java sources are formatted and will fai
#### Code discipline opt out
-In addition to formatting, the Pekko build enforces code discipline through a set of compiler flags. While exploring ideas, the discipline may be more of a hindrance than a help. Therefore, it is possible to disable it by setting the system property `akka.no.discipline`
+In addition to formatting, the Pekko build enforces code discipline through a set of compiler flags. While exploring ideas, the discipline may be more of a hindrance than a help. Therefore, it is possible to disable it by setting the system property `pekko.no.discipline`
to any non-empty string value when starting up sbt:
```shell
@@ -513,9 +513,9 @@ Scala has proven the most viable way to do it, as long as you keep the following
and binary compatibility reasons do not have this subdivision.
1. Have methods in the `javadsl` package delegate to the methods in the Scala API, or the common internal implementation.
- For example, the Pekko Stream Scala instances have a `.asJava` method to convert to the `akka.stream.javadsl` counterparts.
+ For example, the Pekko Stream Scala instances have a `.asJava` method to convert to the `org.apache.pekko.stream.javadsl` counterparts.
-1. When using Scala `object` instances, offer a `getInstance()` method. See `akka.Done` for an example.
+1. When using Scala `object` instances, offer a `getInstance()` method. See `org.apache.pekko.Done` for an example.
1. When the Scala API contains an `apply` method, use `create` or `of` for Java users.
@@ -527,7 +527,7 @@ Scala has proven the most viable way to do it, as long as you keep the following
1. Complement any methods with Scala collections with a Java collection version
-1. Use the `akka.japi.Pair` class to return tuples
+1. Use the `org.apache.pekko.japi.Pair` class to return tuples
1. If the underlying Scala code requires an `ExecutionContext`, make the Java API take an `Executor` and use
`ExecutionContext.fromExecutor(executor)` for conversion.
@@ -559,7 +559,7 @@ Scala has proven the most viable way to do it, as long as you keep the following
| `scala.collection.immutable.Seq[T]` | `java.util.List<T>` |
| `scala.concurrent.Future[T]` | `java.util.concurrent.CompletionStage<T>` |
| `scala.concurrent.Promise[T]` | `java.util.concurrent.CompletableFuture<T>` |
-| `scala.concurrent.duration.FiniteDuration` | `java.time.Duration` (use `akka.util.JavaDurationConverters`) |
+| `scala.concurrent.duration.FiniteDuration` | `java.time.Duration` (use `org.apache.pekko.util.JavaDurationConverters`) |
| `T => Unit` | `java.util.function.Consumer<T>` |
| `() => R` (`scala.Function0[R]`) | `java.util.function.Supplier<R>` |
| `T => R` (`scala.Function1[T, R]`) | `java.util.function.Function<T, R>` |
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@pekko.apache.org
For additional commands, e-mail: commits-help@pekko.apache.org