diff --git a/build.gradle b/build.gradle index 56ed56607..c21075fcd 100644 --- a/build.gradle +++ b/build.gradle @@ -903,6 +903,10 @@ cyclonedxBom { includeLicenseText = true } +tasks.withType(org.cyclonedx.gradle.CyclonedxDirectTask).configureEach { + includeMetadataResolution.set(false) +} + tasks.register('printSourceSetInformation') { doLast { sourceSets.each { srcSet -> diff --git a/fineract-doc/.asciidoctorconfig b/fineract-doc/.asciidoctorconfig new file mode 100644 index 000000000..db9562053 --- /dev/null +++ b/fineract-doc/.asciidoctorconfig @@ -0,0 +1,25 @@ +// 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. +// +:years: 2015-2026 +:revnumber: 1.14.0 +:draft: true +:rootdir: {asciidoctorconfigdir}/.. +:generated: {asciidoctorconfigdir}/build/generated/asciidoc +:diagramsdir: {asciidoctorconfigdir}/src/docs/en/diagrams +:imagesdir: {asciidoctorconfigdir}/src/docs/en/images +:icons: font diff --git a/fineract-doc/antora.yml b/fineract-doc/antora.yml new file mode 100644 index 000000000..62ad0c85c --- /dev/null +++ b/fineract-doc/antora.yml @@ -0,0 +1,26 @@ +# 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. +# +name: modules +title: Fineract Docs +version: '~' +#display_version: '' +nav: +- modules/ROOT/nav.adoc +- modules/contributor/nav.adoc +- modules/committer/nav.adoc +- modules/community/nav.adoc diff --git a/fineract-doc/modules/ROOT/nav.adoc b/fineract-doc/modules/ROOT/nav.adoc new file mode 100644 index 000000000..d85976135 --- /dev/null +++ b/fineract-doc/modules/ROOT/nav.adoc @@ -0,0 +1,3 @@ +.Project Overview +* xref:index.adoc[Introduction] +* xref:faq.adoc[FAQs] diff --git a/fineract-doc/modules/ROOT/pages/faq.adoc b/fineract-doc/modules/ROOT/pages/faq.adoc new file mode 100644 index 000000000..781822b35 --- /dev/null +++ b/fineract-doc/modules/ROOT/pages/faq.adoc @@ -0,0 +1,88 @@ +== What is this project about? +At Apache Fineract, our mission is to build, maintain and enhance a cloud-ready core banking system for robust, scalable, and secure operations of financial institutions. We believe in financial services for everyone, including the unbanked and underbanked. + +The domain of fineract includes accounts, held by customers, with transactions made to those accounts. The types of accounts include credit accounts (e.g. loans to customers) and debit accounts (current accounts and savings accounts), and for credit accounts there are different kinds of interest rate schemes or shared profit schemes. There is other functionality that supports use cases for teller operations, basic treasury management, accounting, portfolio management, authentication, account opening (including KYC), and similar topics that are common to a retail banking operation. + +Initially aimed at Microfinance Institutions (MFIs), Savings Cooperatives, and Credit Unions, the fineract solution is not limited to those specific institutions. A number of finTech innovators have used fineract as their backend solution for offering "Direct Banking" or "Neo-Banking" solutions as well as for "Agent Management" in some contexts. The backend account transaction system is a common requirement in many systems in financial services. + +Fineract was donated by Mifos.org, a US based charity with a financial inclusion mission which had developed the fully featured MifosX and released as open source in 2010 (which was generation 2 of the Mifos software). While many members of the PMC trace their involvement to the project to financial inclusion, the intent of the project is to attract a range of innovators involved in offering account services to consumers everywhere. Financial services should be available to all. + +Open source allows for the project to build the needed building blocks that all kinds of financial institutions can use but we anticipate an ecosystem of providers taking this code and building solutions on top of it. We encourage that and fully expect those builders to send their development priorities and in-house dev teams to the project. We require that virtuous cycle. + +We imagine a world where financial services are offered by a wide range of providers using commodity open source software utilizing the most modern approaches. + +== Who is using fineract? + +(For clarity, those using the mifos.org released solutions, prior to incubation at apache foundation, are not counted in this project.) Fineract is used by many small to medium sized financial institutions in dozens of countries. Larger institutions are considering the use of fineract side-by-side with their existing core banking solution (CBS). The side-by-side strategy allows for innovative offerings to be done without the licensing costs usually associated with commercial CBS. Fineract has also been adopted by finTechs to be the backend transaction account engine, and is being used in testing-lab environments to assist with system integrations. + +With proper hosting and front end dev, Fineract is suitable to Credit Unions, Microfinance Institutions, Agent Banking solutions, Savings Associations, Building Societies, Cooperatives, small Commercial Banks, NeoBanks, and Direct Banking solutions. Our vision is that these institutions may download and use directly, but perhaps more likely, to hire a provider or integrator to provide the complete solution to them. Our users are thus both the institutions where fineract is in place and the system integrators and vendors where fineract is a significant part of their offering. + +Check out our powered-by Fineract page. + +== Is this Mifos? +The Mifos Initiative, a 501c3 US Charity, contributed the code that forms the basis of fineract (this was developed by a community of mifos developers over several years), and the Mifos Initiative remains involved with a number of front end implementations (project wrapper in apache parlance) 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, if you are looking for information on the latest mifos release, please proceed to: https://mifos.org/take-action/get-mifos/#download. Please understand that devs at fineract may not respond to questions about mifos code. + +== Is there a front end? Where are the reports? +Fineract just contains the back-end platform and APIs. Front end development is intentionally left out of the fineract1.x project to encourage the use of software integrators to develop their own front end solutions. Mifos has a number of open source front end User Interfaces (UIs) projects for reference that sit on top of fineract1.x including MifosX Community app (AngularJS project), reporting through Pentaho and there are also client and staff-facing mobile apps. Note that demo servers running Fineract will often be packaged with the open source front end of Mifos (see openmf.github.org) and that front end may not include all of the most recent features developed in fineract. + +== What is the difference between Fineract and Fineract-CN? +Fineract CN was a separate codebase and is now deprecated/archived. +Current Apache Fineract development is focused on Fineract 1.x in this repository. +Fineract1.x, prior to its donation to Apache, was called mifosX and by design consists of a "headless" solution focused on APIs. + +== Do I have to get the code to use the solution? +If all you want is to use the solution, or to demo it, we recommend you use one of the available builds rather than setting up a development environment yourself. The builds, found at http://fineract.apache.org/ (Downloads) are provided for convenience and should not be used in a production environment without fully working out details of operations (e.g. data backup) and security. Also, Mifos volunteers continue to post builds for specific hosting solutions at https://en.wikipedia.org/wiki/Mifos_X (e.g. Azure and AWS). + +== What is the process for getting the code and setting up a development environment? +Please see Contributor's Zone, essentially you need to get your environment ready, then download from the github source and use one of the common IDEs. + +In general we ask that you take the time to read the instructions and familiarize yourself with the listserv before posting questions about building the solution. You can search the listserv archives at https://lists.apache.org/list.html?fineract.apache.org . If you find something missing from the instructions, we welcome contributions of that sort as well. Note that the listserv search is timebound, so that for example this search gets 24 months: https://lists.apache.org/list.html?dev@fineract.apache.org:lte=24M:pentaho (see lte=24M) and search term is "pentaho". + +== How do I get up to speed on development tasks? +Please see Contributor's Zone + +Issue tracker: + +fineract1.x at https://issues.apache.org/jira/projects/FINERACT/summary +A good thing to do is to review an open ticket, especially one with back and forth between devs on the listserv or one that is scheduled for an upcoming release. It is also useful to review existing pull requests (PRs). Pull Requests (PRs) are found here → https://github.com/apache/fineract/pulls + +== What is our Consensus approach? +Every open source project has to adopt some way to come to agreement on new features, new code enhancements, new project directions and fineract now uses a lazy consensus approach. In this approach, the changes and issues are raised and people are given time to reject or discuss the changes, and we rely on contributors to fully vett changes in an appropriate way and have their code reviewed. + +This is documented at Committer's Zone and Changing Processes . Please note that we expect discussion on the listserv to be the primary mode of communication. "If it didn't happen on the list, it didn't happen." + +== I'm new to Open Source, what is this all about? +Welcome. You may want to first read something about how open source projects function (like this) and in particular how the Apache Foundation works. https://www.apache.org/foundation/how-it-works.html. If you are interested in contributing to the project, a good way to get started is to subscribe to the listserv, review the functional specs on this wiki, browse the issue tickets, and start to play around with a build of the software. Open source can be a great way to find your community, contribute and get feedback, and put your work into public view. This is true for both code and the variety of other content needed. + +== Where do I find .... +We get a lot of questions about where to find documentation or the answer to a specific thing. We do appreciate when people take the time to try to find the answer before asking. Once you have new content to propose, a ticket or an improvement to documentation, we encourage you to get involved on that. Not all contributions are code, take, for example, this FAQ. + +== Where do I get the Pentaho Reports? +Fineract does not ship Pentaho reports or the related libraries, due to compliance issues with Apache licence. Please head over to the Mifos community who maintains distributions of Fineract that include pentaho. + +== How do I set this up on my machine? +First, are you a developer? If you are not, then you may not want to run fineract on your local machine. Instead you may want to find one of the demo environments already established or make use of one of the existing cloud deployments. Also, fineract does not come with a native front end UX. The UX is part of the distributions that are provided by third parties, including the aforementioned Mifos Community. + +If you are a developer, then please see how to set up sections on the wiki. + +Fineract User Zone + + +== How do I get something changed in the code? How do I get a feature added? +The project is always interested in ideas about features. That said, we notice some people expect that a feature requested is automatically developed and incorporated. That is not the case. If you have code to suggest, first discuss on the list, add an issue to the issue tracker, and then find someone to help you contribute that feature. You are still not guaranteed that your feature will make it in, because it must also be accepted by the community. + +== I have a great idea for a collaboration tool for the community, how do I make that happen? +We know there are lots of great collaboration tools. To keep things consistent across Apache, there is a philosophy of using current tools rather than cutting edge, while acknowledging there's always something new and cool. We use email listservs for their backwards compatibility, searchability, and simplicity. This wiki has hooks to the issue tracker (JIRA) and github commit entries hook to the same JIRA tickets for all Pull Requests (PRs). A good flow is: + +email discourse >> wiki entry |or| issue (JIRA) + +development sprint >> Pull Request >> email list for review and confirmation + +== I represent a Company and want to contribute, how do I do that? +As stated on http://www.apache.org/foundation/how-it-works.html, "companies and individuals can donate resources and be assured that those resources will be used for the public benefit". If you have developers working at your company, you may encourage them to work on the project, but note that "All of the ASF including the board, the other officers, the committers, and the members, are participating as individuals." and further "the ASF does not allow corporations to participate directly in Apache project management or other governance activities at the ASF; only individuals." http://community.apache.org/projectIndependence.html + +== I found a security flaw, where do I report that? +Security is a mandatory feature in Apache projects. Please report your bug to security AT fineract.apache.org. + +== How do I raise a difficult or sensitive topic? +In general, you are invited to discuss problems you see with the Fineract project openly, on the dev@fineract.apache.org list. In some limited cases, please send an email to private @ fineract.apache.org. Addressing problems early and openly will keep most problems from becoming too large to handle. A good rule of thumb is to compose and then wait overnight before firing off that flame. diff --git a/fineract-doc/modules/ROOT/pages/index.adoc b/fineract-doc/modules/ROOT/pages/index.adoc new file mode 100644 index 000000000..ac12e5499 --- /dev/null +++ b/fineract-doc/modules/ROOT/pages/index.adoc @@ -0,0 +1,41 @@ += Introduction + +== Platform for Digital Financial Services + +Apache Fineract (\’fīn-,ә-,rakt\) is open source software for financial services. + +At Apache Fineract, our mission is to build, maintain and enhance a cloud-ready core banking system for robust, scalable, and secure operations of financial institutions. + +We believe in financial services for everyone, including and especially for the unbanked and underbanked. + +We primarily build the backend system, the headless application. + +== About + +Apache Fineract can be deployed in any environment: cloud or on-premise. It can support front end interfaces on or offline, mobile or PC. It’s extensible enough to support any organizational type or delivery channel, and flexible enough to support any product, service, or lending methodology. For any organization, big or small, it provides the client data management, loan and savings portfolio management, integrated real time accounting, and social and financial reporting needed to bring digital financial services to a modern connected world. + +Fineract 1.x compares well to other core banking systems and draws from requirements in credit unions, microfinance institutions, and small non-banking financial institutions. Features include flexible product configuration, KYC documentation support, business rule sets, payment transactions, and portfolio management. It includes an open API that dates to 2011 and is deployed in relatively high transaction volume environments. + +Fineract CN operates on the principle that financial services are an innovative space and so each fineract microservice encapsulates a domain that can be combined with other microservices to create new platform offerings. Fineract CN microservices can be combined to create new software platforms for digital financial service providers. Fineract CN is still in its early days, but preliminary tests have shown that a simple single-instance laptop deployment of Fineract CN can process over 1000 transactions/second. Fineract CN also includes a fully Apache-licensed backoffice UI. + +Fineract 1.x began incubation at Apache in December 2015 and is used by an active community of companies who build solutions for both financial inclusion and fintech innovation. + +== Contribute + +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. + +== Mailing Lists + +Users & Developers + +If you use, build on top of, deploy or are building contributions and modifications to Apache Fineract, this is the list for you. +To subscribe, send a blank email to dev-subscribe@fineract.apache.org. +To unsubscribe later, just send a blank email to dev-unsubscribe@fineract.apache.org. +You can also read the archives on lists.apache.org or on MarkMail.org. +Commits + +This list receives an email whenever new code is contributed to Apache Fineract. +To subscribe, send a blank email to commits-subscribe@fineract.apache.org. +You can also read the archives. diff --git a/fineract-doc/modules/committer/nav.adoc b/fineract-doc/modules/committer/nav.adoc new file mode 100644 index 000000000..8c7e6da61 --- /dev/null +++ b/fineract-doc/modules/committer/nav.adoc @@ -0,0 +1,2 @@ +.Committer Zone +* xref:becoming-a-committer.adoc[Becoming a Committer] diff --git a/fineract-doc/modules/committer/pages/becoming-a-committer.adoc b/fineract-doc/modules/committer/pages/becoming-a-committer.adoc new file mode 100644 index 000000000..c41ae3aba --- /dev/null +++ b/fineract-doc/modules/committer/pages/becoming-a-committer.adoc @@ -0,0 +1,58 @@ +Being a committer in FINERACT is a responsibility that we wish to encourage as many good contributors as possible to share with us. It is also an honor which is earned by good behavior. + +Apache explains what values underlie Apache community work here: https://community.apache.org/contributors/ + +FINERACT will designate contributors to committers via the following process. + +* A current PMC member will decide to sponsor a contributor. +* The sponsor will propose via the private mailing list, that a contributor be made a committer. The sponsor should explain why he or she believes the contributor should be made a committer. At this point it would be unkind to inform the contributor in case the proposal fails the vote. +* If within 72 hours of the proposal, no committers have vetoed the proposal, the proposal is accepted. +* The sponsor will ask the contributor if he or she wishes to become a committer. +* If contributor so desires, the sponsor will set in motion the processes necessary to add a new committer to FINERACT. +* If a contributor is vetoed there is no need to inform him or her that a vote occurred. Depending on the reason for a veto, the question may be raised again at a later date. + +Because committers determine who will become committers, they need to be able to recognize good committers. A good committer also has other qualities. + +== Developer committer qualities + +To be made a developer committer, a contributor should have developed experience with FINERACT by + +* creating bug fixes or programming features, +* producing multiple high quality code changes as determined by an existing committer using the Code Review Guide, +* owning and fixing their own mistakes, and +* mentoring other contributors. + +== Community Liaison Committer qualities + +To be made a community liaison committer, a contributor should have developed experience with FINERACT by + +* helping other users learn to use FINERACT, or +* helping programmers learn what users need by providing detailed business requirements and use cases required for functional specifications, or +* testing FINERACT for correctness, robustness, scaleability, security, or usability, and reporting bugs and issues found, or +* connecting users with complementary needs with each other on the list, or +* supporting implementers and users of FINERACT with best practices and lessons learned from practical implementation, or +* writing documentation and tutorials for usage of FINERACT and design of financial services, +* owning and fixing their mistakes, and +* mentoring other contributors. + +== Developer committer rights and responsibilities + +* Everything listed in http://www.apache.org/dev/new-committers-guide.html +* Reviewing code before it is committed using the Code Review Guide. +* Reviewing code for other committers after it is committed. +* Taking part in conversations on the dev mailing list when he or she has something to contribute. +* Keeping all decision-making processes transparent for all project participants. +* Community Liaison Committer rights and responsibilities +* Everything listed in http://www.apache.org/dev/new-committers-guide.html +* Prioritizing and refining user stories and tickets on JIRA. +* Moderating and maintaining functional documentation on FINERACT. +* Taking part in conversations on the dev mailing list when he or she has something to contribute. +* Keeping all decision-making processes transparent for all project participants. + +== PMC member rights and responsibilities + +* Taking part in conversations on the private mailing list and keeping those conversations private. +* Proposing new committers and new PMC members. +* Representing Apache Fineract to the ASF Board. +* Protecting the Apache Fineract brand from misuse +* Keeping all decision-making processes transparent for all project participants. diff --git a/fineract-doc/modules/community/nav.adoc b/fineract-doc/modules/community/nav.adoc new file mode 100644 index 000000000..32395874c --- /dev/null +++ b/fineract-doc/modules/community/nav.adoc @@ -0,0 +1,3 @@ +.Community +* xref:index.adoc[Introduction] +* xref:governance.adoc[Governance] diff --git a/fineract-doc/modules/community/pages/governance.adoc b/fineract-doc/modules/community/pages/governance.adoc new file mode 100644 index 000000000..28f81ace1 --- /dev/null +++ b/fineract-doc/modules/community/pages/governance.adoc @@ -0,0 +1,3 @@ +== PMC + +== How decisions are made diff --git a/fineract-doc/modules/community/pages/index.adoc b/fineract-doc/modules/community/pages/index.adoc new file mode 100644 index 000000000..66293ff52 --- /dev/null +++ b/fineract-doc/modules/community/pages/index.adoc @@ -0,0 +1 @@ +== About the project diff --git a/fineract-doc/modules/contributor/nav.adoc b/fineract-doc/modules/contributor/nav.adoc new file mode 100644 index 000000000..a5cf95902 --- /dev/null +++ b/fineract-doc/modules/contributor/nav.adoc @@ -0,0 +1,9 @@ +.Contributors Zone +* xref:take-your-first-steps.adoc[Getting started] +* xref:submitting-a-pull-request.adoc[Guidelines for submitting a PR] +* xref:key-design-principles.adoc[Key Design principles] +* xref:coding-conventions.adoc[Coding Conventions] +* xref:checkstyle-and-spotless.adoc[Checkstyle and Spotless] +* xref:error-handling.adoc[Error handling] +* xref:logging-guidelines.adoc[Logging guidelines] + diff --git a/fineract-doc/modules/contributor/pages/checkstyle-and-spotless.adoc b/fineract-doc/modules/contributor/pages/checkstyle-and-spotless.adoc new file mode 100644 index 000000000..165bb9b09 --- /dev/null +++ b/fineract-doc/modules/contributor/pages/checkstyle-and-spotless.adoc @@ -0,0 +1,24 @@ += Checkstyle and Spotless + +The project enforces code conventions using **Checkstyle** and **Spotless**. + +== Configuration Files +* **Checkstyle**: `config/checkstyle/checkstyle.xml` +* **Spotless**: `config/fineractdev-formatter.xml` + +These tools run automatically during the Gradle build and will fail the build if violations are detected. + +== Fixing Violations +To automatically fix most formatting issues (Spotless and some Checkstyle), run: + +[source,bash] +---- +./gradlew spotlessApply +---- + +To check for Spotless violations only: + +[source,bash] +---- +./gradlew spotlessCheck +---- \ No newline at end of file diff --git a/fineract-doc/modules/contributor/pages/coding-conventions.adoc b/fineract-doc/modules/contributor/pages/coding-conventions.adoc new file mode 100644 index 000000000..ea70d3760 --- /dev/null +++ b/fineract-doc/modules/contributor/pages/coding-conventions.adoc @@ -0,0 +1,24 @@ += Coding Conventions + +== How We Code + +We recommend that you configure your favourite Java IDE to match the project conventions. + +=== Eclipse IDE +For Eclipse, you can go to `Window > Java > Code Style` and import: +* `config/fineractdev-formatter.xml` under the formatter section. +* `config/fineractdev-cleanup.xml` under the cleanup section. + +=== IntelliJ IDEA +For IntelliJ, the project settings for code style should be automatically imported from the Gradle configuration. + +== Formatting + +We use Spotless to enforce code formatting. You can run the following command to automatically fix formatting violations: + +[source,bash] +---- +./gradlew spotlessApply +---- + +This ensures consistent code style across the entire codebase. \ No newline at end of file diff --git a/fineract-doc/modules/contributor/pages/error-handling.adoc b/fineract-doc/modules/contributor/pages/error-handling.adoc new file mode 100644 index 000000000..d0343c675 --- /dev/null +++ b/fineract-doc/modules/contributor/pages/error-handling.adoc @@ -0,0 +1,22 @@ += Error Handling Guidelines + +== Exception Handling + +* **Log or Rethrow**: When catching exceptions, either rethrow them or log them. Include the root cause. ++ +[source,java] +---- +catch (SomeException e) { + throw new AnotherException("..details..", e); + // OR + LOG.error("...context...", e); +} +---- + +* **No Empty Catch Blocks**: Completely empty catch blocks are VERY suspicious. Do not "swallow" exceptions unless you are absolutely sure. + * Such "normal exceptions" are often indications of using the wrong API (e.g., throwing an exception for an expected condition instead of returning empty/optional). + +* **Tests**: In tests, typically propagate exceptions (`throws SomeException`) so the test fails if it occurs. + * To test for an exception, use `Assert.assertThrows()`. + +* **NullPointer**: Never catch `NullPointerException`. Fix the code instead. \ No newline at end of file diff --git a/fineract-doc/modules/contributor/pages/key-design-principles.adoc b/fineract-doc/modules/contributor/pages/key-design-principles.adoc new file mode 100644 index 000000000..0c393b4e2 --- /dev/null +++ b/fineract-doc/modules/contributor/pages/key-design-principles.adoc @@ -0,0 +1,54 @@ += Key Design Principles + +== RESTful API + +The platform exposes all its functionality via a *practically-RESTful API*, that communicates using JSON. + +We use the term *practically-RESTful* in order to make it clear we are not trying to be fully REST compliant but still maintain important RESTful attributes like: + +* **Stateless**: The platform maintains no conversational or session-based state. This allows for horizontal scaling. +* **Resource-oriented**: The API is focused around a set of resources using HTTP vocabulary and conventions (GET, PUT, POST, DELETE, HTTP status codes). This results in a simple and consistent API for clients. + +See the online API Documentation for more details. + +== Multi-tenanted + +The Fineract platform has been developed with support for multi-tenancy at the core of its design. This means that it is just as easy to use the platform for Software-as-a-Service (SaaS) type offerings as it is for local installations. + +The platform uses an approach that isolates an FI's data per database/schema. + +== Extensible + +While each tenant will have a set of core tables, the platform tables can be extended in different ways for each tenant through the use of Data tables functionality. + +== Package Structure + +The intention is for platform code to be packaged in a "vertical slice" way (as opposed to technical layers like controller/service/dao). + +Source code location: `fineract-provider/src/main/java/org/apache/fineract` + +Major modules include: +* accounting +* useradministration +* infrastructure +* portfolio +** charge +** client +** fund +** loanaccount + +Within each vertical slice, there is a common packaging structure: +* `api` - `XXXApiResource.java` (REST API implementation) +* `handler` - `XXXCommandHandler.java` (Specific handlers) +* `service` - Read + Write services for the functional area +* `domain` - Object-Oriented concepts (Entities) +* `data` - Data Transfer Objects (DTOs) +* `serialization` - JSON conversion logic + +== Maker-Checker (Four-Eyes Principle) + +Enables applications to support a maker-checker style workflow process. Commands that pass validation will be persisted. Maker-checker can be enabled/disabled at a fine-grained level for any state-changing API. + +== Fine-Grained Access Control + +A fine-grained permission is associated with each API. Administrators have granular control over what roles or users have access to specific functions. \ No newline at end of file diff --git a/fineract-doc/modules/contributor/pages/logging-guidelines.adoc b/fineract-doc/modules/contributor/pages/logging-guidelines.adoc new file mode 100644 index 000000000..ffab08fc2 --- /dev/null +++ b/fineract-doc/modules/contributor/pages/logging-guidelines.adoc @@ -0,0 +1,34 @@ += Logging Guidelines + +== Library +We use http://www.slf4j.org[SLF4J] as our logging API. + +* **Never use System.out/err**: Always use `LOG.info()` or `LOG.error()`. +* **Use Placeholders**: Use parameterized logging instead of string concatenation. ++ +[source,java] +---- +// GOOD +LOG.error("Could not... details: {}", something, exception); + +// BAD +LOG.error("Could not... details: " + something, exception); +---- + +== Log Levels + +* **`LOG.error()`**: Use for unexpected conditions that need operator attention. + * Includes technical problems (database unreachable) and bugs. + * Does NOT include validation errors (which should be user responses). + * _Note_: SLF4J has no `FATAL` level; use `ERROR`. + +* **`LOG.warn()`**: Use sparingly. Decide if it's an error or not. + +* **`LOG.info()`**: Use for one-time actions (e.g., startup). + * Do NOT use for regular application usage info (use Metrics instead). + * Can be used freely in tests. + +* **`LOG.debug()`**: Use for investigation data. + * Not shown in default configuration but can be enabled for troubleshooting. + +* **`LOG.trace()`**: Not used in Fineract. \ No newline at end of file diff --git a/fineract-doc/modules/contributor/pages/submitting-a-pull-request.adoc b/fineract-doc/modules/contributor/pages/submitting-a-pull-request.adoc new file mode 100644 index 000000000..0a523105b --- /dev/null +++ b/fineract-doc/modules/contributor/pages/submitting-a-pull-request.adoc @@ -0,0 +1,62 @@ +== Submitting a Pull Request + +We encourage all community members to contribute actively to the upstream Fineract codebase. All contributions come in the form of a pull request referencing a JIRA ticket outlining the intent of the contribution. + +We request that your commit message include a FINERACT JIRA issue, recommended to be put in parentheses at the end of the first line. Start with an upper case imperative verb (not past form), and a short but concise clear description. (E.g. Add enforced HideUtilityClassConstructor checkstyle (FINERACT-821) or Fix inability to reschedule when interest accrued larger than EMI (FINERACT-1109) etc.). + +If your PR is failing to pass our CI build due to a test failure, then: + +** Understand if the failure is due to your PR or an unrelated unstable test. + +** If you suspect it is because of a "flaky" test, and not due to a change in your PR, then please do not simply wait for an active maintainer to come and help you, but instead be a proactive contributor to the project - see next steps. Do understand that we may not review PRs that are not green - it is the contributor's (that's you!) responsability to get a proposed PR to pass the build, not primarily the maintainers. + +** Search for the name of the failed test on https://issues.apache.org/jira/, e.g. for AccountingScenarioIntegrationTest you would find FINERACT-899. + +** If you happen to read in such bugs that tests were just recently fixed, or ignored, then rebase your PR to pick up that change. + +** If you find previous comments "proving" that the same test has arbitrarily failed in at least 3 past PRs, then please do yourself raise a small separate new PR proposing to add an @Disabled // TODO FINERACT-123 to the respective unstable test (e.g. #774) with the commit message mentioning said JIRA, as always. (Please do NOT just @Disabled any existing tests mixed in as part of your larger PR.) + +** If there is no existing JIRA for the test, then first please evaluate whether the failure couldn't be a (perhaps strange) impact of the change you are proposing after all. If it's not, then please raise a new JIRA to document the suspected Flaky Test, and link it to FINERACT-850. This will allow the next person coming along hitting the same test failure to easily find it, and eventually propose to ignore the unstable test. + +** Then (only) Close and Reopen your PR, which will cause a new build, to see if it passes. +Of course, we very much appreciate you then jumping onto any such bugs and helping us figure out how to fix all ignored tests! + +** Pull Request Size Limit documents that we cannot accept huge "code dump" Pull Requests, with some related suggestions. + +Guideline for new Feature commits involving Refactoring: + +[attributes] +.... +If you are submitting PR for a new Feature, and it involves refactoring, try to differentiate "new Feature code" with "Refactored" by placing them in different commits. This helps review to review your code faster. +.... + + +We have an automated Bot which marks pull requests as "stale" after a while, and ultimately automatically closes them. + + +The steps below are part of our Github pull request template as a checklist while submitting. Don't treat this as mere boxes to tick off but rather ensure you're following each step so your PR doesn't get rejected and it can merged in a timely manner: + +### Description + +Describe the changes made and why they were made. + +Ignore if these details are present on the associated [Apache Fineract JIRA ticket](https://github.com/apache/fineract/pull/1284). + + +### Checklist + +Please make sure these boxes are checked before submitting your pull request - thanks! + +- [ ] Write the commit message as described above +- [ ] Acknowledge that we will not review PRs that are not passing the build _("green")_ - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers. + +- [ ] Create/update unit or integration tests for verifying the changes made. + +- [ ] Follow coding conventions as described xref:coding-conventions.adoc[here] + +- [ ] Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes + +- [ ] Submission is not a "code dump". (Large changes can be made "in repository" via a branch. Ask on the developer mailing list for guidance, if required.) + + + diff --git a/fineract-doc/modules/contributor/pages/take-your-first-steps.adoc b/fineract-doc/modules/contributor/pages/take-your-first-steps.adoc new file mode 100644 index 000000000..235815f8f --- /dev/null +++ b/fineract-doc/modules/contributor/pages/take-your-first-steps.adoc @@ -0,0 +1,68 @@ +== Take Your First Steps + +=== Understand the basics +Not sure what a pull request is, or how to submit one? Take a look at GitHub's excellent help documentation first. + +=== Search Issues first; create an issue if necessary + +Is there already an issue that addresses your concern? Do a bit of searching in our https://issues.apache.org/jira/projects/FINERACT/issues/FINERACT-1221?filter=allopenissues[issue tracker] to see if you can find something similar. If you do not find something similar, please create a new issue before submitting a pull request unless the change is truly trivial -- for example: typo fixes, removing compiler warnings, etc. + +=== Discuss non-trivial contribution ideas with the community +If you're considering anything more than correcting a typo or fixing a minor bug, please discuss it on the mailing list before submitting a pull request. We're happy to provide guidance, but please spend an hour or two researching the subject on your own. + +== Create a Branch +=== Branch from develop +Develop currently represents work toward Apache Fineract 1.0.0. Please submit all pull requests there, even bug fixes and minor improvements. + +[source] +---- +git checkout develop +---- + +=== Use short branch names +Branches used when submitting pull requests should preferably be named according to issues prefixed FINERACT followed by a dash and the issue number, e.g. 'FINERACT-1234'. This is important, because branch names show up in the merge commits that result from accepting pull requests and should be as expressive and concise as possible. + +[source] +---- +git checkout -b [topic] +---- + +=== Pull in changes +Keep up to date + +There will be development changes to both repositories almost every day for the foreseeable future so its important to keep your fork of the software up to date with the latest changes. + +To pull in upstream changes from repository you forked: + +[source] +---- +git checkout develop +git fetch upstream +git merge upstream/develop +---- + +WARNING: You should not have any local changes on your develop branch, if you do, use rebase! + + +Once you have pulled all latest changes and your build was successful, push the just merged changes to the develop branch on your fork. + +[source] +---- +git push origin develop +---- +=== Rebasing your work +After you pulled all changes from upstream you need to rebase your topic branch with the latest code. + +[source] +---- +git checkout [topic] +git rebase develop +---- + +If you are ready push your topic branch to your GitHub account: +[source] +---- +git push origin [topic] +---- + +Now thats your changes have been pushed to your github account, follow the steps and guidelines found xref:submitting-a-pull-request.adoc[here] to submit your pull request from your git account to fineract. \ No newline at end of file diff --git a/fineract-doc/modules/development/nav.adoc b/fineract-doc/modules/development/nav.adoc new file mode 100644 index 000000000..dafed7c4e --- /dev/null +++ b/fineract-doc/modules/development/nav.adoc @@ -0,0 +1,2 @@ +.Contributor Zone +* xref:development.adoc[How to Setup Project for development] diff --git a/fineract-doc/modules/development/pages/contributor-guide.adoc b/fineract-doc/modules/development/pages/contributor-guide.adoc new file mode 100644 index 000000000..0ea30b7ea --- /dev/null +++ b/fineract-doc/modules/development/pages/contributor-guide.adoc @@ -0,0 +1,15 @@ += Welcome + +There are lots of ways to contribute to Apache Fineract: coding, testing, improving the build process and tools, or contributing to the documentation. This guide provides information that will not only help you get started as a contributor, but that you'll find handy to refer to even as an old hand. + +== Newcomers to Apache + +== Contribution Guidelines + +== Take Your First Steps + +== Key Design Principles + +== Coding Conventions + +== Getting Started Docs diff --git a/fineract-doc/modules/development/pages/development.adoc b/fineract-doc/modules/development/pages/development.adoc new file mode 100644 index 000000000..9b728c427 --- /dev/null +++ b/fineract-doc/modules/development/pages/development.adoc @@ -0,0 +1,3 @@ += Introduction + +There are lots of ways to contribute to Apache Fineract: coding, testing, improving the build process and tools, or contributing to the documentation. This guide provides information that will not only help you get started as a contributor, but that you'll find handy to refer to even as an old hand.