Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FINERACT-2023: Improve contributor's guide #3765

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
493 changes: 12 additions & 481 deletions README.md

Large diffs are not rendered by default.

55 changes: 55 additions & 0 deletions fineract-doc/src/docs/en/chapters/contributing/contributing.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
= Getting Started Guide

Fineract is maintained by a large group of contributors, just like you! Getting started with a mature platform like Fineract can be daunting for new contributors. This guide will help you through your first contribution!

== Read FAQ
** First, have a look at the FAQ on our Wiki link:https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=91554327[here]
** Is this Mifos?
*** The Mifos Initiative, contributed the code that forms the basis of fineract, and it remains involved with a number of front end implementations and other systems that run "on top of" fineract, including a payment hub and API management. Many of the developers are on both listservs. However, Mifos as a separate non-Apache entity is not part of the project as it is considered a "vendor".

== Communication Channels

** Join our Slack Community and subscribe to our Mailing lists.
*** link:mailto:dev-subscribe@fineract.apache.org[Apache Fineract Developers List]: Send a blank email to dev-subscribe@fineract.apache.org
*** link:https://the-asf.slack.com/archives/C4QPZURQQ[Apache Fineract Slack Channel]
*** link:https://bit.ly/mifos-slack[Mifos Slack Channel]: There's an active community of developers on the Mifos Slack channel, and you may consider joining it.

== Communication Guidelines

The Apache Software Foundation (ASF) adage is: *"If it didn't happen on the list, then it didn't happen."*

All communications that happen off-list should be brought back to the list. Normally, you should not discuss things off list, but if you do, then you should summarize it on list.

Example, if you discuss something "off list" on a slack channel, especially one at Mifos slack, then you should summarize that discussion on the dev list (dev@fineract.apache.org). By summarizing it, you are bringing into the official record of the project.

== Dev environment setup:

Follow link:../development/dev-env-setup.adoc[these] steps to set up your dev environment.

== Identify something to work on

* Browse existing link:https://issues.apache.org/jira/browse/FINERACT-2055?jql=project%20%3D%20FINERACT%20ORDER%20BY%20created%20DESC[issues]
** Filter by tags - "volunteer", "gsoc", "new contributor", etc.
* Browse link:https://mifosforge.jira.com/wiki/spaces/RES/pages/3532095546/Google+Summer+of+Code+2024+Ideas[GSoC projects]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We cannot point to an external project

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.


== Open your first PR

* When you've found an issue to work on, add a comment on the jira issue to say that you're looking to avoid conflicting work.
* Follow our coding conventions through link:https://github.com/apache/fineract?tab=readme-ov-file#checkstyle-and-spotless[spotless].
* Follow our link:https://github.com/apache/fineract?tab=readme-ov-file#error-handling-guidelines[error handling] and link:https://github.com/apache/fineract?tab=readme-ov-file#logging-guidelines[logging] guidelines.
* Ensure that your changes are link:https://github.com/apache/fineract?tab=readme-ov-file#instructions-how-to-run-and-debug-in-eclipse-ide[tested].
* Read our link:https://github.com/apache/fineract?tab=readme-ov-file#merge-strategy[merge strategy] guidelines before creating a Pull Request.
* Ensure that your pull request follows link:https://github.com/apache/fineract?tab=readme-ov-file#pull-requests[these] guidelines.

== What's next?

link:https://cwiki.apache.org/confluence/display/FINERACT/Becoming+a+Committer[Becoming a Committer] documents the process through which you can become a committer in this project.

== Useful links

* Apache Fineract link:https://fineract.apache.org/[website].
* Apache Fineract link:https://cwiki.apache.org/confluence/display/FINERACT/Fineract+Home[wiki].
* Understand the major architectural decisions in the platform link:https://fineract.apache.org/docs/current/#_architecture[here].
* Understand how you can configure deployments link:https://fineract.apache.org/docs/current/#_deployment[here].

Note also our link:https://github.com/apache/fineract/blob/develop/CODE_OF_CONDUCT.md[Code of Conduct].
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
= GORVENANCE AND POLICIES

link:https://cwiki.apache.org/confluence/display/FINERACT/Becoming+a+Committer[Becoming a Committer]
documents the process through which you can become a committer in this project.
8 changes: 8 additions & 0 deletions fineract-doc/src/docs/en/chapters/contributing/index.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
= Contributing

The Apache Fineract community welcomes contributors who want to support the Fineract technology. Our community builds everything from this website, to the Fineract code to documentation and best practices information.

We especially welcome additions and corrections to the documentation, wiki, and website to improve the user experience. Bug reports and fixes and additions to the Apache Fineract code are welcome. Helping users learn best practices also earns good karma in our community.

