Felix +1 and thank you.
Note my comments below to respond to you.
On Fri, Oct 10, 2025 at 12:53 PM Felix van Hove <[email protected]>
wrote:
Hello everyone,
I've updated the README PR draft and changed the following points of the
initial version:
1. I've replaced the mission statement, i.e. the very first part of the
README. I took the text from Javier Borkenztain's email, because it
seemed to have most votes in favor of it. Note that the title on top of
everything is still the same ("Apache Fineract: A Platform for
Microfinance"). I made a suggestion for its replacement, but there was
no discussion, as far as I can see.
I think we should just drop the tag line "a platform for microfinance" as
our mission statement is now broader.
We could replace it with "core banking and lending" but I think we don't
need a tagline in the readme.
But, we can make that change later too.
2. James Dailey, you asked for "not referencing Mifos in the Readme",
and Paul agreed. I have therefore removed all references to Mifos. I
don't think that makes sense and firmly believe it is unhelpful to
visitors (and Fineract shoots itself in the foot). I dropped the section
on API clients and demos, because I didn't see how this could possibly
be rephrased without mentioning the "Mifos" word. (Why, James, are top
representatives of vendors in the PMC okay, a roadmap (to a considerable
extent) shaped by vendor requirements is okay - but saying Mifos in the
README is not? We all have to recognize technical dependencies in
software. We should recognize all of afore as non-technical, practical
dependencies - we might like it or not.) If anyone disagrees with the
removal of the section, please make a concrete proposal - I'm more than
happy to bring it back.
*VENDORS ARE NOT REPRESENTED AT THE PMC*
We all put on our Apache Fineract(R) hat when making decisions for the
benefit of the project.
Vendors (corporate entities) are never participants in the project, only
individuals.
Those individuals may be paid by a company to work on the project, but they
should always have the "benefit of the project" in the forefront.
This is the pattern across all Apache projects. Unlike other open source
foundations, the intent is to not have a "pay to play" model.
*ROADMAP is DRIVEN BY NEEDS *
You will note in my discussion with the Community that the Roadmap items
are driven by user requirements
and roadmap items get built by devs who are paid or unpaid (contributors)
so, yes, there is a need to build consensus about what needs to be built
with the widest possible group
but also, if no one is doing the work (paid or not), then it's not a
realistic roadmap
We can only build what is both needed and contributed.
Please read:
https://community.apache.org/projectIndependence.html
"A primary purpose of the basic requirements the ASF places on its
projects is to help ensure long-lived and stable projects by having a
broad-enough community to maintain the project even in the absence of any
individual volunteer or any sea change at a major vendor in that area. The
Apache project governance model
<https://www.apache.org/foundation/governance/> is explicitly based on a
diverse community. This is different from other governance models, like the
“benevolent dictator” idea or the corporate-backed model that projects like
Eclipse use.
Please Note: These requirements apply to *Apache projects*: that is, to
individual committer and PMC member behaviors and actions within the
context of collaboratively building software products *at The Apache
Software Foundation*. By definition, “Apache project” is the
collaborative activity of building and releasing software products at the
ASF."
*MIFOS in the Readme *
What I was trying to express is that, looking around, there are no other
Apache projects that I have found where a key vendor is mentioned in the
README as a required part of the setup. I have been looking more, and
sometimes vendors are mentioned for sponsoring something (test data?), or
helping with a test instance, or something, so we could do that. But, we
need fineract to "stand on its own" without mifos... which is the
requirement.
My suggestion to you, not a requirement to you, was to find a way to
provide links to "Other related open source projects" which I see as a bit
of a compromise, as Mifos is both a vendor (in the ASF view) but also a
kind of "custodial open source non-profit" with other, but highly related,
projects. As long as there is a clear separation between "what is
Fineract" and "what is mifos", I think it's ok. But I may want others at
the ASF to weigh in on this.
I appreciate you trying to keep things clear and I think this level of
clarity about role separation is important.
So, if I understand the ASF "rules" correctly, we could "Thank Mifos for
supporting the Slack channel" with a link, but without formally saying
"this is our Fineract project slack". It does make a difference because in
the future, we may also thank abc, xyz vendors for supplying a different
slack, discord channel, test data, hackathon, etc.
3. I've removed the TOC, because Adam Monsen suggested so, although I
disagree again. More than anything else, a TOC gave future editors an
idea of where content is to be inserted (and some prior editors clearly
had not paid much attention); it gave the reader an idea of where to
look and what to expect; the times when a TOC required maintenance are
over: any change of the README is hopefully proofread by AI - in the
wake of which the TOC is updated automatically.
I guess I think that a README should never be long enough to need a Table
of Contents. But, if it needs a TOC, then why not have it?
4. In the first version, I had assembled a chapter on "GUIDELINES FOR
CONTRIBUTING CODE", based on existing sections. I have moved all of this
and much, much more to CONTRIBUTING, because Adam Monsen and I are in
favour of it, and no one seemed against it. Please read the text of
CONTRIBUTING, because I added, rephrased and restructured content.
Do you mean this link ?
https://github.com/apache/fineract/blob/develop/CONTRIBUTING.md
Initially I thought of moving significant parts of the "Instructions" to
the one-page platform documentation. (In this context, Adam Saghy and I
considered removing the section on Minikube altogether.) But I now think
we should get a first README version merged. So many changes already!
The platform documentation would profit from its own overhaul. We can
still hone small aspects of the README later. Let's get a new baseline
for the README! I have retracted the draft status.
Yes, fully agree. update readme as best we can for now. +1
But also recognize that you are helping to define the mission, vision,
community with each clarification and so it is bound to create some
discussion.
keep moving forward.
Minor, thing...I noticed a link in the top nav of the Readme to a
Deprecated page that needs some work to bring up to date.
https://cwiki.apache.org/confluence/display/FINERACT/Fineract+101
<https://cwiki.apache.org/confluence/display/FINERACT/Fineract+101>
I think it should exist in the asciidocs or be maintained in the wiki.
Which do you think?
Felix
On 10/10/2025 03:15, Paul wrote:
👍
On Thu, Oct 9, 2025 at 6:39 PM James Dailey <[email protected]> wrote:
To repeat what I wrote in the github comments...
+1
This is great progress. I would however like to be even more explicit
about not referencing Mifos in the Readme. To reference a Vendor in the
README is highly irregular in any other apache project.
I think it might be appropriate to have other open source projects
listed
somewhere... i.e. "the following projects have committed to work on or
with
Fineract - external site referenced here warning links take you away
from
Apache.org... ... then with some links to those GitHub repos. But
describing a packaging approach with Mifos (as a vendor) is not
appropriate.
It would be more appropriate to have a listing of all known vendors of
Fineract on the website, not the README.
It fundamentally is against the Vendor neutrality obligation of the
project.
On Thu, Oct 9, 2025 at 2:25 PM Adam Monsen <[email protected]> wrote:
On Fri, Oct 3, 2025 at 6:39 AM Felix van Hove <[email protected]
wrote:
https://github.com/apache/fineract/pull/5076
TL;DR - Great work so far!
2. I suggest to move some parts of the current README somewhere else.
Yes! 100% agree. I'd love to get the readme down to "one page"
(whatever
that means--let's just say *very* succinct). The rest can live in
official docs or wiki. ~50% of the existing readme content should be
moved
to the official docs and ~50% to the wiki.
( By "official docs" I mean the asciidoc sources in fineract-doc
<
https://github.com/apache/fineract/tree/develop/fineract-doc/src/docs/en>.
)
I attached my suggestion. You can view it rendered here
<https://codeberg.org/meonkeys/fineract-brief-readme> or here
<https://git.disroot.org/meonkeys/fineract-brief-readme> (wait for it
--
sometimes it takes a few seconds for the charts to render). Of course
if
you accept this it's still only a third of the work, the rest of the
work
is updating official docs, wiki, and a couple other markdown files (see
below).
- First of all, have you had a look at the CONTRIBUTING document?
Contrary to the README, it's too short. Is it okay, if I move what is
now
"Guidelines for Contributing Code" over?
Sure, or to the official docs. And CONTRIBUTING.md should be updated
and
kept short.
- Secondly, could we not move half of what is under "Instructions" now
to the documentation page (https://fineract.apache.org/docs/current/)
Yes, please do.
3. I would like to add a section "Troubleshooting", but need your
input
for it.
This can go in the official docs too, once we have content for it.
4. The current text remains extraordinarily long for a README, even if
we move some sections somewhere else. To mitigate its complexity I
have
added a hopefully better structure to it (moved sections etc.) and a
Table
of contents. Okay?
I don't want to add nor maintain a TOC. Let's just make the readme so
short we don't need one. (side note: many tools generate a TOC for you
by
scanning Markdown headings, e.g. Vim Markdown
<https://github.com/preservim/vim-markdown> and Markdown Viewer
<
https://addons.mozilla.org/en-US/firefox/addon/markdown-viewer-webext/>
).
5. I've removed and/or merged a few sections.
👍
6. I'm not happy with the current DATABASE section and its position,
suggestions welcome.
Move to wiki or official docs or axe it.
Final thought: content in STATIC_WEAVING.md should be moved to official
docs or wiki.
