You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fineract.apache.org by ad...@apache.org on 2023/04/24 14:20:24 UTC
[fineract] branch develop updated: docs: Capitalize headings
This is an automated email from the ASF dual-hosted git repository.
adamsaghy pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/fineract.git
The following commit(s) were added to refs/heads/develop by this push:
new 0cd3ac1cb docs: Capitalize headings
0cd3ac1cb is described below
commit 0cd3ac1cb03be65ca565fb71e0dc1d3fdc4210a2
Author: David Kariuki <dk...@gmail.com>
AuthorDate: Sun Apr 23 02:13:38 2023 +0300
docs: Capitalize headings
Capitalize headings and add line breaks to improve on readability.
---
README.md | 78 +++++++++++++++++++++++++++++++--------------------------------
1 file changed, 39 insertions(+), 39 deletions(-)
diff --git a/README.md b/README.md
index 7b22f0530..0a642418c 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,7 @@ Apache Fineract: A Platform for Microfinance
============
[](https://validator.swagger.io/validator/debug?url=https://demo.fineract.dev/fineract-provider/swagger-ui/fineract.yaml) [](https://github.com/apache/fineract/actions/workflows/build.yml) [](ht [...]
+</b>
Fineract is a mature platform with open APIs that provides a reliable, robust, and affordable core banking solution for financial institutions offering services to the world’s 3 billion underbanked and unbanked.
@@ -12,16 +13,16 @@ to start contributing to this project in the online web-based IDE GitPod.io righ
(You may initially have to press F1 to Find Command and run "Java: Start Language Server".)
It's of course also possible to contribute with a "traditional" local development environment (see below).
-Community
+COMMUNITY
=========
If you are interested in contributing to this project, but perhaps don't quite know how and where to get started, please [join our developer mailing list](http://fineract.apache.org/#contribute), listen into our conversations, chime into threads, and just send us a "Hello!" introduction email; we're a friendly bunch, and look forward to hearing from you.
-Requirements
+REQUIREMENTS
============
-* Java >= 17 (Azul Zulu JVM is tested by our CI on GitHub Actions)
-* MariaDB 10.9
+* `Java >= 17` (Azul Zulu JVM is tested by our CI on GitHub Actions)
+* MariaDB `10.9`
You can run the required version of the database server in a container, instead of having to install it, like this:
@@ -31,14 +32,14 @@ and stop and destroy it like this:
docker rm -f mariadb-10.9
-Beware that this database container database keeps its state inside the container and not on the host filesystem. It is lost when you destroy (rm) this container. This is typically fine for development. See [Caveats: Where to Store Data on the database container documentation](https://hub.docker.com/_/mariadb) re. how to make it persistent instead of ephemeral.
+<br>Beware that this database container database keeps its state inside the container and not on the host filesystem. It is lost when you destroy (rm) this container. This is typically fine for development. See [Caveats: Where to Store Data on the database container documentation](https://hub.docker.com/_/mariadb) re. how to make it persistent instead of ephemeral.<br>
Tomcat v9 is only required if you wish to deploy the Fineract WAR to a separate external servlet container. Note that you do not require to install Tomcat to develop Fineract, or to run it in production if you use the self-contained JAR, which transparently embeds a servlet container using Spring Boot. (Until FINERACT-730, Tomcat 7/8 were also supported, but now Tomcat 9 is required.)
-IMPORTANT: if you use MySQL or MariaDB
+<br>IMPORTANT: If you use MySQL or MariaDB
============
-Recently (after release 1.7.0) we introduced improved date time handling in Fineract. Date time is from now on stored in UTC and we are enforcing UTC timezone even on the JDBC driver, e. g. for MySQL:
+Recently (after release `1.7.0`), we introduced improved date time handling in Fineract. Date time is from now on stored in UTC and we are enforcing UTC timezone even on the JDBC driver, e. g. for MySQL:
```
serverTimezone=UTC&useLegacyDatetimeCode=false&sessionVariables=time_zone=‘-00:00’
@@ -61,7 +62,7 @@ If a previously used Fineract instance didn't run in UTC (backward compatibility
__RECOMMENDATION__: you need to shift all dates in your database by the timezone offset that your Fineract instance used.
-Instructions how to run for local development
+<br>INSTRUCTIONS: How to run for local development
============
Run the following commands:
@@ -70,7 +71,7 @@ Run the following commands:
1. `./gradlew bootRun`
-Instructions to build the JAR file
+<br>INSTRUCTIONS: How to build the JAR file
============
1. Clone the repository or download and extract the archive file to your local directory.
2. Run `./gradlew clean bootJar` to build a modern cloud native fully self contained JAR file which will be created at `fineract-provider/build/libs` directory.
@@ -86,7 +87,7 @@ The tenants database connection details are configured [via environment variable
java -jar fineract-provider.jar
-Security
+<br>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.
@@ -103,7 +104,7 @@ FINERACT_SECURITY_OAUTH_ENABLED=false
java -Dfineract.security.basicauth.enabled=true -Dfineract.security.oauth.enabled=false -jar fineract-provider.jar
```
-OAuth2 Authentication
+<br>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):
@@ -116,7 +117,7 @@ FINERACT_SECURITY_OAUTH_ENABLED=true
java -Dfineract.security.basicauth.enabled=false -Dfineract.security.oauth.enabled=true -jar fineract-provider.jar
```
-Two Factor Authentication
+TWO FACTOR AUTHENTICATION (2FA)
------------
You can also enable 2FA authentication. Depending on how you start Fineract add the following:
@@ -130,7 +131,7 @@ FINERACT_SECURITY_2FA_ENABLED=true
```
-Instructions to build a WAR file
+<br>INSTRUCTIONS: How to build a WAR file
============
1. Clone the repository or download and extract the archive file to your local directory.
2. Run `./gradlew :fineract-war:clean :fineract-war:war` to build a traditional WAR file which will be created at `fineract-war/build/libs` directory.
@@ -141,7 +142,7 @@ We recommend using the JAR instead of the WAR file deployment, because it's much
Note that with the 1.4 release the tenants database pool configuration changed from Tomcat DBCP in XML to an embedded Hikari, configured by environment variables, see above.
-Instructions to execute Integration Tests
+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.
@@ -151,7 +152,7 @@ Run the following commands:
1. `./gradlew clean test`
-Instructions to run and debug in Eclipse IDE
+INSTRUCTIONS: How to run and debug in Eclipse IDE
============
It is possible to run Fineract in Eclipse IDE and also to debug Fineract using Eclipse's debugging facilities.
@@ -169,7 +170,7 @@ You can also use Eclipse Junit support to run tests in Eclipse (Run As->Junit Te
Finally, modifying source code in Eclipse automatically triggers hot code replace to a running instance, allowing you to immediately test your changes
-Instructions to run using Docker and docker-compose
+INSTRUCTIONS: How to run using Docker and docker-compose
===================================================
It is possible to do a 'one-touch' installation of Fineract using containers (AKA "Docker").
@@ -213,7 +214,7 @@ Please check `application.properties` to see which connection pool settings can
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.
-SSL configuration
+<br>SSL CONFIGURATION
=================
Read also [the HTTPS related doc](fineract-doc/src/docs/en/deployment.adoc#https).
@@ -222,16 +223,16 @@ By default SSL is enabled, but all SSL related properties are now tunable. SSL c
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.
-Tomcat configuration
+<br>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`.
-Instructions to run on Kubernetes
+<br>INSTRUCTIONS: How to run on Kubernetes
=================================
-General Clusters
+<br>General Clusters
----------------
You can also run Fineract using containers on a Kubernetes cluster.
@@ -262,7 +263,7 @@ Now to run a new Fineract instance on Minikube you can simply:
1. `minikube service fineract-server --url --https`
1. Fineract is now running at the printed URL (note HTTP), which you can check e.g. using:
- http --verify=no --timeout 240 --check-status get $(minikube service fineract-server --url --https)/fineract-provider/actuator/health
+ http --verify=no --timeout 240 --check-status get $(minikube service fineract-server --url --https)/fineract-provider/actuator/health
To check the status of your containers on your local minikube Kubernetes cluster, run:
@@ -285,7 +286,7 @@ To shutdown and reset your cluster, run:
We have [some open issues in JIRA with Kubernetes related enhancement ideas](https://jira.apache.org/jira/browse/FINERACT-783?jql=labels%20%3D%20kubernetes%20AND%20project%20%3D%20%22Apache%20Fineract%22%20) which you are welcome to contribute to.
-Instructions to download Gradle wrapper
+INSTRUCTIONS: How to download Gradle wrapper
============
The file gradle/wrapper/gradle-wrapper.jar binary is checked into this projects Git source repository,
but won't exist in your copy of the Fineract codebase if you downloaded a released source archive from apache.org.
@@ -298,13 +299,13 @@ In that case, you need to download it using the commands below:
curl --insecure -L https://github.com/apache/fineract/raw/develop/gradle/wrapper/gradle-wrapper.jar > gradle/wrapper/gradle-wrapper.jar
-Instructions to run Apache RAT (Release Audit Tool)
+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
-Instructions to enable ActiveMQ
+INSTRUCTIONS: How to enable ActiveMQ
============
Messaging configuration is disabled by default. If you want to enable it and register some message listeners, application needs to be started with the proper Spring profile, ie `-Dspring.profiles.active=activeMqEnabled` (or one of the other Spring ways to configure it).
@@ -360,7 +361,7 @@ As discussed in [LEGAL-462](https://issues.apache.org/jira/browse/LEGAL-462), th
complies with the [Apache Software Foundation third-party license policy](https://www.apache.org/legal/resolved.html).
-Apache Fineract Platform API
+<br><br>APACHE FINERACT PLATFORM API
============
The API for Fineract is documented in [apiLive.htm](fineract-provider/src/main/resources/static/api-docs/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).
@@ -370,7 +371,7 @@ The Swagger documentation (work in progress; see [FINERACT-733](https://issues.a
Apache Fineract supports client code generation using [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) based on the [OpenAPI Specification](https://swagger.io/specification/). For more instructions on how to generate the client code, check [docs/developers/swagger/client.md](docs/developers/swagger/client.md).
-API clients (Web UIs, Mobile, etc.)
+<br>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
@@ -379,7 +380,7 @@ API clients (Web UIs, Mobile, etc.)
* https://github.com/openMF has more related proejcts
-Online Demos
+<br>ONLINE DEMOS
============
* [fineract.dev](https://www.fineract.dev) always runs the latest version of this code
@@ -387,8 +388,7 @@ Online Demos
* [Swagger-UI Demo video](https://www.youtube.com/watch?v=FlVd-0YAo6c) This is a demo video for Swagger-UI documentation, more information [here](https://github.com/apache/fineract#swagger-ui-documentation).
-
-Developers
+<br>DEVELOPERS
============
Please see <https://cwiki.apache.org/confluence/display/FINERACT/Contributor%27s+Zone> for the developers wiki page.
@@ -399,42 +399,42 @@ Please see <https://cwiki.apache.org/confluence/display/FINERACT/How-to+articles
Please visit [our JIRA Dashboard](https://issues.apache.org/jira/secure/Dashboard.jspa?selectPageId=12335824) to find issues to work on, see what others are working on, or open new issues.
-Video Demonstration
+<br>VIDEO DEMONSTRATION
============
Apache Fineract / Mifos X Demo (November 2016) - <https://www.youtube.com/watch?v=h61g9TptMBo>
-Swagger-UI Documentation
+<br>SWAGGER UI DEMONSTRATION
============
We use Swagger-UI to generate and maintain our API documentation, you can see the demo video [here](https://www.youtube.com/watch?v=FlVd-0YAo6c) or a live version
[here](https://demo.fineract.dev/fineract-provider/swagger-ui/index.html). If you interested to know more about Swagger-UI you can check their [website](https://swagger.io/).
-Governance and Policies
+<br>GORVENANCE AND POLICIES
=======================
[Becoming a Committer](https://cwiki.apache.org/confluence/display/FINERACT/Becoming+a+Committer)
documents the process through which you can become a committer in this project.
-Error Handling Guidelines
+<br>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 inste [...]
* 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 [JUnit's Assert.assertThrows()](https://github.com/junit-team/junit4/wiki/Exception-testing) (but not `@Test(expected = SomeException.class)`).
* Never catch `NullPointerException` & Co.
-Logging Guidelines
+<br>LOGGING GUIDELINES
------------------
* We use [SLF4J](http://www.slf4j.org) as our logging API.
* Never, ever, use `System.out` and `System.err` or `printStackTrace()` anywhere, but always `LOG.info()` or `LOG.error()` instead.
* Use placeholder (`LOG.error("Could not... details: {}", something, exception)`) and never String concatenation (`LOG.error("Could not... details: " + something, exception)`)
* Which Log Level is appropriate?
- * `LOG.error()` should be used to inform an "operator" running Fineract who supervises error logs of an unexpected condition. This includes technical problems with an external "environment" (e.g. can't reach a database), and situations which are likely bugs which need to be fixed in the code. They do NOT include e.g. validation errors for incoming API requests - that is signaled through the API response - and does (should) not be logged as an error. (Note that there is no _FATAL_ le [...]
- * `LOG.warn()` should be using sparingly. Make up your mind if it's an error (above) - or not!
- * `LOG.info()` can be used notably for one-time actions taken during start-up. It should typically NOT be used to print out "regular" application usage information. The default logging configuration always outputs the application INFO logs, and in production under load, there's really no point to constantly spew out lots of information from frequently traversed paths in the code about what's going on. (Metrics are a better way.) `LOG.info()` *can* be used freely in tests though.
- * `LOG.debug()` can be used anywhere in the code to log things that may be useful during investigations of specific problems. They are not shown in the default logging configuration, but can be enabled for troubleshooting. Developers should typically "turn down" most `LOG.info()` which they used while writing a new feature to "follow along what happens during local testing" to `LOG.debug()` for production before we merge their PRs.
- * `LOG.trace()` is not used in Fineract.
+ * `LOG.error()` should be used to inform an "operator" running Fineract who supervises error logs of an unexpected condition. This includes technical problems with an external "environment" (e.g. can't reach a database), and situations which are likely bugs which need to be fixed in the code. They do NOT include e.g. validation errors for incoming API requests - that is signaled through the API response - and does (should) not be logged as an error. (Note that there is no _FATAL_ [...]
+ * `LOG.warn()` should be using sparingly. Make up your mind if it's an error (above) - or not!
+ * `LOG.info()` can be used notably for one-time actions taken during start-up. It should typically NOT be used to print out "regular" application usage information. The default logging configuration always outputs the application INFO logs, and in production under load, there's really no point to constantly spew out lots of information from frequently traversed paths in the code about what's going on. (Metrics are a better way.) `LOG.info()` *can* be used freely in tests though.
+ * `LOG.debug()` can be used anywhere in the code to log things that may be useful during investigations of specific problems. They are not shown in the default logging configuration, but can be enabled for troubleshooting. Developers should typically "turn down" most `LOG.info()` which they used while writing a new feature to "follow along what happens during local testing" to `LOG.debug()` for production before we merge their PRs.
+ * `LOG.trace()` is not used in Fineract.
Pull Requests
-------------