include::contributing.adoc[leveloffset=+1]
include::governance.adoc[leveloffset=+1]
5 changes: 5 additions & 0 deletions fineract-doc/src/docs/en/chapters/demos/online-demos.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
= ONLINE DEMOS

* link:https://www.fineract.dev[fineract.dev] always runs the latest version of this code
* link:https://demo.mifos.io[demo.mifos.io] A demo account is provided for users to experience the functionality of the Community App. Users can use "mifos" for USERNAME and "password" for PASSWORD (without quotation marks).
* link:https://www.youtube.com/watch?v=FlVd-0YAo6c[Swagger-UI Demo video] This is a demo video for Swagger-UI documentation, more information link:https://github.com/apache/fineract#swagger-ui-documentation[here].
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
= VIDEO DEMONSTRATION

Apache Fineract / Mifos X Demo (November 2016) - <https://www.youtube.com/watch?v=h61g9TptMBo>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is really old. Let's delete or create a new one. I think it should be a demo of the APIs

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jdailey Done.

Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
= API CLIENTS (Web UIs, Mobile, etc.)

* https://github.com/openMF/community-app/ is the "traditional" Reference Client App Web UI for the API offered by this project
* https://github.com/openMF/web-app is the next generation UI rewrite also using this project's API
* https://github.com/openMF/android-client is an Android Mobile App client for this project's API
* https://github.com/openMF has more related proejcts
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
= API Documentation

include::platform-api.adoc[leveloffset=+1]
include::api-clients.adoc[leveloffset=+1]
include::swagger-ui-documentation.adoc[leveloffset=+1]
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
= APACHE FINERACT PLATFORM API

