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 <angusyo...@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
