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 <[email protected]>
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
-------------