The API for Fineract is documented in link:../fineract-provider/src/main/resources/static/api-docs/apiLive.htm[apiLive.htm], and the [apiLive.htm can be viewed on Fineract.dev](https://fineract.apache.org/legacy-docs/apiLive.htm "API Documentation"). If you have your own Fineract instance running, you can find this documentation under [/fineract-provider/api-docs/apiLive.htm](https://localhost:8443/fineract-provider/api-docs/apiLive.htm).

The Swagger documentation (work in progress; see link:https://issues.apache.org/jira/browse/FINERACT-733[FINERACT-733]) can be accessed under link:https://localhost:8443/fineract-provider/swagger-ui/index.html[/fineract-provider/swagger-ui/index.html] and link:https://demo.fineract.dev/fineract-provider/swagger-ui/index.html[live Swagger UI here on Fineract.dev].

Apache Fineract supports client code generation using link:https://github.com/swagger-api/swagger-codegen[Swagger Codegen] based on the link:https://swagger.io/specification/[OpenAPI Specification]. For more instructions on how to generate the client code, check link:../developers/swagger/client.md[docs/developers/swagger/client.md].
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
= SWAGGER UI DEMONSTRATION

We use Swagger-UI to generate and maintain our API documentation, you can see the demo video link:https://www.youtube.com/watch?v=FlVd-0YAo6c[here] or a live version
link:https://demo.fineract.dev/fineract-provider/swagger-ui/index.html[here]. If you interested to know more about Swagger-UI you can check their link:https://swagger.io/[website].
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
= Connection pool configuration

Please check `application.properties` to see which connection pool settings can be tweaked. The associated environment variables are prefixed with `FINERACT_HIKARI_*`. You can find more information about specific connection pool settings (Hikari) at https://github.com/brettwooldridge/HikariCP#configuration-knobs-baby

NOTE: we'll keep backwards compatibility until one of the next releases to ensure that things are working as expected. Environment variables prefixed `fineract_tenants_*` can still be used to configure the database connection, but we strongly encourage using `FINERACT_HIKARI_*` with more options.
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
= Custom Configuration for Fineract

include::security-configuration.adoc[leveloffset=+1]

include::connection-pool-configuration.adoc[leveloffset=+1]

include::ssl-configuration.adoc[leveloffset=+1]

include::tomcat-configuration.adoc[leveloffset=+1]

include::message-broker-configuration.adoc[leveloffset=+1]
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
= INSTRUCTIONS: How to enable External Message Broker (ActiveMQ or Apache Kafka)

There are two use-cases where external message broker is needed:
- External Business Events / Reliable Event Framework
- Executing Partitioned Spring Batch Jobs

External Events are business events, e.g.: `ClientCreated`, which might be important for third party systems. Apache Fineract supports ActiveMQ (or other JMS compliant brokers) and Apache Kafka endpoints for sending out Business Events. By default, they are not emitted.

In case of a large deployment with millions of accounts, the Close of Business Day Spring Batch job may run several hours. In order to speed up this task, remote partitioning of the job is supported. The Manager node partitions (breaks up) the COB job into smaller pieces (sub tasks) which then can be executed on multiple Worker nodes in parallel. The worker nodes are notified either by ActiveMQ or Kafka regarding their new sub tasks.

== Active MQ

JMS based messaging is disabled by default. In `docker-compose-postgresql-activemq.yml` an example is shown where ActiveMQ is enabled. In that configuration one Spring Batch Manager instance and two Spring Batch Worker instances are created.
Spring based events should be disabled and jms based event handling should be enabled. Furthermore, proper broker JMS URL should be configured.


FINERACT_REMOTE_JOB_MESSAGE_HANDLER_JMS_ENABLED=true
FINERACT_REMOTE_JOB_MESSAGE_HANDLER_SPRING_EVENTS_ENABLED=false
FINERACT_REMOTE_JOB_MESSAGE_HANDLER_JMS_BROKER_URL=tcp://activemq:61616


For additional ActiveMQ related configuration please take a look to the `application.properties` where the supported configuration parameters are listed with their default values.

== Kafka

Kafka support also disabled by default. In `docker-compose-postgresql-kafka.yml` an example is shown where self-hosted Kafka is enabled for both External Events and Spring Batch Remote Job execution.

During the development Fineract was tested with PLAINTEXT Kafka brokers without authentication and with AWS MSK using IAM authentication. The extra link:https://github.com/aws/aws-msk-iam-auth/releases[jar file] required for IAM authentication is already added to the classpath.
An example MSK setup can be found in `docker-compose-postgresql-kafka-msk.yml`.

The full list of supported Kafka related properties are documented here: https://fineract.apache.org/docs/current/
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
= SECURITY

NOTE: The HTTP Basic and OAuth2 authentication schemes are mutually exclusive. You can't enable them both at the same time. Fineract checks these settings on startup and will fail if more than one authentication scheme is enabled.

== HTTP Basic Authentication

By default Fineract is configured with a HTTP Basic Authentication scheme, so you actually don't have to do anything if you want to use it. But if you would like to explicitly choose this authentication scheme then there are two ways to enable it:

1. Use environment variables (best choice if you run with Docker Compose):

FINERACT_SECURITY_BASICAUTH_ENABLED=true
FINERACT_SECURITY_OAUTH_ENABLED=false

2. Use JVM parameters (best choice if you run the Spring Boot JAR):

java -Dfineract.security.basicauth.enabled=true -Dfineract.security.oauth.enabled=false -jar fineract-provider.jar


== OAuth2 AUTHENTICATION

There is also an OAuth2 authentication scheme available. Again, two ways to enable it:

1. Use environment variables (best choice if you run with Docker Compose):

FINERACT_SECURITY_BASICAUTH_ENABLED=false
FINERACT_SECURITY_OAUTH_ENABLED=true

2. Use JVM parameters (best choice if you run the Spring Boot JAR):

java -Dfineract.security.basicauth.enabled=false -Dfineract.security.oauth.enabled=true -jar fineract-provider.jar

== TWO FACTOR AUTHENTICATION (2FA)

You can also enable 2FA authentication. Depending on how you start Fineract add the following:

1. Use environment variable (best choice if you run with Docker Compose):

FINERACT_SECURITY_2FA_ENABLED=true

2. Use JVM parameter (best choice if you run the Spring Boot JAR):

-Dfineract.security.2fa.enabled=true
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
= SSL CONFIGURATION

Read also [the HTTPS related doc](fineract-doc/src/docs/en/deployment.adoc#https).

By default SSL is enabled, but all SSL related properties are now tunable. SSL can be turned off by setting the environment variable `FINERACT_SERVER_SSL_ENABLED` to false. If you do that then please make sure to also change the server port to `8080` via the variable `FINERACT_SERVER_PORT`, just for the sake of keeping the conventions.
You can choose now easily a different SSL keystore by setting `FINERACT_SERVER_SSL_KEY_STORE` with a path to a different (not embedded) keystore. The password can be set via `FINERACT_SERVER_SSL_KEY_STORE_PASSWORD`. See the `application.properties` file and the latest Spring Boot documentation (https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html) for more details.
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
= TOMCAT CONFIGURATION

Please refer to the `application.properties` and the official Spring Boot documentation (https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html) on how to do performance tuning for Tomcat. Note: you can set now the acceptable form POST size (default is 2MB) via environment variable `FINERACT_SERVER_TOMCAT_MAX_HTTP_FORM_POST_SIZE`.
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
= INSTRUCTIONS: How to run Apache RAT (Release Audit Tool)

1. Extract the archive file to your local directory.
2. Run `./gradlew rat`. A report will be generated under build/reports/rat/rat-report.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
= Checkstyle and Spotless

This project enforces its code conventions using link:../config/checkstyle/checkstyle.xml[checkstyle.xml] through Checkstyle and [fineract-formatting-preferences.xml](config/fineract-formatting-preferences.xml) through Spotless. They are configured to run automatically during the normal Gradle build, and fail if there are any violations detected. You can run the following command to automatically fix spotless violations:

./gradlew spotlessApply

Since some checks are present in both Checkstyle and Spotless, the same command can help you fix some of the Checkstyle violations (but not all, other Checkstyle violations need to fixed manually).

You can also check for Spotless violations (only; but normally don't have to, because the regular build full already includes this anyway):

./gradlew spotlessCheck

We recommend that you configure your favourite Java IDE to match those conventions. For Eclipse, you can go to
Window > Java > Code Style and import our link:../config/fineractdev-formatter.xml[config/fineractdev-formatter.xml] under formatter section and link:../config/fineractdev-cleanup.xml[config/fineractdev-cleanup.xml] under Clean up section. The same fineractdev-formatter.xml configuration file (that can be used in Eclipse IDE) is also used by Spotless to both check for violations and autoformat code on the CLI.
You could also use Checkstyle directly in your IDE (but you don't necessarily have to, it may just be more convenient for you). For Eclipse, use https://checkstyle.org/eclipse-cs/ and load our checkstyle.xml into it, for IntelliJ you can use link:https://plugins.jetbrains.com/plugin/1065-checkstyle-idea[CheckStyle-IDEA].
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
= Code Coverage Reports

The project uses Jacoco to measure unit tests code coverage, to generate a report run the following command:

./gradlew clean build jacocoTestReport

Generated reports can be found in build/code-coverage directory.
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
= Dependency Upgrades

This project uses a number of 3rd-party libraries, and this section provides some guidance for their updates. We have set-up link:https://renovate.whitesourcesoftware.com[Renovate's bot] to automatically raise Pull Requests for our review when new dependencies are available link:https://issues.apache.org/jira/browse/FINERACT-962[FINERACT-962].

Upgrades sometimes require package name changes. Changed code should ideally have test coverage.

Our `ClasspathHellDuplicatesCheckRuleTest` detects classes that appear in more than 1 JAR. If a version bump in link:https://github.com/search?q=repo%3Aapache%2Ffineract+filename%3Abuild.gradle&type=Code&ref=advsearch&l=&l=[`build.gradle`] causes changes in transitives dependencies, then you may have to add related `exclude` to our link:https://github.com/apache/fineract/search?q=dependencies.gradle[`dependencies.gradle`]. Running `./gradlew dependencies` helps to understand what is required.
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
= ERROR HANDLING GUIDELINES

* When catching exceptions, either rethrow them, or log them. Either way, include the root cause by using `catch (SomeException e)` and then either `throw AnotherException("..details..", e)` or `LOG.error("...context...", e)`.
* Completely empty catch blocks are VERY suspicous! Are you sure that you want to just "swallow" an exception? Really, 100% totally absolutely sure?? ;-) Such "normal exceptions which just happen sometimes but are actually not really errors" are almost always a bad idea, can be a performance issue, and typically are an indication of another problem - e.g. the use of a wrong API which throws an Exception for an expected condition, when really you would want to use another API that instead returns something empty or optional.
* In tests, you'll typically never catch exceptions, but just propagate them, with `@Test void testXYZ() throws SomeException, AnotherException`..., so that the test fails if the exception happens. Unless you actually really want to test for the occurence of a problem - in that case, use link:https://github.com/junit-team/junit4/wiki/Exception-testing[JUnit's Assert.assertThrows()] (but not `@Test(expected = SomeException.class)`).
* Never catch `NullPointerException` & Co.
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
= Fork

Make sure to disable Github Actions in your forked repository. See: https://github.com/orgs/community/discussions/26704
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
= Additonal Dev Guidelines and How-tos

include::apache-rat.adoc[leveloffset=+1]

include::checkstyle.adoc[leveloffset=+1]

include::integration-tests.adoc[leveloffset=+1]

include::coverage-reports.adoc[leveloffset=+1]

include::error-handling.adoc[leveloffset=+1]

include::logging.adoc[leveloffset=+1]

include::pull-requests.adoc[leveloffset=+1]

include::git-fork.adoc[leveloffset=+1]

include::merge-strategy.adoc[leveloffset=+1]

include::dependency-upgrades.adoc[leveloffset=+1]
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
= INSTRUCTIONS: How to execute Integration Tests

__Note that if this is the first time to access MySQL DB, then you may need to reset your password.__

Run the following commands:
1. `./gradlew createDB -PdbName=fineract_tenants`
1. `./gradlew createDB -PdbName=fineract_default`
1. `./gradlew clean test`
Loading