FINERACT-1607: Improve documentation on Cucumber usage

build.gradle

@@ -96,8 +96,7 @@ allprojects  {
 
     jgitver {
         strategy 'PATTERN'
-        versionPattern '${M}.${m}.${p}-${meta.GIT_SHA1_8}'
-        // versionPattern '${v}'
+        versionPattern ( project.hasProperty('fineract.release.version') ? '${v}' : '${M}.${m}.${p}-${meta.GIT_SHA1_8}' )
     }
 
     repositories {
@@ -265,6 +264,7 @@ configure(project.fineractJavaProjects) {
     apply plugin: 'se.thinkcode.cucumber-runner'
     apply from: "${rootDir}/buildSrc/src/main/groovy/org.apache.fineract.dependencies.gradle"
 
+    group = 'org.apache.fineract'
 
     /* define the valid syntax level for source files */
     sourceCompatibility = JavaVersion.VERSION_17
@@ -590,10 +590,15 @@ configure(project.fineractJavaProjects) {
 
 configure(project.fineractPublishProjects) {
     apply plugin: 'maven-publish'
+    apply plugin: 'signing'
 
     publishing {
         publications {
             mavenJava(MavenPublication) {
+                groupId 'org.apache.fineract'
+                artifactId project.name
+                version "${project.version}-SNAPSHOT"
+
                 from components.java
 
                 versionMapping {
@@ -606,7 +611,7 @@ configure(project.fineractPublishProjects) {
                 }
 
                 pom {
-                    name = 'Fineract'
+                    name = "Fineract: ${project.name}"
                     description = 'A secure, multi-tenanted microfinance platform'
                     url = 'https://fineract.apache.org'
                     licenses {
@@ -624,7 +629,23 @@ configure(project.fineractPublishProjects) {
             }
         }
 
-        // TODO FINERACT-1102: Actually use this to deploy to ASF (Apache Software Foundation) Nexus Maven Repository
+        repositories {
+            def releaseUrl = 'https://repository.apache.org/content/repositories/releases'
+            def stagingUrl = 'https://repository.apache.org/content/repositories/snapshots'
+
+            maven {
+                name 'apache'
+                url hasProperty('fineract.release.version') ? releaseUrl : stagingUrl
+                credentials {
+                    username "${findProperty('fineract.config.username')}"
+                    password "${findProperty('fineract.config.password')}"
+                }
+            }
+        }
+    }
+
+    signing {
+        sign publishing.publications.mavenJava
     }
 }
 

fineract-doc/src/docs/en/chapters/release/index.adoc

@@ -11,3 +11,5 @@ include::{diagramsdir}/release-schedule.puml[]
 include::configuration.adoc[leveloffset=+1]
 
 include::process.adoc[leveloffset=+1]
+
+include::publish.adoc[leveloffset=+1]

fineract-doc/src/docs/en/chapters/release/publish.adoc

@@ -0,0 +1,32 @@
+= Publish Release Artifacts
+
+NOTE: More on releases at the ASF see https://www.apache.org/legal/release-policy.html#distribute-raw-artifact
+
+== Requirements
+
+You need to have your GPG keypairs properly set up. The JAR release artifacts (currently only `fineract-client`) are signed with a Gradle plugin just before being uploaded to the Maven repository. Please make sure that the following properties are set in your private `gradle.properties` file in your home folder:
+
+[source,properties]
+----
+signing.keyId=7890ABCD
+signing.password=*****
+signing.secretKeyRingFile=~/.gnupg/secring.gpg
+----
+
+This is quite similiar to the Fineract release plugin properties for GPG. In one of the next release we'll merge these two setups to avoid this duplicated configuration.
+
+== Maven Repository
+
+We are using the ASF's official https://repository.apache.org[Nexus Maven repository] to publish our snapshot and release artifacts.
+
+NOTE: Find more information at https://infra.apache.org/publishing-maven-artifacts.html
+
+== NPM Registry
+
+For convenience we will be using Github Packages to publish Fineract's Typescript API client.
+
+TBD
+
+== Docker Hub
+
+TBD

fineract-doc/src/docs/en/chapters/testing/cucumber-cheatsheet.adoc

@@ -1,3 +1,109 @@
-= Cheatsheet
+= Cucumber Cheatsheet
 
-TBD
+Cucumber is a test framework based on Behavior-Driven Development (BDD). Tests are written in plain text with very basic syntax rules. These rules form a mini language that is called Gherkin.
+
+A specification resembles spoken language. This makes it ideal for use with non-technical people that have domain specific knowledge. The emphasis of Cucumber lies on finding examples to describe your test cases. The few keywords and language rules are easy to explain to anyone (compared JUnit for example).
+
+== Keywords
+
+The Gherkin language has the following keywords:
+
+* `Feature`
+* `Rule`
+* `Scenario Outline` or `Scenario Template`
+* `Example` or `Scenario`
+* `Examples` or `Scenarios`
+* `Background`
+* `Given`
+* `And`
+* `But`
+* `When`
+* `Then`
+
+There are a couple of additional signs used in Gherkin:
+
+* `|` is as column delimiters in `Examples` tables
+* with `@` you can assign any kind of tags to categorize the specs (or e.g. relate them to certain Jira tickets)
+* `#` is used to indicate line comments
+
+IMPORTANT: The tag `@ignore` is used to skip tests. This is a somewhat arbitrary choice (we could use any other tag to indicate temporarily disabled tests).
+
+Each non-empty line of a test specification needs to start with one of these keywords. The text blocks that follows the keywords are mapped to so called step definitions that contain the actual test code.
+
+A typical Cucumber test specification written in Gherkin looks like this:
+
+[source,gherkin,subs="attributes+,+macros"]
+----
+include::{rootdir}/fineract-provider/src/test/resources/features/template/template.service.feature[lines=19..]
+----
+
+The corresponding step definitions would look like this:
+
+[source,java,subs="attributes+,+macros"]
+----
+include::{rootdir}/fineract-provider/src/test/java/org/apache/fineract/template/service/TemplateServiceStepDefinitions.java[lines=19..]
+----
+
+NOTE: This example is an actual test specification that you can find in the `fineract-provider` module.
+
+=== Feature
+
+This keyword is used to group scenarios and to group related scenarios. All Gherkin specifications must start with the word `Feature`.
+
+=== Descriptions
+
+A description is any non-empty line that doesn't start with a keyword. Descriptions can be placed under the keywords:
+
+* `Feature`
+* `Rule`
+* `Background`
+* `Example`/`Scenario`
+* `Scenario Outline`
+
+=== Rule
+
+Rule is used to group multiple related scenarios together.
+
+=== Example/Scenario
+
+This is the important part of the specification as it should describe the business logic in more detail with the usage of steps (usually `Given`, `When`, `Then`)
+
+=== Steps
+
+TBD
+
+=== Given
+
+TBD
+
+=== When
+
+TBD
+
+=== Then
+
+TBD
+
+=== And, But
+
+TBD
+
+=== Background
+
+TBD
+
+=== Scenario Outline
+
+TBD
+
+=== Examples/Tables
+
+TBD
+
+== Outlook
+
+As a proof of concept we've converted all unit tests in `fineract-provider` into Cucumber tests. The more interesting part starts when we'll attack the integration tests with over 400 mostly business logic related tests. These tests fit very well in Cucumber's test specification structure (a lot of _if-then-else_ or in Gherkin: _Given-When-Then_). Migrating all tests will take a while, but we would already recommend trying to implement tests as Cucumber specifications. It should be relatively easy to convert these tests into the new syntax.
+
+Hopefully this will motivate even more people from the broader Fineract community to participate in the project by sharing their domain specific knowledge as Cucumber specifications. Specifications are written in Englisch (although not a technical requirement).
+
+NOTE: Have a look at the specifications in `fineract-provider` for an initial inspiration. For more information please see https://cucumber.io/docs

fineract-doc/src/docs/en/chapters/testing/cucumber-introduction.adoc

@@ -1,3 +0,0 @@
-= Introduction
-
-TBD

fineract-doc/src/docs/en/chapters/testing/cucumber-tutorial.adoc

@@ -1,3 +0,0 @@
-= Tutorial
-
-TBD

fineract-doc/src/docs/en/chapters/testing/cucumber.adoc

@@ -3,8 +3,4 @@
 
 TBD
 
-include::cucumber-introduction.adoc[leveloffset=+1]
-
-include::cucumber-tutorial.adoc[leveloffset=+1]
-
 include::cucumber-cheatsheet.adoc[leveloffset=+1]

fineract-doc/src/docs/en/index.adoc

@@ -39,16 +39,16 @@ include::chapters/development/index.adoc[leveloffset=+1]
 
 include::chapters/security/index.adoc[leveloffset=+1]
 
-include::{rootdir}/fineract-client/build/generated/asciidoc/index.adoc[leveloffset=+1]
-
-include::chapters/sdk/index.adoc[leveloffset=+1]
-
 include::chapters/testing/index.adoc[leveloffset=+1]
 
 include::chapters/documentation/index.adoc[leveloffset=+1]
 
 include::chapters/release/index.adoc[leveloffset=+1]
 
+include::chapters/sdk/index.adoc[leveloffset=+1]
+
+include::{rootdir}/fineract-client/build/generated/asciidoc/index.adoc[leveloffset=+1]
+
 include::faq.adoc[leveloffset=+1]
 
 include::glossary.adoc[leveloffset=+1]

fineract-provider/build.gradle

@@ -51,11 +51,11 @@ compileJava.doLast {
 import org.apache.tools.ant.filters.ReplaceTokens
 
 task prepareInputYaml {
-    outputs.file('config/swagger/fineract-input.yaml')
+    outputs.file("${buildDir}/tmp/swagger/fineract-input.yaml")
 
     doLast {
         copy {
-            from file('config/swagger/fineract-input.yaml.template')
+            from file("${projectDir}/config/swagger/fineract-input.yaml.template")
             into file("${buildDir}/tmp/swagger")
             rename { String filename -> return 'fineract-input.yaml' }
             filter(ReplaceTokens, tokens: [VERSION: "${project.version}".toString()])
@@ -323,6 +323,7 @@ jar.dependsOn resolve
 test.dependsOn resolve
 checkstyleMain.dependsOn resolve
 checkstyleTest.dependsOn resolve
+rat.dependsOn prepareInputYaml
 spotbugsTest.dependsOn resolve
 compileTestJava.dependsOn ':fineract-client:processResources'
 bootJarMainClassName.dependsOn resolve

fineract-provider/src/test/resources/features/accounting/accounting.common.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: Accounting Service
 
   @accounting

fineract-provider/src/test/resources/features/batch/batch.builder.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: Batch Service
 
   @batch

fineract-provider/src/test/resources/features/commands/commands.provider.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: Commands Service
 
   @template

fineract-provider/src/test/resources/features/infrastructure/infrastructure.classpath.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: Classpath duplicates
 
   @infrastructure

fineract-provider/src/test/resources/features/infrastructure/infrastructure.core.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: Core Infrastructure
 
   @infrastructure

fineract-provider/src/test/resources/features/infrastructure/infrastructure.security.utils.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: Security Utils Infrastructure
 
   @security

fineract-provider/src/test/resources/features/infrastructure/infrastructure.sqlbuilder.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: SQL Builder
 
   @sqlbuilder

fineract-provider/src/test/resources/features/mix/mix.report.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: MIX XBRL
 
   @mix

fineract-provider/src/test/resources/features/module/modules.example.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: Example Modules
 
   @modules

fineract-provider/src/test/resources/features/module/modules.service.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: Service Modules
 
   @modules

fineract-provider/src/test/resources/features/portfolio/loanproduct.validation.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: Loan Product Validation
 
   @loanproduct

fineract-provider/src/test/resources/features/template/template.service.feature

@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
 Feature: Template Service
 
   @template

gradle.properties

@@ -20,3 +20,4 @@ org.gradle.jvmargs=-Xmx2g --add-exports jdk.compiler/com.sun.tools.javac.api=ALL
 buildType=BUILD
 org.gradle.caching=true
 org.gradle.parallel=true
+org.gradle.logging.level=warn