As a general rule, the style and formatting of commit messages should follow the guidelines in How to Write a Git Commit Message.
In addition, any commit that is related to an existing issue must reference the issue. For example, if a commit in a pull request addresses issue #999, it must contain the following at the bottom of the commit message.
Issue: #999
Our Definition of Done offers some guidelines on what we expect from a pull request. Feel free to open a pull request that does not fulfill all criteria, e.g. to discuss a certain change before polishing it, but please be aware that we will only merge it in case the DoD is met.
Please add the following lines to your pull request description:
--- I hereby agree to the terms of the JUnit Contributor License Agreement.
Whenever an acronym is included as part of a type name or method name, keep the first letter of the acronym uppercase and use lowercase for the rest of the acronym. Otherwise, it becomes impossible to perform camel-cased searches in IDEs, and it becomes potentially very difficult for mere humans to read or reason about the element without reading documentation (if documentation even exists).
Consider for example a use case needing to support an HTTP URL. Calling the method getHTTPURL()
is absolutely horrible in terms of usability; whereas, getHttpUrl()
is great in terms of usability. The same applies for types HTTPURLProvider
vs HttpUrlProvider
, etc.
Whenever an acronym is included as part of a field name or parameter name:
String url;
.String defaultUrl;
.Code formatting is enforced using the Spotless Gradle plugin. You can use gradle spotlessApply
to format new code and add missing license headers to source files. Formatter and import order settings for Eclipse are available in the repository under src/eclipse/junit-eclipse-formatter-settings.xml and src/eclipse/junit-eclipse.importorder, respectively. For IntelliJ IDEA there's a plugin you can use in conjunction with the Eclipse settings.
It is forbidden to use wildcard imports (e.g., import static org.junit.jupiter.api.Assertions.*;
) in Java code.
Text in *.adoc
and *.md
files should be wrapped at 90 characters whenever technically possible.
In multi-line bullet point entries, subsequent lines should be indented.
Use American English spelling rules when writing documentation as well as for code -- class names, method names, variable names, etc.
<p>
on the same line as the first line in a new paragraph and precede <p>
with a blank line.{@code foo}
over <code>foo</code>
.{@literal @}
) over HTML entities.@since ...
annotation.@since 5.0
instead of @since 5.0.0
.@author
tags. Instead, contributors are listed on GitHub.See ExtensionContext
and ParameterContext
for example Javadoc.
Tests
suffix.TestCase
suffix.org.junit.jupiter.api.Assertions
wherever possible.org.junit.Assert
or junit.framework.Assert
.Logger
façade provided via the JUnit LoggerFactory.SEVERE
, Log4J: ERROR
): extra information (in addition to an Exception) about errors that will halt executionWARNING
, Log4J: WARN
): potential usage or configuration errors that should not halt executionINFO
, Log4J: INFO
): information the users might want to know but not by defaultCONFIG
, Log4J: CONFIG
): information related to configuration of the system (Example: ServiceLoaderTestEngineRegistry
logs IDs of discovered engines)FINE
, Log4J: DEBUG
)FINER
, Log4J: TRACE
)Publicly available interfaces, classes and methods have a defined lifecycle which is described in detail in the User Guide. This process is using the @API
annotation from API Guardian. It also describes the deprecation process followed for API items.
To deprecate an item:
@API.status
to DEPRECATED
.@API.since
. Please note since
describes the version when the status was changed and not the introduction of the element.@Deprecated
Java annotation on the item.@deprecated
JavaDoc tag to describe the deprecation, and refer to an eventual replacement.@SuppressWarnings("deprecation")
to make the build pass.