|
| 1 | +# Contributing Guidelines |
| 2 | + |
| 3 | +First of all, thank you for having the interest in contributing to this project! |
| 4 | + |
| 5 | +## Found a bug? |
| 6 | + |
| 7 | +Please create an issue describing the following: |
| 8 | + |
| 9 | +- The version the bug was discovered. |
| 10 | +- A scenario to reproduce the bug. |
| 11 | + |
| 12 | +## Enhancement ideas? |
| 13 | + |
| 14 | +Got an idea to enhance the library? Please feel free to create an issue describing the feature proposal. Any ideas are welcome! :) |
| 15 | + |
| 16 | +## Build |
| 17 | + |
| 18 | +The project uses Java 11 as runtime for Gradle but compiles source code to Java 8. |
| 19 | + |
| 20 | +To build the project, run the command: |
| 21 | + |
| 22 | +```sh |
| 23 | +./gradlew clean build |
| 24 | +``` |
| 25 | + |
| 26 | +To create reports, run the commands: |
| 27 | + |
| 28 | +```sh |
| 29 | +./gradlew clean build testAggregateTestReport |
| 30 | +``` |
| 31 | + |
| 32 | +```sh |
| 33 | +./gradlew clean build testCodeCoverageReport |
| 34 | +``` |
| 35 | + |
| 36 | +Tests are run in multiple JVM runtimes. By default, it is run in LTS versions (succeeding the version used in source compilation) + the latest released non-LTS version. Test runtimes are overrideable by setting the `ADDITIONAL_TEST_RUNS_ON_JVM_VERSIONS` environment variable or `additionalTestRunsOnJvmVersions` system property e.g. `ADDITIONAL_TEST_RUNS_ON_JVM_VERSIONS=8,17,18` / `additionalTestRunsOnJvmVersions=8,17,18`. |
| 37 | + |
| 38 | +## Development Guidelines |
| 39 | + |
| 40 | +### Unit Test Structure |
| 41 | + |
| 42 | +Unit tests in this project follow a specific structure. |
| 43 | + |
| 44 | +- Classes must have a corresponding test class i.e. `MapResolver` -> `MapResolverTests`. The test class must be in the exact same java package as the class it corresponds to. |
| 45 | +- Test classes are nested in structure. Each method in the class under test must have a corresponding `@Nested` test class. Each `@Nested` test class must test scenarios that is supported by the method it corresponds to. |
| 46 | + |
| 47 | + ```java |
| 48 | + // Class under test: io.github.joeljeremy7.externalizedproperties.resolver.my.MyResolver |
| 49 | + class MyResolver implements Resolver { |
| 50 | + public MyResolver(...) { |
| 51 | + ... |
| 52 | + } |
| 53 | + |
| 54 | + public Optional<String> resolve(InvocationContext context, String propertyName) { |
| 55 | + ... |
| 56 | + } |
| 57 | + |
| 58 | + public String someOtherMethod(...) { |
| 59 | + ... |
| 60 | + } |
| 61 | + |
| 62 | + public static class Builder { |
| 63 | + ... |
| 64 | + public MyResolver build() { |
| 65 | + ... |
| 66 | + } |
| 67 | + } |
| 68 | + } |
| 69 | + |
| 70 | + // Test class: io.github.joeljeremy7.externalizedproperties.resolver.my.MyResolverTests |
| 71 | + class MyResolverTests { |
| 72 | + @Nested |
| 73 | + class Constructor { |
| 74 | + // @Test methods here... |
| 75 | + } |
| 76 | + |
| 77 | + @Nested |
| 78 | + class ResolveMethod { |
| 79 | + // @Test methods here... |
| 80 | + } |
| 81 | + |
| 82 | + @Nested |
| 83 | + class SomeOtherMethod { |
| 84 | + // @Test methods here... |
| 85 | + } |
| 86 | + |
| 87 | + // Nested class must also have corresponding test classes |
| 88 | + @Nested |
| 89 | + class BuilderTests { |
| 90 | + ... |
| 91 | + @Nested |
| 92 | + class BuildMethod { |
| 93 | + // @Test methods here... |
| 94 | + } |
| 95 | + } |
| 96 | + } |
| 97 | + ``` |
0 commit comments