(camel) branch main updated: (doc) Updated the contributing guide

[or...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

orpiske pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git


The following commit(s) were added to refs/heads/main by this push:
     new 96d2e789def (doc) Updated the contributing guide
96d2e789def is described below

commit 96d2e789defdf07894abb164715933235f9aaca1
Author: Otavio Rodolfo Piske <an...@gmail.com>
AuthorDate: Thu Feb 8 15:19:52 2024 +0100

    (doc) Updated the contributing guide
    
    - Added a Testing Camel page
    - Updated building details
    - Added basic information about adjusting the code when required
    - Fixed outdated links
---
 docs/main/modules/contributing/pages/building.adoc |  29 ++++++
 docs/main/modules/contributing/pages/index.adoc    |  55 +++++++++--
 .../modules/contributing/pages/testing-camel.adoc  | 110 +++++++++++++++++++++
 3 files changed, 187 insertions(+), 7 deletions(-)

diff --git a/docs/main/modules/contributing/pages/building.adoc b/docs/main/modules/contributing/pages/building.adoc
index 43d9a980cb2..1a15528e905 100644
--- a/docs/main/modules/contributing/pages/building.adoc
+++ b/docs/main/modules/contributing/pages/building.adoc
@@ -109,3 +109,32 @@ mvn -Pfastinstall,deploy clean install
 ------------------------------------------
 
 The build with deployment will build source jars, javadoc and other artifacts needed for deployment.
+
+== Verifying the coding style
+
+== Camel 4.x
+
+Starting with Camel 4.0.0, our build system will automatically verify and format the code when doing a full build or
+when running certain phases that trigger it (i.e.; when running `mvn verify`).
+
+== Camel 3.x
+
+Apache Camel source code uses a coding style/format that can be verified for compliance using the "checkstyle" plugin.
+
+To enable source style checking, build Camel with the `-Psourcecheck` profile:
+
+[source,bash]
+----
+mvn clean install -Psourcecheck
+----
+
+Please remember to run this check on your code changes before submitting a patch or GitHub PR. You do not need to run this against the entire project, but only in the modules you modified.
+
+
+For instance, if you do some code changes in the camel-ftp component, following which you can run the check from within this directory:
+
+[source,bash]
+----
+cd camel-ftp
+mvn clean install -Psourcecheck
+----
\ No newline at end of file
diff --git a/docs/main/modules/contributing/pages/index.adoc b/docs/main/modules/contributing/pages/index.adoc
index 797dc63c6c0..6b5740b434d 100644
--- a/docs/main/modules/contributing/pages/index.adoc
+++ b/docs/main/modules/contributing/pages/index.adoc
@@ -112,6 +112,7 @@ We recommend forking the code from the https://github.com/apache/camel/[camel Gi
 ----
 git clone https://github.com/your-github/camel.git
 cd camel
+git remote add upstream https://github.com/apache/camel.git
 ----
 
 Alternatively, if you are using the https://cli.github.com[GitHub CLI]:
@@ -242,12 +243,7 @@ CAMEL-9999: Some message goes here
 * When submitting a performance improvement, providing JMH test data as evidence or adding a JMH-based test on the https://github.com/apache/camel-performance-tests/[camel-performance-tests] repository is strongly recommended.
 * Be responsive, assume good intent and respect the https://www.apache.org/foundation/policies/conduct.html[Code of Conduct]
 * When contributing components, please make sure that their dependencies are available in the https://search.maven.org[Maven Central]. We do not accept contributions if the dependencies are not publicly available.
-* Tests must follow the following naming convention:
-** `*Test.java` (i.e.: MyComponentTest.java) for unit tests.
-** `*IT.java` (i.e.: MyComponentIT.java) for integration tests.
-** `*ManualTest.java` (i.e.: MyComponentManualTest.java) for manual tests.
-** Avoid `Thread.sleep` (they make our tests slow and unreliable)
-** To disable tests use JUnit's https://junit.org/junit5/docs/current/api/org.junit.jupiter.api/org/junit/jupiter/api/Disabled.html[@Disabled] annotation or one of its siblings (i.e.: `@DisabledIfSystemProperty` and others)
+* Do read the xref:testing-camel.adoc[Testing Camel] page to learn about naming convention and other practices that may be required
 
 Following these guidelines will help you in getting your contribution accepted.
 
@@ -270,7 +266,7 @@ The code will be tested automatically. The access to the build and test logs is
 
 === Submitting your changes via Patches
 
-=== Manual patch files
+==== Manual patch files
 
 For smaller patches, you may also submit a patch file instead of using a Pull Request. To do this:
 
@@ -294,6 +290,51 @@ or,
 git diff --no-prefix > patchfile.txt
 ----
 
+=== Adjusting your contribution
+
+The Apache Camel project uses Git to track changes and control the versions. Although it is a rather complex versioning system,
+there is a vast amount of https://git-scm.com/book/en/v2[material available on the web]. Some basic understanding of Git is
+necessary for contributing with Apache Camel.
+
+In some cases, the reviewers may ask for certain things involving Git to be done prior to merging your code.
+
+The sections below describe how to use the git command-line perform some of the tasks that reviewers may ask.
+
+[NOTE]
+====
+Some operations may also be done using the user interfaces provided by IDEs such as IntelliJ.
+====
+
+==== Rebase the code
+
+A common request is for the user to rebase the code. Reviewers typically ask for this when the HEAD (last commit) used for
+creating the contribution (i.e.; the code on your fork) is too outdated compared to the current version in the Camel upstream repository.
+
+You can usually do this by running the following set of commands:
+
+[source,bash]
+----
+# Checkout to the main branch
+git checkout main
+
+# Fetch the latest changes from main (make sure you have the upstream remote - check using the command git remote -v)
+git pull --rebase upstream main
+
+# Checkout the branch where you have your changes (replace your-branch with the branch you are working on)
+git rebase main your-branch
+----
+
+==== Edit the commit message
+
+[source,bash]
+----
+# Amend the commit. This opens the default text editor (usually vim) so you can write the commit message.
+git commit --amend
+
+# After saving the changes, push them to the repository (replace your-branch with the branch you are working on)
+git push -f origin your-branch
+----
+
 == Watching your Contribution
 
 === Continuous Integration
diff --git a/docs/main/modules/contributing/pages/testing-camel.adoc b/docs/main/modules/contributing/pages/testing-camel.adoc
new file mode 100644
index 00000000000..711a9c79860
--- /dev/null
+++ b/docs/main/modules/contributing/pages/testing-camel.adoc
@@ -0,0 +1,110 @@
+= Testing Camel
+
+== Basic testing
+
+After you have xref:building.adoc[Build] the code, you should test your changes. Our project follows http://maven.apache.org[Apache Maven] conventions for building and testing the code.
+
+The code base relies on the https://maven.apache.org/surefire/maven-surefire-plugin/[Maven Surefire Plugin] for running the unit tests and the https://maven.apache.org/surefire/maven-failsafe-plugin/[Maven Failsafe Plugin] for running the integration tests.
+
+To run the unit tests, use the following command:
+
+[source,bash]
+----
+mvn test
+----
+
+To run the integration tests, use the following command:
+
+[source,bash]
+----
+mvn verify
+----
+
+[NOTE]
+====
+The command `mvn verify` will also run the unit tests.
+====
+
+The set of tests executed may differ according to the platform, operating system and Java version used.
+
+[NOTE]
+====
+Our project has automation that will automatically test contributions made via pull-requests. Nonetheless, it's always better to ensure your contribution works before sending it.
+====
+
+=== Unit Tests versus Integration Tests
+
+Since Camel is an integration framework, which by definition depends on external systems, tools and platforms to produce or consume data, the distinction of unit/integration tests may not be so clear.
+
+Tests must follow the following naming convention:
+
+* `*Test.java` (i.e.: MyComponentTest.java) for unit tests.
+* `*IT.java` (i.e.: MyComponentIT.java) for integration tests.
+* `*ManualTest.java` (i.e.: MyComponentManualTest.java) for manual tests.
+
+== Implementing new tests
+
+If you need to implement tests for your changes, which is highly recommended, you will probably need to handle three separate things:
+
+1. writing testable code
+2. writing Apache Camel tests
+3. simulating the infrastructure
+
+=== Writing testable code
+
+Camel has multiple features to simplify testing. You can use those features to maximize your ability to test your code contribution.
+The xref:manual::testing.adoc[Testing] page in the User Manual provides detailed information and examples for writing Camel tests.
+
+[NOTE]
+====
+Although the testing information on the User Manual is aimed at Camel users, the same features are also used to test Camel itself.
+====
+
+=== Writing Apache Camel tests
+
+Naturally, there is no rule of thumb for how the code changes, and test logic should be written. There are, however, a few things
+to avoid and good practices to follow when writing tests for Apache Camel.
+
+*Things to avoid*:
+
+- Calling `Thread.sleep` in tests
+- Disabling tests without providing a reason (when needed, create a Jira ticket and use that as part of the reason string)
+- Writing large tests
+- Writing assertions without a fail message
+- Writing custom profiles for enabling/disabling tests
+
+*Good things to do*:
+
+- Use the http://www.awaitility.org/[Awaitility] library
+- Writing small tests
+- Coordinating test execution using https://junit.org/junit5/docs/current/user-guide/#writing-tests-test-execution-order[JUnit's @Order annotation]
+- Providing fail messages for assertions
+
+=== Simulating the test infrastructure
+
+In many cases, it may be necessary to access or simulate access to a certain infrastructure to execute the tests.
+
+As an integration framework, by nature, Camel needs to interact with other systems to execute its tests.
+
+[NOTE]
+====
+Typical assumptions made when writing tests for user-level applications, don't necessarily translate well to Camel.
+In many cases, it is necessary to evaluate the specific needs and requirements of each component.
+For instance, assumptions about whether it's OK or not to reuse resources, whether data ordering matters, and a lot more have to be evaluated per-component.
+====
+
+Camel has a growing library of reusable components to help providing the xref:manual::test-infra.adoc[test infra structure].
+
+These components are located in the test-infra module and provide support for simulating message brokers, cloud environments, databases, and much more.
+
+Using these components is usually as simple as registering them as JUnit 5 extensions:
+
+[source,java]
+----
+@RegisterExtension
+static NatsService service = NatsServiceFactory.createService();
+----
+
+Then you can access the service by using the methods and properties provided by the services. This varies according to each service.
+
+If you need to implement a new test-infra service, check the xref:manual::test-infra.adoc[test infra structure] documentation for additional details.
\ No newline at end of file